docs: edits and fixes to commerce module docs (#7468)
Apply edits and fixes to the commerce modules docs
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
130de74d6d
commit
2c5ba408d4
160 files changed
+6400
-3790
No files matched your search
@@ -8,13 +8,7 @@ In this document, you’ll learn about promotion actions and how they’re compu
|
||||
|
||||
## computeActions Method
|
||||
|
||||
The `IPromotionModuleService` has a `computeActions` method that returns an array of actions to perform on a cart when one or more promotions are applied.
|
||||
|
||||
<Note>
|
||||
|
||||
Refer to [the method’s reference](/references/promotion/computeActions) for full details on this method’s parameters and return type.
|
||||
|
||||
</Note>
|
||||
The Promotion Module's main service has a [computeActions method](/references/promotion/computeActions) that returns an array of actions to perform on a cart when one or more promotions are applied.
|
||||
|
||||
Actions inform you what adjustment must be made to a cart item or shipping method. Each action is an object having the `action` field indicating the type of action.
|
||||
|
||||
@@ -38,7 +32,7 @@ export interface AddItemAdjustmentAction {
|
||||
}
|
||||
```
|
||||
|
||||
When the Medusa application receives this action type, it creates a new record of the `LineItemAdjustment` data model in the Cart Module.
|
||||
This action means that a new record should be created of the `LineItemAdjustment` data model in the Cart Module.
|
||||
|
||||
<Note>
|
||||
|
||||
@@ -50,7 +44,7 @@ Refer to [this reference](/references/promotion/interfaces/promotion.AddItemAdju
|
||||
|
||||
The `removeItemAdjustment` action indicates that an adjustment must be removed from a line item. For example, remove the $5 discount.
|
||||
|
||||
When the Medusa application uses the `computeActions` method, it passes any previous item adjustments in the `items` property of the second parameter.
|
||||
The `computeActions` method accepts any previous item adjustments in the `items` property of the second parameter.
|
||||
|
||||
This action has the following format:
|
||||
|
||||
@@ -63,7 +57,7 @@ export interface RemoveItemAdjustmentAction {
|
||||
}
|
||||
```
|
||||
|
||||
When the Medusa application receives this action type, it removes the `LineItemAdjustment` with the specified ID in the `adjustment_id` property.
|
||||
This action means that a new record should be removed of the `LineItemAdjustment` with the specified ID in the `adjustment_id` property.
|
||||
|
||||
<Note>
|
||||
|
||||
@@ -87,7 +81,7 @@ export interface AddShippingMethodAdjustment {
|
||||
}
|
||||
```
|
||||
|
||||
When the Medusa application receives this action type, it creates a new record of the `ShippingMethodAdjustment` data model in the Cart Module.
|
||||
This action means that a new record should be created of the `ShippingMethodAdjustment` data model in the Cart Module.
|
||||
|
||||
<Note>
|
||||
|
||||
@@ -99,7 +93,7 @@ Refer to [this reference](/references/promotion/interfaces/promotion.AddShipping
|
||||
|
||||
The `removeShippingMethodAdjustment` action indicates that an adjustment must be removed from a shipping method. For example, remove the free shipping discount.
|
||||
|
||||
When the Medusa application uses the `computeActions` method, it passes any previous shipping method adjustments in the `shipping_methods` property of the second parameter.
|
||||
The `computeActions` method accepts any previous shipping method adjustments in the `shipping_methods` property of the second parameter.
|
||||
|
||||
This action has the following format:
|
||||
|
||||
@@ -132,8 +126,6 @@ export interface CampaignBudgetExceededAction {
|
||||
}
|
||||
```
|
||||
|
||||
The Medusa Application considers this an error, so it doesn’t apply the promotions on the cart.
|
||||
|
||||
<Note>
|
||||
|
||||
Refer to [this reference](/references/promotion/interfaces/promotion.CampaignBudgetExceededAction) for details on the object’s properties.
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
import { Table } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Application Method`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you'll learn what an application method is.
|
||||
|
||||
## What is an Application Method?
|
||||
|
||||
The [ApplicationMethod data model](/references/promotion/models/ApplicationMethod) defines how a promotion is applied:
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>
|
||||
|
||||
Field
|
||||
|
||||
</Table.HeaderCell>
|
||||
<Table.HeaderCell>
|
||||
|
||||
Purpose
|
||||
|
||||
</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`type`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Does the promotion discount a fixed amount or a percentage?
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`target_type`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Is the promotion applied on a cart item, shipping method, or the entire order?
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`allocation`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Is the discounted amount applied on each item or split between the applicable items?
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
## Target Promotion Rules
|
||||
|
||||
When the promotion is applied to a cart item or a shipping method, you can restrict which items/shipping methods the promotion is applied to.
|
||||
|
||||
The `ApplicationMethod` data model has a collection of `PromotionRule` records to restrict which items or shipping methods the promotion applies to. The `target_rules` field represents this relation.
|
||||
|
||||
|
||||
|
||||
In this example, the promotion is only applied on products in the cart having the SKU `SHIRT`.
|
||||
|
||||
---
|
||||
|
||||
## Buy Promotion Rules
|
||||
|
||||
When the promotion’s type is `buyget`, you must specify the “buy X” condition. For example, a cart must have two shirts before the promotion can be applied.
|
||||
|
||||
The application method has a collection of `PromotionRule` items to define the “buy X” rule. The `buy_rules` field represents this relation.
|
||||
|
||||
|
||||
|
||||
In this example, the cart must have two products with the SKU `SHIRT` for the promotion to be applied.
|
||||
@@ -0,0 +1,26 @@
|
||||
export const metadata = {
|
||||
title: `Campaign`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you'll learn about campaigns.
|
||||
|
||||
## What is a Campaign?
|
||||
|
||||
A [Campaign](/references/promotion/models/Campaign) combines promotions under the same conditions, such as start and end dates.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Campaign Limits
|
||||
|
||||
Each campaign has a budget represented by the [CampaignBudget data model](/references/promotion/models/CampaignBudget). The budget limits how many times the promotion can be used.
|
||||
|
||||
There are two types of budgets:
|
||||
|
||||
- `spend`: An amount that, when crossed, the promotion becomes unusable. For example, if the amount limit is set to `$100`, and the total amount of usage of this promotion crosses that threshold, the promotion can no longer be applied.
|
||||
- `usage`: The number of times that a promotion can be used. For example, if the usage limit is set to `10`, the promotion can be used only 10 times by customers. After that, it can no longer be applied.
|
||||
|
||||
|
||||
@@ -6,11 +6,11 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about the concepts in the Promotion Module.
|
||||
In this document, you’ll learn about the main promotion and rule concepts in the Promotion Module.
|
||||
|
||||
## Promotion
|
||||
## What is a Promotion?
|
||||
|
||||
A promotion, represented by the `Promotion` data model, represents a discount applied on cart items, shipping methods, or entire orders.
|
||||
A promotion, represented by the [Promotion data model](/references/promotion/models/Promotion), represents a discount applied on cart items, shipping methods, or entire orders.
|
||||
|
||||
A promotion has two types:
|
||||
|
||||
@@ -72,131 +72,27 @@ A promotion has two types:
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
### PromotionRule
|
||||
## PromotionRule
|
||||
|
||||
A promotion can be restricted by a set of rules, each rule is represented by the `PromotionRule` data model. For example, you can create a promotion that only customers of the `VIP` customer group can use it.
|
||||
A promotion can be restricted by a set of rules, each rule is represented by the [PromotionRule data model](/references/promotion/models/PromotionRule). For example, you can create a promotion that only customers of the `VIP` customer group can use.
|
||||
|
||||
|
||||
|
||||
A `PromotionRule`'s `field` field indicates the field's name to which this rule is applied. For example, `customer_group_id`. Its value is stored in the `PromotionRuleValue` data model. So, a rule can have multiple values.
|
||||
A `PromotionRule`'s `attribute` field indicates the field's name to which this rule is applied. For example, `customer_group_id`. Its value is stored in the `PromotionRuleValue` data model. So, a rule can have multiple values.
|
||||
|
||||
When testing whether a promotion can be applied to a cart, the rule's `field` field and its values are tested on the cart itself. For example, the cart's customer must be part of the customer group(s) indicated in the promotion rule's value.
|
||||
When testing whether a promotion can be applied to a cart, the rule's `attribute` field and its values are tested on the cart itself. For example, the cart's customer must be part of the customer group(s) indicated in the promotion rule's value.
|
||||
|
||||
### Flexible Rules
|
||||
---
|
||||
|
||||
## Flexible Rules
|
||||
|
||||
The `PromotionRule`'s `operator` field adds more flexibility to the rule’s condition rather than simple equality (`eq`).
|
||||
|
||||
For example, to restrict the promotion to only `VIP` and `B2B` customer groups:
|
||||
|
||||
- Add a `PromotionRule` with its `field` field set to `customer_group_id` and `operator` field to `in`.
|
||||
- Add a `PromotionRule` with its `attribute` field set to `customer_group_id` and `operator` field to `in`.
|
||||
- Add two `PromotionRuleValue` associated with the rule: one with the value `VIP` and the other `B2B`.
|
||||
|
||||
|
||||
|
||||
In this case, a customer’s group must be in the `VIP` and `B2B` set of values to use the promotion.
|
||||
|
||||
---
|
||||
|
||||
## Application Method
|
||||
|
||||
The `ApplicationMethod` data model defines how a promotion is applied:
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>
|
||||
|
||||
field
|
||||
|
||||
</Table.HeaderCell>
|
||||
<Table.HeaderCell>
|
||||
|
||||
Purpose
|
||||
|
||||
</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`type`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Does the promotion discount a fixed amount or a percentage?
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`target_type`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Is the promotion applied on a cart item, shipping method, or the entire order?
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
|
||||
`allocation`
|
||||
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
|
||||
Is the discounted amount applied on each item or split between the applicable items?
|
||||
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
### Target Promotion Rules
|
||||
|
||||
When the promotion is applied to a cart item or a shipping method, you can restrict which items/shipping methods the promotion is applied to.
|
||||
|
||||
The `ApplicationMethod` data model has a collection of `PromotionRule` records to restrict which items or shipping methods the promotion applies to. The `target_rules` field represents this relation.
|
||||
|
||||
|
||||
|
||||
In this example, the promotion is only applied on products in the cart having the SKU `SHIRT`.
|
||||
|
||||
### Buy Promotion Rules
|
||||
|
||||
When the promotion’s type is `buyget`, you must specify the “buy X” condition. For example, a cart must have two shirts before the promotion can be applied.
|
||||
|
||||
The application method has a collection of `PromotionRule` items to define the “buy X” rule. The `buy_rules` field represents this relation.
|
||||
|
||||
|
||||
|
||||
In this example, the cart must have two products with the SKU `SHIRT` for the promotion to be applied.
|
||||
|
||||
---
|
||||
|
||||
## Campaign
|
||||
|
||||
A `Campaign` combines promotions under the same conditions, such as start and end dates.
|
||||
|
||||
|
||||
|
||||
### Campaign Limits
|
||||
|
||||
Each campaign has a budget represented by the `CampaignBudget` data model. The budget limits how many times the promotion can be used.
|
||||
|
||||
There are two types of budgets:
|
||||
|
||||
- `spend`: An amount that, when crossed, the promotion becomes unusable. For example, if the amount limit is set to `$100`, and the total amount of usage of this promotion crosses that threshold, the promotion can no longer be applied.
|
||||
- `usage`: The number of times that a promotion can be used. For example, if the usage limit is set to `10`, the promotion can be used only 10 times by customers. After that, it can no longer be applied.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Full Data Models Diagram
|
||||
|
||||
|
||||
@@ -8,4 +8,10 @@ export const metadata = {
|
||||
|
||||
Find in this reference the list of events emitted by the Promotion Module.
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Events are still in development, so this reference will change in the future.
|
||||
|
||||
</Note>
|
||||
|
||||
<EventsTable />
|
||||
@@ -32,6 +32,7 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
type: "percentage",
|
||||
target_type: "order",
|
||||
value: "10",
|
||||
currency_code: "usd",
|
||||
},
|
||||
})
|
||||
|
||||
@@ -61,6 +62,7 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
type: "percentage",
|
||||
target_type: "order",
|
||||
value: "10",
|
||||
currency_code: "usd",
|
||||
},
|
||||
})
|
||||
|
||||
@@ -96,11 +98,6 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
campaign_identifier: "G-123445",
|
||||
starts_at: new Date("2024-05-02"),
|
||||
ends_at: new Date("2024-07-20"),
|
||||
promotions: [
|
||||
{
|
||||
id: "promo_123",
|
||||
},
|
||||
],
|
||||
}
|
||||
)
|
||||
|
||||
@@ -129,11 +126,6 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
campaign_identifier: "G-123445",
|
||||
starts_at: new Date("2024-05-02"),
|
||||
ends_at: new Date("2024-07-20"),
|
||||
promotions: [
|
||||
{
|
||||
id: "promo_123",
|
||||
},
|
||||
],
|
||||
}
|
||||
)
|
||||
|
||||
@@ -170,10 +162,11 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
type: "percentage",
|
||||
target_type: "order",
|
||||
value: "10",
|
||||
currency_code: "usd",
|
||||
},
|
||||
rules: [
|
||||
{
|
||||
field: "customer_group_id",
|
||||
attribute: "customer_group_id",
|
||||
operator: "eq",
|
||||
values: ["VIP"],
|
||||
},
|
||||
@@ -205,10 +198,11 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
type: "percentage",
|
||||
target_type: "order",
|
||||
value: "10",
|
||||
currency_code: "usd",
|
||||
},
|
||||
rules: [
|
||||
{
|
||||
field: "customer_group_id",
|
||||
attribute: "customer_group_id",
|
||||
operator: "eq",
|
||||
values: ["VIP"],
|
||||
},
|
||||
@@ -257,7 +251,7 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
initialize as initializePromotionModule,
|
||||
} from "@medusajs/promotion"
|
||||
|
||||
export async function POST(request: Request) {
|
||||
export async function GET(request: Request) {
|
||||
const promotionModuleService =
|
||||
await initializePromotionModule()
|
||||
|
||||
@@ -274,4 +268,4 @@ In this document, you’ll find common examples of how you can use the Promotion
|
||||
|
||||
## More Examples
|
||||
|
||||
The [module interface reference](/references/promotion) provides a reference to all the methods available for use with examples for each.
|
||||
The [Promotion Module's main service reference](/references/promotion) provides a reference to all the methods available for use with examples for each.
|
||||
@@ -24,6 +24,7 @@ const promotion = await promotionModuleService.create({
|
||||
type: "percentage",
|
||||
target_type: "order",
|
||||
value: "10",
|
||||
currency_code: "usd"
|
||||
},
|
||||
})
|
||||
```
|
||||
@@ -40,10 +41,11 @@ const promotion = await promotionModuleService.create({
|
||||
type: "percentage",
|
||||
target_type: "order",
|
||||
value: "10",
|
||||
currency_code: "usd"
|
||||
},
|
||||
rules: [
|
||||
{
|
||||
field: "customer_group_id",
|
||||
attribute: "customer_group_id",
|
||||
operator: "eq",
|
||||
values: ["VIP"],
|
||||
},
|
||||
@@ -64,11 +66,6 @@ const campaign = await promotionModuleService.createCampaigns(
|
||||
campaign_identifier: "G-123445",
|
||||
starts_at: new Date("2024-05-02"),
|
||||
ends_at: new Date("2024-07-20"),
|
||||
promotions: [
|
||||
{
|
||||
id: "promo_123",
|
||||
},
|
||||
],
|
||||
}
|
||||
)
|
||||
```
|
||||
@@ -77,14 +74,16 @@ const campaign = await promotionModuleService.createCampaigns(
|
||||
|
||||
## Configure Promotion Module
|
||||
|
||||
After installing the `@medusajs/promotion` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
|
||||
To use the Promotion Module, enable it in the `modules` object in `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const { Modules } = require("@medusajs/modules-sdk")
|
||||
|
||||
// ...
|
||||
|
||||
const modules = {
|
||||
// ...
|
||||
promotion: {
|
||||
resolve: "@medusajs/promotion",
|
||||
},
|
||||
[Modules.PROMOTION]: true,
|
||||
}
|
||||
```
|
||||
|
||||
@@ -143,9 +142,11 @@ For example:
|
||||
import { IPromotionModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
const step1 = createStep("step-1", async (_, context) => {
|
||||
const step1 = createStep(
|
||||
"step-1",
|
||||
async (_, { container }) => {
|
||||
const promotionModuleService: IPromotionModuleService =
|
||||
context.container.resolve(ModuleRegistrationName.PROMOTION)
|
||||
container.resolve(ModuleRegistrationName.PROMOTION)
|
||||
|
||||
const promotions = await promotionModuleService.list()
|
||||
})
|
||||
|
||||
+10
-6
@@ -4,14 +4,18 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
When Commerce Modules are used together in a Medusa application, the Medusa application handles building the relations between these modules.
|
||||
|
||||
This document showcases the relation between the Promotion Module and other Commerce Modules.
|
||||
This document showcases the link modules defined between the Promotion Module and other commerce modules.
|
||||
|
||||
## Cart Module
|
||||
|
||||
When the Cart and Promotion modules are used together, the Medusa application links the `Promotion` data model to the `Cart`, `LineItemAdjustment`, and `ShippingMethodAdjustment` data models of the Cart Module.
|
||||
A promotion can be applied on line items and shipping methods of a cart. Medusa defines a link module that builds a relationship between the `Cart`, `LineItemAdjustment`, and `Promotion` data models.
|
||||
|
||||
|
||||
|
||||
|
||||
A promotion is linked to a cart when a promotion is applied on the cart. Adjustments on items and shipping methods, represented by the `LineItemAdjustment` and `ShippingMethodAdjustment` data models, are linked to the promotion as well.
|
||||
---
|
||||
|
||||
## Order Module
|
||||
|
||||
An order is associated with the promotion applied on it. Medusa defines a link module that builds a relationship between the `Order` and `Promotion` data models.
|
||||
|
||||
|
||||
Reference in new issue
Block a user