asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: general fixes to cart and order concept docs (#13270)

Browse Source
This commit is contained in:
Shahed Nasser
2025-08-21 19:09:01 +03:00
committed by GitHub
parent e7b45f5fde
commit 25ed42f740
10 changed files with 367 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/commerce-modules/cart/concepts/page.mdx
+20 -6
View File
@@ -4,13 +4,19 @@ export const metadata = {
# {metadata.title}
In this document, you’ll get an overview of the main concepts of a cart.
In this document, you’ll learn about the main concepts related to carts in Medusa.
## Shipping and Billing Addresses
## Cart
A cart has a shipping and billing address. Both of these addresses are represented by the [Address data model](/references/cart/models/Address).
A cart is the selection of product variants that a customer intends to purchase. It is represented by the [Cart data model](/references/cart/models/Cart).
![A diagram showcasing the relation between the Cart and Address data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711532392/Medusa%20Resources/cart-addresses_ls6qmv.jpg)
A cart holds informations about:
- The items the customer wants to buy.
- The customer's shipping and billing addresses.
- The shipping methods used to fulfill the items after purchase.
- The payment method and information necessary to complete the purchase.
- These are stored and handled by the [Payment Module](../../payment/page.mdx).
---
@@ -18,14 +24,22 @@ A cart has a shipping and billing address. Both of these addresses are represent
A line item, represented by the [LineItem](/references/cart/models/LineItem) data model, is a quantity of a product variant added to the cart. A cart has multiple line items.
A line item stores some of the product variant’s properties, such as the `product_title` and `product_description`. It also stores data related to the item’s quantity and price.
<Note>
In the Medusa application, a product variant is implemented in the [Product Module](../../product/page.mdx).
</Note>
A line item stores some of the product variant’s properties, such as the `product_title` and `product_description`. It also stores data related to the item’s quantity and price.
---
## Shipping and Billing Addresses
A cart has a shipping and billing address. Both of these addresses are represented by the [Address data model](/references/cart/models/Address).
![A diagram showcasing the relation between the Cart and Address data models](https://res.cloudinary.com/dza7lstvk/image/upload/v1711532392/Medusa%20Resources/cart-addresses_ls6qmv.jpg)
---
## Shipping Methods
www/apps/resources/app/commerce-modules/fulfillment/item-fulfillment/page.mdx
+13 -11
View File
@@ -1,28 +1,30 @@
export const metadata = {
title: `Item Fulfillment`,
title: `Item Fulfillment Concepts`,
}
# {metadata.title}
In this document, you’ll learn about the concepts of item fulfillment.
In this document, you’ll learn about the concepts related to item fulfillment.
## Fulfillment Data Model
A fulfillment is the shipping and delivery of one or more items to the customer. It’s represented by the [Fulfillment data model](/references/fulfillment/models/Fulfillment).
A fulfillment can be created to fulfill orders, [returns](../../order/return/), [exchanges](../../order/exchange/page.mdx), and [claims](../../order/claim/page.mdx).
---
## Fulfillment Processing by a Fulfillment Provider
A fulfillment is associated with a fulfillment provider that handles all its processing, such as creating a shipment for the fulfillment’s items.
A fulfillment is associated with a [fulfillment provider](../fulfillment-provider/page.mdx) that handles all its processing, such as creating a shipment for the fulfillment’s items.
The fulfillment is also associated with a shipping option of that provider, which determines how the item is shipped.
The fulfillment is also associated with a [shipping option](../shipping-option/page.mdx) of that provider, which determines how the item is shipped.
![A diagram showcasing the relation between a fulfillment, fulfillment provider, and shipping option](https://res.cloudinary.com/dza7lstvk/image/upload/v1712331947/Medusa%20Resources/fulfillment-shipping-option_jk9ndp.jpg)
---
## data Property
## data Property of Fulfillment Data Model
The `Fulfillment` data model has a `data` property that holds any necessary data for the third-party fulfillment provider to process the fulfillment.
@@ -32,7 +34,7 @@ For example, the `data` property can hold the ID of the fulfillment in the third
## Fulfillment Items
A fulfillment is used to fulfill one or more items. Each item is represented by the `FulfillmentItem` data model.
A fulfillment is used to fulfill one or more items. Each item is represented by the [FulfillmentItem data model](/references/fulfillment/models/FulfillmentItem).
The fulfillment item holds details relevant to fulfilling the item, such as barcode, SKU, and quantity to fulfill.
@@ -42,14 +44,14 @@ The fulfillment item holds details relevant to fulfilling the item, such as barc
## Fulfillment Label
Once a shipment is created for the fulfillment, you can store its tracking number, URL, or other related details as a label, represented by the `FulfillmentLabel` data model.
Once a shipment is created for the fulfillment, you can store its tracking number, URL, or other related details as a label, represented by the [FulfillmentLabel data model](/references/fulfillment/models/FulfillmentLabel).
---
## Fulfillment Status
The `Fulfillment` data model has three properties to keep track of the current status of the fulfillment:
The [Fulfillment data model](/references/fulfillment/models/Fulfillment) has three properties to determine the current status of the fulfillment:
- `packed_at`: The date the fulfillment was packed. If set, then the fulfillment has been packed.
- `shipped_at`: The date the fulfillment was shipped. If set, then the fulfillment has been shipped.
- `delivered_at`: The date the fulfillment was delivered. If set, then the fulfillment has been delivered.
- `packed_at`: The date the fulfillment was packed. If set, the fulfillment has been packed.
- `shipped_at`: The date the fulfillment was shipped. If set, the fulfillment has been shipped.
- `delivered_at`: The date the fulfillment was delivered. If set, the fulfillment has been delivered.
www/apps/resources/app/commerce-modules/fulfillment/module-options/page.mdx
+3 -3
View File
@@ -10,11 +10,11 @@ export const metadata = {
# {metadata.title}
In this document, you'll learn about the options of the Fulfillment Module.
In this document, you'll learn about the options of the Fulfillment Module. You can pass these options in `medusa-config.ts`.
## providers
The `providers` option is an array of fulfillment module providers.
The `providers` option is an array of [Fulfillment Module Providers](../fulfillment-provider/page.mdx).
When the Medusa application starts, these providers are registered and can be used to process fulfillments.
@@ -48,6 +48,6 @@ module.exports = defineConfig({
The `providers` option is an array of objects that accept the following properties:
- `resolve`: A string indicating either the package name of the module provider or the path to it relative to the `src` directory.
- `resolve`: A string indicating either the package name of the module provider or its relative path.
- `id`: A string indicating the provider's unique name or ID.
- `options`: An optional object of the module provider's options.
www/apps/resources/app/commerce-modules/order/concepts/page.mdx
+19 -4
View File
@@ -6,9 +6,22 @@ export const metadata = {
In this document, you’ll learn about orders and related concepts
## Order
An order is a purchase made by a customer, either through the storefront or through the API. It is represented by the [Order data model](/references/order/models/Order).
An order holds information about:
- The purchased items.
- The customer who made the order.
- This is stored and handled by the [Customer Module](../../customer/page.mdx).
- Payment and shipping information
---
## Order Items
The items purchased in the order are represented by the [OrderItem data model](/references/order/models/OrderItem). An order can have multiple items.
The items purchased in an order are represented by the [OrderItem data model](/references/order/models/OrderItem). An order can have multiple items.
![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1712304722/Medusa%20Resources/order-order-items_uvckxd.jpg)
@@ -28,7 +41,7 @@ Each shipping method is represented by the [OrderShippingMethod data model](/ref
### data Property
When fulfilling the order, you can use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
When fulfilling an order, you can use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
The `OrderShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.
@@ -38,7 +51,9 @@ The Medusa application passes the `data` property to the Fulfillment Module when
## Order Totals
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).
An 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).
Refer to the [Retrieve Order Totals](../order-totals/page.mdx) guide to learn how to retrieve an order’s totals.
---
@@ -48,4 +63,4 @@ Payments made on an order, whether they’re capture or refund payments, are rec
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.
Learn more about transactions in [this guide](../transactions/page.mdx).
Refer to the [Transactions](../transactions/page.mdx) guide to learn more.
www/apps/resources/app/commerce-modules/order/order-change/page.mdx
+195 -21
View File
@@ -6,30 +6,31 @@ export const metadata = {
# {metadata.title}
In this document, you'll learn about the Order Change data model and possible actions in it.
In this document, you'll learn what an order change is and the related concepts.
## OrderChange Data Model
The [OrderChange data model](/references/order/models/OrderChange) represents any kind of change to an order, such as a return, exchange, or edit.
The [OrderChange data model](/references/order/models/OrderChange) represents any kind of change to an order, such as a [return](../return/page.mdx), [exchange](../exchange/page.mdx), or [edit](../edit/page.mdx). Each of these is essentially an order change that is confirmed to apply changes to the original order.
Its `change_type` property indicates what the order change is created for:
The `OrderChange` model's `change_type` property indicates the purpose of the order change:
1. `edit`: The order change is making edits to the order, as explained in [this guide](../edit/page.mdx).
2. `exchange`: The order change is associated with an exchange, which you can learn about in [this guide](../exchange/page.mdx).
3. `claim`: The order change is associated with a claim, which you can learn about in [this guide](../claim/page.mdx).
4. `return_request` or `return_receive`: The order change is associated with a return, which you can learn about in [this guide](../return/page.mdx).
1. `edit`: The order change is making edits to the order, as explained in the [Order Edit](../edit/page.mdx) guide.
2. `exchange`: The order change is associated with an exchange, which you can learn about in the [Order Exchange](../exchange/page.mdx) guide.
3. `claim`: The order change is associated with a claim, which you can learn about in the [Order Claim](../claim/page.mdx) guide.
4. `return_request` or `return_receive`: The order change is associated with a return, which you can learn about in the [Order Return](../return/page.mdx) guide.
Once the order change is confirmed, its changes are applied on the order.
Once the order change is confirmed, its changes are applied to the order.
---
## Order Change Actions
The actions to perform on the original order by a change, such as adding an item, are represented by the [OrderChangeAction data model](/references/order/models/OrderChangeAction).
The actions performed on the original order by an order change, such as adding an item, are represented by the [OrderChangeAction data model](/references/order/models/OrderChangeAction).
The `OrderChangeAction` has an `action` property that indicates the type of action to perform on the order, and a `details` property that holds more details related to the action.
The `OrderChangeAction` has an `action` property that indicates the type of action to perform on the order, and a `details` property that holds additional information related to the action.
The following table lists the possible `action` values that Medusa uses and what `details` they carry.
The following table lists the possible `action` values that Medusa uses and the corresponding `details` they carry.
<Table>
<Table.Header>
@@ -48,7 +49,7 @@ The following table lists the possible `action` values that Medusa uses and what
</Table.Cell>
<Table.Cell>
Add an item to the order.
Add an item to the order. The item is only added after the change is confirmed.
</Table.Cell>
<Table.Cell>
@@ -69,8 +70,8 @@ The following table lists the possible `action` values that Medusa uses and what
</Table.Cell>
<Table.Cell>
Update an item in the order.
Update an item in an order change. It's only applied to the order after the change is confirmed.
</Table.Cell>
<Table.Cell>
@@ -86,6 +87,26 @@ The following table lists the possible `action` values that Medusa uses and what
<Table.Row>
<Table.Cell>
`ITEM_REMOVE`
</Table.Cell>
<Table.Cell>
Remove an item from an order change. This can happen when a claim or an exchange is canceled.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to remove.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`RETURN_ITEM`
</Table.Cell>
@@ -100,7 +121,6 @@ The following table lists the possible `action` values that Medusa uses and what
- `reference_id`: the ID of the item.
- `quantity`: The quantity to be returned.
- `reason_id`: The ID of the return reason.
- `metadata`: The item's metadata.
</Table.Cell>
@@ -148,17 +168,20 @@ The following table lists the possible `action` values that Medusa uses and what
<Table.Row>
<Table.Cell>
`SHIPPING_ADD`
`CANCEL_RETURN_ITEM`
</Table.Cell>
<Table.Cell>
Add a shipping method for new or returned items.
Cancel the return of an item. This can happen when a return is canceled.
</Table.Cell>
<Table.Cell>
No details added. The ID to the shipping method is added in the `reference_id` property of the action.
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to cancel.
</Table.Cell>
</Table.Row>
@@ -170,7 +193,7 @@ The following table lists the possible `action` values that Medusa uses and what
</Table.Cell>
<Table.Cell>
Add a shipping method for new or returned items.
Add a shipping method to an order change. It's only added to the order after the change is confirmed.
</Table.Cell>
<Table.Cell>
@@ -182,12 +205,92 @@ The following table lists the possible `action` values that Medusa uses and what
<Table.Row>
<Table.Cell>
`SHIPPING_REMOVE`
</Table.Cell>
<Table.Cell>
Remove a shipping method from an order change. This can happen when a claim or an exchange is canceled.
</Table.Cell>
<Table.Cell>
No details added. The ID to the shipping method is added in the `reference_id` property of the action.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`SHIP_ITEM`
</Table.Cell>
<Table.Cell>
Mark an item's quantity as shipped.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to mark as shipped.
- `metadata`: The item's metadata.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`FULFILL_ITEM`
</Table.Cell>
<Table.Cell>
Fulfill an item's quantity as part of a change.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to fulfill.
- `metadata`: The item's metadata.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`DELIVER_ITEM`
</Table.Cell>
<Table.Cell>
Mark an item's quantity as delivered.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to mark as delivered.
- `metadata`: The item's metadata.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`WRITE_OFF_ITEM`
</Table.Cell>
<Table.Cell>
Remove an item's quantity as part of the claim, without adding the quantity back to the item variant's inventory.
Remove an item's quantity from an order change, without adding the quantity back to the item variant's inventory. The quantity isn't removed from the order until the change is confirmed.
</Table.Cell>
<Table.Cell>
@@ -196,7 +299,78 @@ The following table lists the possible `action` values that Medusa uses and what
- `reference_id`: the ID of the item.
- `quantity`: The quantity to write off.
- `reason`: The claim reason.
- `metadata`: The item's metadata.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`REINSTATE_ITEM`
</Table.Cell>
<Table.Cell>
Reinstate an item's quantity in an order change that was previously written off. The quantity is added back to the item variant's inventory when the change is confirmed.
</Table.Cell>
<Table.Cell>
`details` is an object having the following properties:
- `reference_id`: the ID of the item.
- `quantity`: The quantity to reinstate.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`TRANSFER_CUSTOMER`
</Table.Cell>
<Table.Cell>
Transfer an order to another customer. The order is not removed from the original customer until the change is confirmed.
</Table.Cell>
<Table.Cell>
No details added. The ID to the new customer is added in the `reference_id` property of the action.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`UPDATE_ORDER_PROPERTIES`
</Table.Cell>
<Table.Cell>
Update the properties of an order, such as customer information or shipping address. The properties are not updated on the original order until the change is confirmed.
</Table.Cell>
<Table.Cell>
`details` is an object that has the properties to update. The properties are the same as the ones in the [Order data model](/references/order/models/Order).
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`CREDIT_LINE_ADD`
</Table.Cell>
<Table.Cell>
Add a credit line to an order. The credit line is not added to the original order until the change is confirmed.
</Table.Cell>
<Table.Cell>
No details added. The ID to the associated payment is added in the `reference_id` property of the action.
</Table.Cell>
</Table.Row>
www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx
+9 -8
View File
@@ -4,13 +4,14 @@ export const metadata = {
# {metadata.title}
In this document, you’ll learn how an order and its details are versioned.
## What's Versioning?
In this document, you’ll learn how orders and their details are versioned.
Versioning means assigning a version number to a record, such as an order and its items. This is useful to view the different versions of the order following changes in its lifetime.
## What is Order Versioning?
When changes are made on an order, such as an item is added or returned, the order's version changes.
Versioning means assigning a version number to a record, such as an order and its items. This is useful for viewing the different versions of an order following changes throughout its lifetime.
When changes are confirmed on an order, such as when an item is added or returned, the order's version changes.
---
@@ -18,15 +19,15 @@ When changes are made on an order, such as an item is added or returned, the ord
The `Order` and `OrderSummary` data models have a `version` property that indicates the current version. By default, its value is `1`.
Other order-related data models, such as `OrderItem`, also has a `version` property, but it indicates the version it belongs to.
Other order-related data models, such as `OrderItem`, also have a `version` property, but it indicates the version to which the record belongs.
---
## How the Version Changes
When the order is changed, such as an item is exchanged, this changes the version of the order and its related data:
When the order is changed, such as when an item is exchanged, Medusa updates the order's version and its related data:
1. The version of the order and its summary is incremented.
2. Related order data that have a `version` property, such as the `OrderItem`, are duplicated. The duplicated item has the new version, whereas the original item has the previous version.
2. Related order data that have a `version` property, such as `OrderItem`, are duplicated. The duplicated item has the new version, while the original item retains the previous version.
When the order is retrieved, only the related data having the same version is retrieved.
When the order is retrieved, only the related data with the same version is returned.