From 25ed42f74081c62bd36f4a62dbf5f78c6eaff0ae Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 21 Aug 2025 19:09:01 +0300 Subject: [PATCH] docs: general fixes to cart and order concept docs (#13270) --- www/apps/book/public/llms-full.txt | 134 +++++++---- .../commerce-modules/cart/concepts/page.mdx | 26 ++- .../fulfillment/item-fulfillment/page.mdx | 24 +- .../fulfillment/module-options/page.mdx | 6 +- .../commerce-modules/order/concepts/page.mdx | 23 +- .../order/order-change/page.mdx | 216 ++++++++++++++++-- .../order/order-versioning/page.mdx | 17 +- www/apps/resources/generated/edit-dates.mjs | 12 +- .../generated-commerce-modules-sidebar.mjs | 18 +- www/apps/resources/sidebars/fulfillment.mjs | 12 +- 10 files changed, 367 insertions(+), 121 deletions(-) diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index caf99c8755..b0d9ad15ac 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -25883,13 +25883,19 @@ You can't apply filters directly on the cart totals, as they are not stored in t # Cart Concepts -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](https://docs.medusajs.com/references/cart/models/Address/index.html.md). +A cart is the selection of product variants that a customer intends to purchase. It is represented by the [Cart data model](https://docs.medusajs.com/references/cart/models/Cart/index.html.md). -![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](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md). *** @@ -25897,9 +25903,17 @@ A cart has a shipping and billing address. Both of these addresses are represent A line item, represented by the [LineItem](https://docs.medusajs.com/references/cart/models/LineItem/index.html.md) data model, is a quantity of a product variant added to the cart. A cart has multiple line items. +In the Medusa application, a product variant is implemented in the [Product Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/index.html.md). + 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. -In the Medusa application, a product variant is implemented in the [Product Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/product/index.html.md). +*** + +## Shipping and Billing Addresses + +A cart has a shipping and billing address. Both of these addresses are represented by the [Address data model](https://docs.medusajs.com/references/cart/models/Address/index.html.md). + +![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) *** @@ -27400,27 +27414,29 @@ You can remove a registered fulfillment provider from the Medusa application by Then, the next time the Medusa application starts, it will set the `is_enabled` property of the `FulfillmentProvider`'s record to `false`. This allows you to re-enable the fulfillment provider later if needed by adding it back to the `providers` option. -# Item Fulfillment +# Item Fulfillment Concepts -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](https://docs.medusajs.com/references/fulfillment/models/Fulfillment/index.html.md). +A fulfillment can be created to fulfill orders, [returns](../../order/return/), [exchanges](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/exchange/index.html.md), and [claims](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/claim/index.html.md). + *** ## 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](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/fulfillment-provider/index.html.md) 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](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/shipping-option/index.html.md) 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. @@ -27430,7 +27446,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](https://docs.medusajs.com/references/fulfillment/models/FulfillmentItem/index.html.md). The fulfillment item holds details relevant to fulfilling the item, such as barcode, SKU, and quantity to fulfill. @@ -27440,17 +27456,17 @@ 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](https://docs.medusajs.com/references/fulfillment/models/FulfillmentLabel/index.html.md). *** ## Fulfillment Status -The `Fulfillment` data model has three properties to keep track of the current status of the fulfillment: +The [Fulfillment data model](https://docs.medusajs.com/references/fulfillment/models/Fulfillment/index.html.md) 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. # Links between Fulfillment Module and Other Modules @@ -27815,11 +27831,11 @@ createRemoteLinkStep({ # Fulfillment Module Options -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](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/fulfillment/fulfillment-provider/index.html.md). When the Medusa application starts, these providers are registered and can be used to process fulfillments. @@ -27853,7 +27869,7 @@ 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. @@ -28929,9 +28945,22 @@ When a claim is confirmed, the order’s version is incremented. 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](https://docs.medusajs.com/references/order/models/Order/index.html.md). + +An order holds information about: + +- The purchased items. +- The customer who made the order. + - This is stored and handled by the [Customer Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/customer/index.html.md). +- Payment and shipping information + +*** + ## Order Items -The items purchased in the order are represented by the [OrderItem data model](https://docs.medusajs.com/references/order/models/OrderItem/index.html.md). An order can have multiple items. +The items purchased in an order are represented by the [OrderItem data model](https://docs.medusajs.com/references/order/models/OrderItem/index.html.md). 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) @@ -28951,7 +28980,7 @@ Each shipping method is represented by the [OrderShippingMethod data model](http ### 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. @@ -28961,7 +28990,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](https://docs.medusajs.com/references/order/models/OrderSummary/index.html.md). +An order’s total amounts (including tax total, total after an item is returned, etc…) are represented by the [OrderSummary data model](https://docs.medusajs.com/references/order/models/OrderSummary/index.html.md). + +Refer to the [Retrieve Order Totals](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/order-totals/index.html.md) guide to learn how to retrieve an order’s totals. *** @@ -28971,7 +29002,7 @@ 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](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/transactions/index.html.md). +Refer to the [Transactions](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/transactions/index.html.md) guide to learn more. # Order Edit @@ -29610,41 +29641,50 @@ const { data: orders } = useQueryGraphStep({ # Order Change -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](https://docs.medusajs.com/references/order/models/OrderChange/index.html.md) represents any kind of change to an order, such as a return, exchange, or edit. +The [OrderChange data model](https://docs.medusajs.com/references/order/models/OrderChange/index.html.md) represents any kind of change to an order, such as a [return](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md), [exchange](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/exchange/index.html.md), or [edit](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/edit/index.html.md). 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](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/edit/index.html.md). -2. `exchange`: The order change is associated with an exchange, which you can learn about in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/exchange/index.html.md). -3. `claim`: The order change is associated with a claim, which you can learn about in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/claim/index.html.md). -4. `return_request` or `return_receive`: The order change is associated with a return, which you can learn about in [this guide](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md). +1. `edit`: The order change is making edits to the order, as explained in the [Order Edit](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/edit/index.html.md) guide. +2. `exchange`: The order change is associated with an exchange, which you can learn about in the [Order Exchange](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/exchange/index.html.md) guide. +3. `claim`: The order change is associated with a claim, which you can learn about in the [Order Claim](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/claim/index.html.md) guide. +4. `return_request` or `return_receive`: The order change is associated with a return, which you can learn about in the [Order Return](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/order/return/index.html.md) 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](https://docs.medusajs.com/references/order/models/OrderChangeAction/index.html.md). +The actions performed on the original order by an order change, such as adding an item, are represented by the [OrderChangeAction data model](https://docs.medusajs.com/references/order/models/OrderChangeAction/index.html.md). -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. |Action|Description|Details| |---|---|---|---|---| -|\`ITEM\_ADD\`|Add an item to the order.|\`details\`| -|\`ITEM\_UPDATE\`|Update an item in the order.|\`details\`| +|\`ITEM\_ADD\`|Add an item to the order. The item is only added after the change is confirmed.|\`details\`| +|\`ITEM\_UPDATE\`|Update an item in an order change. It's only applied to the order after the change is confirmed.|\`details\`| +|\`ITEM\_REMOVE\`|Remove an item from an order change. This can happen when a claim or an exchange is canceled.|\`details\`| |\`RETURN\_ITEM\`|Set an item to be returned.|\`details\`| |\`RECEIVE\_RETURN\_ITEM\`|Mark a return item as received.|\`details\`| |\`RECEIVE\_DAMAGED\_RETURN\_ITEM\`|Mark a return item that's damaged as received.|\`details\`| -|\`SHIPPING\_ADD\`|Add a shipping method for new or returned items.|No details added. The ID to the shipping method is added in the | -|\`SHIPPING\_ADD\`|Add a shipping method for new or returned items.|No details added. The ID to the shipping method is added in the | -|\`WRITE\_OFF\_ITEM\`|Remove an item's quantity as part of the claim, without adding the quantity back to the item variant's inventory.|\`details\`| +|\`CANCEL\_RETURN\_ITEM\`|Cancel the return of an item. This can happen when a return is canceled.|\`details\`| +|\`SHIPPING\_ADD\`|Add a shipping method to an order change. It's only added to the order after the change is confirmed.|No details added. The ID to the shipping method is added in the | +|\`SHIPPING\_REMOVE\`|Remove a shipping method from an order change. This can happen when a claim or an exchange is canceled.|No details added. The ID to the shipping method is added in the | +|\`SHIP\_ITEM\`|Mark an item's quantity as shipped.|\`details\`| +|\`FULFILL\_ITEM\`|Fulfill an item's quantity as part of a change.|\`details\`| +|\`DELIVER\_ITEM\`|Mark an item's quantity as delivered.|\`details\`| +|\`WRITE\_OFF\_ITEM\`|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.|\`details\`| +|\`REINSTATE\_ITEM\`|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.|\`details\`| +|\`TRANSFER\_CUSTOMER\`|Transfer an order to another customer. The order is not removed from the original customer until the change is confirmed.|No details added. The ID to the new customer is added in the | +|\`UPDATE\_ORDER\_PROPERTIES\`|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.|\`details\`| +|\`CREDIT\_LINE\_ADD\`|Add a credit line to an order. The credit line is not added to the original order until the change is confirmed.|No details added. The ID to the associated payment is added in the | # Retrieve Order Totals Using Query @@ -29982,13 +30022,13 @@ You can't apply filters directly on the order totals, as they are not stored in # Order Versioning -In this document, you’ll learn how an order and its details are versioned. +In this document, you’ll learn how orders and their details are versioned. -## What's Versioning? +## What is Order Versioning? -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. +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 made on an order, such as an item is added or returned, the order's version changes. +When changes are confirmed on an order, such as when an item is added or returned, the order's version changes. *** @@ -29996,18 +30036,18 @@ 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. # Order Module diff --git a/www/apps/resources/app/commerce-modules/cart/concepts/page.mdx b/www/apps/resources/app/commerce-modules/cart/concepts/page.mdx index 5bc68bdb4c..d28f42c42e 100644 --- a/www/apps/resources/app/commerce-modules/cart/concepts/page.mdx +++ b/www/apps/resources/app/commerce-modules/cart/concepts/page.mdx @@ -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. - In the Medusa application, a product variant is implemented in the [Product Module](../../product/page.mdx). +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 diff --git a/www/apps/resources/app/commerce-modules/fulfillment/item-fulfillment/page.mdx b/www/apps/resources/app/commerce-modules/fulfillment/item-fulfillment/page.mdx index 3eaeb0bf5c..3dc6d30192 100644 --- a/www/apps/resources/app/commerce-modules/fulfillment/item-fulfillment/page.mdx +++ b/www/apps/resources/app/commerce-modules/fulfillment/item-fulfillment/page.mdx @@ -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. diff --git a/www/apps/resources/app/commerce-modules/fulfillment/module-options/page.mdx b/www/apps/resources/app/commerce-modules/fulfillment/module-options/page.mdx index 12108594ad..b0da3ff947 100644 --- a/www/apps/resources/app/commerce-modules/fulfillment/module-options/page.mdx +++ b/www/apps/resources/app/commerce-modules/fulfillment/module-options/page.mdx @@ -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. diff --git a/www/apps/resources/app/commerce-modules/order/concepts/page.mdx b/www/apps/resources/app/commerce-modules/order/concepts/page.mdx index 0c1414e7cb..d9d972d7cf 100644 --- a/www/apps/resources/app/commerce-modules/order/concepts/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/concepts/page.mdx @@ -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. diff --git a/www/apps/resources/app/commerce-modules/order/order-change/page.mdx b/www/apps/resources/app/commerce-modules/order/order-change/page.mdx index 5b921c07f8..b486624325 100644 --- a/www/apps/resources/app/commerce-modules/order/order-change/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/order-change/page.mdx @@ -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. @@ -48,7 +49,7 @@ The following table lists the possible `action` values that Medusa uses and what - Add an item to the order. + Add an item to the order. The item is only added after the change is confirmed. @@ -69,8 +70,8 @@ The following table lists the possible `action` values that Medusa uses and what - - 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. @@ -86,6 +87,26 @@ The following table lists the possible `action` values that Medusa uses and what + `ITEM_REMOVE` + + + + + Remove an item from an order change. This can happen when a claim or an exchange is canceled. + + + + + `details` is an object having the following properties: + + - `reference_id`: the ID of the item. + - `quantity`: The quantity to remove. + + + + + + `RETURN_ITEM` @@ -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. @@ -148,17 +168,20 @@ The following table lists the possible `action` values that Medusa uses and what - `SHIPPING_ADD` + `CANCEL_RETURN_ITEM` - Add a shipping method for new or returned items. + Cancel the return of an item. This can happen when a return is canceled. - 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. @@ -170,7 +193,7 @@ The following table lists the possible `action` values that Medusa uses and what - 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. @@ -182,12 +205,92 @@ The following table lists the possible `action` values that Medusa uses and what + `SHIPPING_REMOVE` + + + + + Remove a shipping method from an order change. This can happen when a claim or an exchange is canceled. + + + + + No details added. The ID to the shipping method is added in the `reference_id` property of the action. + + + + + + + `SHIP_ITEM` + + + + + Mark an item's quantity as shipped. + + + + + `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. + + + + + + + `FULFILL_ITEM` + + + + + Fulfill an item's quantity as part of a change. + + + + + `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. + + + + + + + `DELIVER_ITEM` + + + + + Mark an item's quantity as delivered. + + + + + `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. + + + + + + `WRITE_OFF_ITEM` - 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. @@ -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. + + + + + + + `REINSTATE_ITEM` + + + + + 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. + + + + + `details` is an object having the following properties: + + - `reference_id`: the ID of the item. + - `quantity`: The quantity to reinstate. + + + + + + + `TRANSFER_CUSTOMER` + + + + + Transfer an order to another customer. The order is not removed from the original customer until the change is confirmed. + + + + + No details added. The ID to the new customer is added in the `reference_id` property of the action. + + + + + + + `UPDATE_ORDER_PROPERTIES` + + + + + 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. + + + + + `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). + + + + + + + `CREDIT_LINE_ADD` + + + + + Add a credit line to an order. The credit line is not added to the original order until the change is confirmed. + + + + + No details added. The ID to the associated payment is added in the `reference_id` property of the action. diff --git a/www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx b/www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx index 45b64a96ae..57012ce1c9 100644 --- a/www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx @@ -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. diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index b7276355aa..ff542c9749 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -7,7 +7,7 @@ export const generatedEditDates = { "app/commerce-modules/auth/page.mdx": "2025-04-17T08:48:17.286Z", "app/commerce-modules/cart/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/cart/_events/page.mdx": "2024-07-03T19:27:13+03:00", - "app/commerce-modules/cart/concepts/page.mdx": "2024-10-08T07:49:03.737Z", + "app/commerce-modules/cart/concepts/page.mdx": "2025-08-21T14:50:37.130Z", "app/commerce-modules/cart/promotions/page.mdx": "2024-10-08T07:54:31.120Z", "app/commerce-modules/cart/tax-lines/page.mdx": "2024-10-08T07:57:19.168Z", "app/commerce-modules/cart/page.mdx": "2025-04-17T08:48:27.822Z", @@ -22,8 +22,8 @@ export const generatedEditDates = { "app/commerce-modules/fulfillment/_events/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/fulfillment/concepts/page.mdx": "2025-04-24T09:21:37.616Z", "app/commerce-modules/fulfillment/fulfillment-provider/page.mdx": "2025-05-20T07:51:40.707Z", - "app/commerce-modules/fulfillment/item-fulfillment/page.mdx": "2024-10-08T14:38:15.496Z", - "app/commerce-modules/fulfillment/module-options/page.mdx": "2024-10-15T12:51:56.118Z", + "app/commerce-modules/fulfillment/item-fulfillment/page.mdx": "2025-08-21T14:58:42.730Z", + "app/commerce-modules/fulfillment/module-options/page.mdx": "2025-08-21T15:00:29.183Z", "app/commerce-modules/fulfillment/shipping-option/page.mdx": "2025-04-24T09:21:52.540Z", "app/commerce-modules/fulfillment/page.mdx": "2025-05-20T07:51:40.707Z", "app/commerce-modules/inventory/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", @@ -34,9 +34,9 @@ export const generatedEditDates = { "app/commerce-modules/order/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/order/_events/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/order/claim/page.mdx": "2025-02-26T11:23:55.003Z", - "app/commerce-modules/order/concepts/page.mdx": "2024-10-09T10:12:49.399Z", + "app/commerce-modules/order/concepts/page.mdx": "2025-08-21T15:05:58.124Z", "app/commerce-modules/order/exchange/page.mdx": "2025-02-26T11:23:29.845Z", - "app/commerce-modules/order/order-versioning/page.mdx": "2024-10-09T07:41:22.201Z", + "app/commerce-modules/order/order-versioning/page.mdx": "2025-08-21T15:31:58.563Z", "app/commerce-modules/order/promotion-adjustments/page.mdx": "2024-10-09T10:19:19.333Z", "app/commerce-modules/order/return/page.mdx": "2025-02-26T11:22:49.675Z", "app/commerce-modules/order/tax-lines/page.mdx": "2024-10-09T10:22:49.335Z", @@ -2113,7 +2113,7 @@ export const generatedEditDates = { "app/commerce-modules/promotion/links-to-other-modules/page.mdx": "2025-04-17T15:59:11.667Z", "app/commerce-modules/order/edit/page.mdx": "2025-02-26T11:24:28.852Z", "app/commerce-modules/order/links-to-other-modules/page.mdx": "2025-04-17T15:57:52.146Z", - "app/commerce-modules/order/order-change/page.mdx": "2024-10-09T09:59:40.745Z", + "app/commerce-modules/order/order-change/page.mdx": "2025-08-21T15:33:50.982Z", "app/commerce-modules/payment/links-to-other-modules/page.mdx": "2025-04-17T15:53:23.515Z", "references/core_flows/Common/Steps_Common/functions/core_flows.Common.Steps_Common.useQueryGraphStep/page.mdx": "2025-06-25T10:11:28.483Z", "references/core_flows/Payment/Workflows_Payment/functions/core_flows.Payment.Workflows_Payment.processPaymentWorkflow/page.mdx": "2025-08-14T12:59:37.895Z", diff --git a/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs b/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs index 6fb1a4cde0..e3dc0755ad 100644 --- a/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs +++ b/www/apps/resources/generated/generated-commerce-modules-sidebar.mjs @@ -3355,7 +3355,15 @@ const generatedgeneratedCommerceModulesSidebarSidebar = { "isPathHref": true, "type": "link", "path": "/commerce-modules/fulfillment/concepts", - "title": "Fulfillment Concepts", + "title": "General Concepts", + "children": [] + }, + { + "loaded": true, + "isPathHref": true, + "type": "link", + "path": "/commerce-modules/fulfillment/item-fulfillment", + "title": "Item Fulfillment", "children": [] }, { @@ -3374,14 +3382,6 @@ const generatedgeneratedCommerceModulesSidebarSidebar = { "title": "Shipping Option", "children": [] }, - { - "loaded": true, - "isPathHref": true, - "type": "link", - "path": "/commerce-modules/fulfillment/item-fulfillment", - "title": "Item Fulfillment", - "children": [] - }, { "loaded": true, "isPathHref": true, diff --git a/www/apps/resources/sidebars/fulfillment.mjs b/www/apps/resources/sidebars/fulfillment.mjs index 268fe347ef..5168e7d35f 100644 --- a/www/apps/resources/sidebars/fulfillment.mjs +++ b/www/apps/resources/sidebars/fulfillment.mjs @@ -27,7 +27,12 @@ export const fulfillmentSidebar = [ { type: "link", path: "/commerce-modules/fulfillment/concepts", - title: "Fulfillment Concepts", + title: "General Concepts", + }, + { + type: "link", + path: "/commerce-modules/fulfillment/item-fulfillment", + title: "Item Fulfillment", }, { type: "link", @@ -39,11 +44,6 @@ export const fulfillmentSidebar = [ path: "/commerce-modules/fulfillment/shipping-option", title: "Shipping Option", }, - { - type: "link", - path: "/commerce-modules/fulfillment/item-fulfillment", - title: "Item Fulfillment", - }, { type: "link", path: "/commerce-modules/fulfillment/links-to-other-modules",