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
@@ -4,27 +4,23 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about orders and their general fields.
|
||||
|
||||
## Order Data Model
|
||||
|
||||
An order represents a customer purchase in your store. The `Order` data model holds the information about that purchase.
|
||||
|
||||
---
|
||||
In this document, you’ll learn about orders and related concepts
|
||||
|
||||
## Order Items
|
||||
|
||||
The items purchased in the order are represented by the `OrderItem` data model. An order can have multiple items.
|
||||
The items purchased in the order are represented by the [OrderItem data model](/references/order/models/OrderItem). An order can have multiple items.
|
||||
|
||||
|
||||
|
||||
|
||||
Learn more about order items in [this guide](../order-items/page.mdx).
|
||||
### Item’s Product Details
|
||||
|
||||
The details of the purchased products are represented by the [LineItem data model](/references/order/models/LineItem). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
|
||||
|
||||
---
|
||||
|
||||
## Order’s Shipping Method
|
||||
|
||||
An order has one or more shipping methods used to handle item shipment. Each shipping method is represented by the `ShippingMethod` data model that holds its details.
|
||||
An order has one or more shipping methods used to handle item shipment. Each shipping method is represented by the [ShippingMethod data model](/references/order/models/ShippingMethod) that holds its details.
|
||||
|
||||
### data Field
|
||||
|
||||
@@ -32,19 +28,19 @@ When fulfilling the order, you may use a third-party fulfillment provider that r
|
||||
|
||||
The `ShippingMethod` data model has a `data` field. It’s an object used to store custom data relevant later for fulfillment.
|
||||
|
||||
In the Medusa application, the `data` is passed to the Fulfillment Module when fulfilling items.
|
||||
The Medusa application passes the `data` field to the Fulfillment Module when fulfilling items.
|
||||
|
||||
---
|
||||
|
||||
## Order Totals
|
||||
|
||||
The order’s total amounts (including tax total, total after an item is returned, etc…) are represented by the `OrderSummary` data model. An order can have multiple summaries.
|
||||
The order’s total amounts (including tax total, total after an item is returned, etc…) are represented by the [OrderSummary data model](/references/order/models/OrderSummary).
|
||||
|
||||
---
|
||||
|
||||
## Order Payments
|
||||
|
||||
Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the `Transaction` data model.
|
||||
Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [Transaction data model](/references/order/models/Transaction).
|
||||
|
||||
An order can have multiple transactions. The sum of these transactions must be equal to the order summary’s total. Otherwise, there’s an outstanding amount.
|
||||
|
||||
|
||||
@@ -8,4 +8,10 @@ export const metadata = {
|
||||
|
||||
Find in this reference the list of events emitted by the Order Module.
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
Events are still in development, so this reference will change in the future.
|
||||
|
||||
</Note>
|
||||
|
||||
<EventsTable />
|
||||
@@ -8,11 +8,17 @@ export const metadata = {
|
||||
|
||||
In this document, you’ll learn how to make changes to an order, such as return or exchange an item.
|
||||
|
||||
<Note type="soon" title="In Development">
|
||||
|
||||
Order Change is still in development.
|
||||
|
||||
</Note>
|
||||
|
||||
## What's an Order Change?
|
||||
|
||||
An order change is modifying the order’s items for business purposes. For example, when a customer requests to return an item, or when you suggest exchanging an item with another.
|
||||
An order change is modifying the order’s items for business purposes. For example, when a customer requests to return an item, or when a merchant suggests exchanging an item with another.
|
||||
|
||||
Order changes are represented by the `OrderChange` data model.
|
||||
Order changes are represented by the [OrderChange data model](/references/order/models/OrderChange).
|
||||
|
||||
---
|
||||
|
||||
@@ -25,7 +31,7 @@ An order change can have multiple underlying actions. For example, to exchange a
|
||||
- Add the new item to be sent to the customer.
|
||||
- Fulfill the item and send it to the customer.
|
||||
|
||||
Each of these actions is represented by the `OrderChangeAction` data model.
|
||||
Each of these actions is represented by the [OrderChangeAction data model](/references/order/models/OrderChangeAction).
|
||||
|
||||
### Action Name
|
||||
|
||||
@@ -269,33 +275,12 @@ The `action` field of the `OrderChangeAction` holds the name of the action to pe
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
|
||||
### Action Chaining
|
||||
|
||||
Actions are chained one after the other, similar to the example in the earlier section. This also allows you to cancel or undo some actions.
|
||||
|
||||
For example, if you request an order return with `RETURN_ITEM` action, you can later cancel it with the `CANCEL_RETURN` action.
|
||||
|
||||
The actions are ordered by the `ordering` field of the `OrderChangeAction` data model.
|
||||
|
||||
### Action Amount
|
||||
|
||||
The `OrderChangeAction` data model has an `amount` field that indicates a change in the order’s amount that this action incurs.
|
||||
|
||||
---
|
||||
|
||||
## Order Change Confirmation
|
||||
|
||||
The `OrderChange` data model has a `status` field that indicates its current status. By default, it’s pending. At this point, the order change’s actions aren’t applied to the order yet.
|
||||
|
||||
To apply these changes to the order, you must confirm the order change. When the order change is confirmed:
|
||||
To apply these changes to the order, you confirm the order change. When the order change is confirmed:
|
||||
|
||||
- The status of the order change is changed to `confirmed`.
|
||||
- The order’s items are changed based on the order change’s actions. For example, an item is added, or an existing item’s quantity is changed.
|
||||
- The order summary is modified to reflect new changes.
|
||||
|
||||
<Note>
|
||||
|
||||
If there are changes to the order’s total amount due to refunding or capturing payment, they must be added as transactions first. Otherwise, they won’t be accounted for when modifying the order summary
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `Order Item`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about the order item and the general details it holds.
|
||||
|
||||
## OrderItem Data Model
|
||||
|
||||
Each item in an order is represented by the `OrderItem` data model. It holds details related to the quantity of the item and the underlying product details.
|
||||
|
||||
---
|
||||
|
||||
## Order Item Quantity
|
||||
|
||||
The `OrderItem` data model has the following quantity fields:
|
||||
|
||||
- `quantity`: The quantity ordered.
|
||||
- `fulfilled_quantity`: The quantity that’s been fulfilled.
|
||||
- `shipped_quantity`: The quantity that’s been shipped.
|
||||
- `return_requested_quantity`: The quantity requested to be returned, but hasn’t been received yet.
|
||||
- `return_received_quantity`: The quantity that’s been received from the customer due to a return request.
|
||||
- `return_dismissed_quantity`: The quantity that’s been received from the customer due to a return request, but the items are damaged.
|
||||
- `written_off_quantity`: The quantity removed from the originally ordered quantity.
|
||||
|
||||
---
|
||||
|
||||
## Item’s Product Details
|
||||
|
||||
The details of the purchased products are represented by the `LineItem` data model. Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
|
||||
|
||||
<Note>
|
||||
|
||||
The `LineItem` data model is similar to the Cart Module’s `LineItem` data model. So, when using both modules, the data can be copied between the modules as-is.
|
||||
|
||||
</Note>
|
||||
@@ -28,6 +28,6 @@ So, if the order’s `version` is `1`, the order change’s version is `2`.
|
||||
|
||||
Then, once the order change is confirmed and applied to the order, the versions of the order and order summary change to that of the order change.
|
||||
|
||||
Order items change depending on the version they were added or modified in, as explained in the earlier section.
|
||||
|
||||
|
||||
|
||||
Order items change depending on the version they were added or modified in, as explained in the earlier section.
|
||||
|
||||
@@ -8,13 +8,11 @@ export const metadata = {
|
||||
|
||||
The Order Module is the `@medusajs/order` NPM package that provides order-related features in your Medusa and Node.js applications.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Order Management
|
||||
|
||||
Store and manage your orders by retrieving, creating, canceling, and performing other operations.
|
||||
Store and manage your orders to retriev, create, cancel, and perform other operations.
|
||||
|
||||
```ts
|
||||
const order = await orderModuleService.create({
|
||||
@@ -47,9 +45,35 @@ const draftOrder = await orderModuleService.create({
|
||||
})
|
||||
```
|
||||
|
||||
### Apply Promotions
|
||||
|
||||
Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
|
||||
|
||||
```ts
|
||||
const lineAdjustments =
|
||||
await orderModuleService.addLineItemAdjustments({
|
||||
item_id: "cali_123",
|
||||
code: "50OFF",
|
||||
amount: 500,
|
||||
})
|
||||
|
||||
const shippingAdjustments =
|
||||
await orderModuleService.addShippingMethodAdjustments({
|
||||
shipping_method_id: "casm_123",
|
||||
code: "FREESHIPPING",
|
||||
amount: 1000,
|
||||
})
|
||||
```
|
||||
|
||||
### Returns, Exchanges, and Other Order Changes
|
||||
|
||||
Orders can be changed to return items from the customer, exchange an item with another, change the quantity of an item, or other changes.
|
||||
<Note title="In Development" type="soon">
|
||||
|
||||
Order Changes are still in development.
|
||||
|
||||
</Note>
|
||||
|
||||
Orders can be changed to return items from the customer, exchange an item with another, change the quantity of an item, or perform other changes.
|
||||
|
||||
Changes are only applied after confirmation, and order history is preserved through versioning.
|
||||
|
||||
@@ -74,38 +98,20 @@ await orderModuleService.addOrderAction({
|
||||
await orderModuleService.confirmOrderChange("ord_123")
|
||||
```
|
||||
|
||||
### Apply Promotions
|
||||
|
||||
Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.
|
||||
|
||||
```ts
|
||||
const lineAdjustments =
|
||||
await orderModuleService.addLineItemAdjustments({
|
||||
item_id: "cali_123",
|
||||
code: "50OFF",
|
||||
amount: 500,
|
||||
})
|
||||
|
||||
const shippingAdjustments =
|
||||
await orderModuleService.addShippingMethodAdjustments({
|
||||
shipping_method_id: "casm_123",
|
||||
code: "FREESHIPPING",
|
||||
amount: 1000,
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configure Order Module
|
||||
|
||||
After installing the `@medusajs/order` package in your Medusa application, add it to the `modules` object in `medusa-config.js`:
|
||||
To use the Order Module, enable it in the `modules` object in `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const { Modules } = require("@medusajs/modules-sdk")
|
||||
|
||||
// ...
|
||||
|
||||
const modules = {
|
||||
// ...
|
||||
order: {
|
||||
resolve: "@medusajs/order",
|
||||
},
|
||||
[Modules.ORDER]: true,
|
||||
}
|
||||
```
|
||||
|
||||
@@ -150,7 +156,7 @@ For example:
|
||||
container,
|
||||
}: SubscriberArgs) {
|
||||
const orderModuleService: IOrderModuleService =
|
||||
container.resolve(ModuleRegistrationName.API_KEY)
|
||||
container.resolve(ModuleRegistrationName.ORDER)
|
||||
|
||||
const orders = await orderModuleService.list()
|
||||
}
|
||||
@@ -164,10 +170,12 @@ For example:
|
||||
import { IOrderModuleService } from "@medusajs/types"
|
||||
import { ModuleRegistrationName } from "@medusajs/modules-sdk"
|
||||
|
||||
const step1 = createStep("step-1", async (_, context) => {
|
||||
const step1 = createStep(
|
||||
"step-1",
|
||||
async (_, { container }) => {
|
||||
const orderModuleService: IOrderModuleService =
|
||||
context.container.resolve(
|
||||
ModuleRegistrationName.API_KEY
|
||||
container.resolve(
|
||||
ModuleRegistrationName.ORDER
|
||||
)
|
||||
const orders = await orderModuleService.list()
|
||||
})
|
||||
|
||||
@@ -14,17 +14,26 @@ In this document, you’ll learn how a promotion is applied to an order’s item
|
||||
|
||||
An adjustment line indicates a change to a line item or a shipping method’s amount. It’s used to apply promotions or discounts on an order.
|
||||
|
||||
The `LineItemAdjustment` data model represents adjustment lines for a line item, and the `ShippingMethodAdjustment` data model represents adjustment lines for a shipping method.
|
||||
The [LineItemAdjustment data model](/references/order/models/LineItemAdjustment) represents changes on a line item, and the [ShippingMethodAdjustment data model](/references/order/models/ShippingMethodAdjustment) represents changes on a shipping method.
|
||||
|
||||
|
||||
|
||||
|
||||
The `amount` field of the adjustment line indicates the amount to be discounted from the original amount. Also, the ID of the applied promotion can be stored in the `promotion_id` field of the adjustment line.
|
||||
|
||||
---
|
||||
|
||||
## Discountable Option
|
||||
|
||||
The `LineItem` data model has an `is_discountable` field that indicates whether promotions can be applied to the line item. It’s enabled by default.
|
||||
|
||||
When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Promotion Actions
|
||||
|
||||
When using the Order and Promotion modules together, such as in the Medusa application, use the `computeActions` method of the Promotion Module’s main service. It retrieves the actions of line items and shipping methods.
|
||||
When using the Order and Promotion modules together, use the [computeActions method of the Promotion Module’s main service](/references/promotion/computeActions). It retrieves the actions of line items and shipping methods.
|
||||
|
||||
<Note>
|
||||
|
||||
@@ -92,12 +101,6 @@ const actions = await promotionModuleService.computeActions(
|
||||
|
||||
The `computeActions` method accepts the existing adjustments of line items and shipping methods to compute the actions accurately.
|
||||
|
||||
<Note>
|
||||
|
||||
Learn more about the `computeActions` method in [this reference](/references/promotion/computeActions).
|
||||
|
||||
</Note>
|
||||
|
||||
Then, use the returned `addItemAdjustment` and `addShippingMethodAdjustment` actions to set the order’s line items and the shipping method’s adjustments.
|
||||
|
||||
```ts
|
||||
@@ -123,12 +126,4 @@ await orderModuleService.setShippingMethodAdjustments(
|
||||
action.action === "addShippingMethodAdjustment"
|
||||
) as AddShippingMethodAdjustment[]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Discountable Option
|
||||
|
||||
The `LineItem` data model has an `is_discountable` field that indicates whether promotions can be applied to the line item. It’s enabled by default.
|
||||
|
||||
When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.
|
||||
```
|
||||
@@ -4,13 +4,59 @@ 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 link modules defined between the Order Module and other commerce modules.
|
||||
|
||||
This document showcases the relation between the Order Module and other Commerce Modules.
|
||||
## Customer Module
|
||||
|
||||
An order is associated with the customer that placed it. Medusa defines a link module that builds a relationship between the `Order` and `Customer` data models.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Fulfillment Module
|
||||
|
||||
A fulfillment is created for an orders' items. Medusa defines a link module that builds a relationship between the `Fulfillment` and `Order` data models.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Payment Module
|
||||
|
||||
An order's payment is stored in a payment collection. Medusa defines a link module that builds a relationship between the `Order` and `PaymentCollection` data models.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Product Module
|
||||
|
||||
An order's line item is associated with the purchased product and its variant. Medusa defines a link module that builds a relationship between the `LineItem`, `Product`, and `ProductVariant` data models.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Promotion 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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Region Module
|
||||
|
||||
An order is associated with the customer's region. Medusa defines a link module that builds a relationship between the `Order` and `Region` data models.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Sales Channel Module
|
||||
|
||||
Orders can be scoped to a sales channel. The Medusa application forms a relation between the `Order` and the `SalesChannel` data models.
|
||||
Orders can be scoped to a sales channel. Medusa defines a link module that builds a relationship between the `Order` and the `SalesChannel` data models.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -12,15 +12,15 @@ In this document, you’ll learn about tax lines in an order.
|
||||
|
||||
## What are Tax Lines?
|
||||
|
||||
A tax line indicates the tax rate of a line item or a shipping method. The `LineItemTaxLine` data model represents a line item’s tax line, and the `ShippingMethodTaxLine` data model represents a shipping method’s tax line.
|
||||
A tax line indicates the tax rate of a line item or a shipping method. The [LineItemTaxLine data model](/references/order/models/LineItemTaxLine) represents a line item’s tax line, and the [ShippingMethodTaxLine data model](/references/order/models/ShippingMethodTaxLine) represents a shipping method’s tax line.
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Tax Inclusivity
|
||||
|
||||
By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount and then added to the item/method’s subtotal.
|
||||
By default, the tax amount is calculated by taking the tax rate from the line item or shipping method’s amount and then adding it to the item/method’s subtotal.
|
||||
|
||||
However, line items and shipping methods have an `is_tax_inclusive` field that, when enabled, indicates that the item or method’s price already includes taxes.
|
||||
|
||||
@@ -32,4 +32,4 @@ The following diagram is a simplified showcase of how a subtotal is calculated f
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
|
||||
@@ -6,30 +6,19 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this document, you’ll learn about an order’s transactions and usefulness.
|
||||
In this document, you’ll learn about an order’s transactions and its use.
|
||||
|
||||
## What is a Transaction?
|
||||
|
||||
A transaction represents any order payment process, such as capturing or refunding an amount. It’s represented by the `Transaction` data model.
|
||||
A transaction represents any order payment process, such as capturing or refunding an amount. It’s represented by the [Transaction data model](/references/order/models/Transaction).
|
||||
|
||||
The transaction’s main purpose is to ensure a correct balance between paid and outstanding amounts.
|
||||
|
||||
---
|
||||
|
||||
## Transaction Reference
|
||||
|
||||
The Order Module doesn’t provide payment processing functionalities, so it doesn’t store payments that can be processed. For that, use the Payment Module or custom logic.
|
||||
|
||||
The `Transaction` data model has two fields that determine which data model and record holds the actual payment’s details:
|
||||
|
||||
- `reference`: indicates the table’s name in the database. For example, `payment` if you’re using the Payment Module.
|
||||
- `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.
|
||||
|
||||
---
|
||||
|
||||
## Checking Outstanding Amount
|
||||
|
||||
The order’s total is stored in the `OrderSummary`'s `total` field. To check the outstanding amount of the order, the transaction amounts of an order are summed. Then:
|
||||
The order’s total is stored in the `OrderSummary`'s `total` field. To check the outstanding amount of the order, its transaction amounts are summed. Then, the following conditions are checked:
|
||||
|
||||
<Table>
|
||||
<Table.Header>
|
||||
@@ -77,3 +66,14 @@ The order’s total is stored in the `OrderSummary`'s `total` field. To check th
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
---
|
||||
|
||||
## Transaction Reference
|
||||
|
||||
The Order Module doesn’t provide payment processing functionalities, so it doesn’t store payments that can be processed. For that, use the Payment Module or custom logic.
|
||||
|
||||
The `Transaction` data model has two fields that determine which data model and record holds the actual payment’s details:
|
||||
|
||||
- `reference`: indicates the table’s name in the database. For example, `payment` if you’re using the Payment Module.
|
||||
- `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.
|
||||
Reference in New Issue
Block a user