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

2025-08-21 19:09:01 +03:00
1 parent e7b45f5fde
commit 25ed42f740
@@ -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.
@@ -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>
@@ -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.