docs: update order module's conceptual guides (#7893)

* fixes + add return document * update order conceptual guides * resolve todo * re-generate files map
2024-07-09 18:14:30 +03:00
1 parent d46f9fda21
commit 3e4a96a31c
@@ -0,0 +1,58 @@
 export const metadata = {
  title: `Order Claim`,
 }
 # {metadata.title}
 In this document, you’ll learn about order claims.
 ## What is a Claim?
 When a customer receives a defective or incorrect item, the merchant can create a claim to refund or replace the item.
 The [Claim data model](/references/order/models/Claim) represents a claim.
 ---
 ## Claim Type
 The `Claim` data model has a `type` property whose value indicates the type of the claim:
 - `refund`: the items are returned, and the customer is refunded.
 - `replace`: the items are returned, and the customer receives new items.
 ---
 ## Old and Replacement Items
 When the claim is created, a return is also created to handle receiving the old items from the customer.
 <Note>
 Learn more about returns in [this guide](../return/page.mdx).
 </Note>
 If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](/references/order/models/ClaimItem).
 ---
 ## Claim Shipping Methods
 An exchange uses shipping methods to send the replacement items to the customer. These methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
 The items returned from the customer are handled by the associated return.
 ---
 ## Claim Refund
 If the claim’s type is `refund`, the amount to be refunded is stored in the `refund_amount` property.
 The [Transaction data model](/references/order/models/Transaction) represents the refunds made for the claim.
 ---
 ## How Claims Impact an Order’s Version
 When an exchange is created, the order’s version is incremented.
@@ -20,7 +20,11 @@ The details of the purchased products are represented by the [LineItem data mode
 ## 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](/references/order/models/ShippingMethod) 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. The shipping method is linked to the order through the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
 ![A diagram showcasing the relation between an order and its items.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719570409/Medusa%20Resources/order-shipping-method_tkggvd.jpg)
 ### data Property
@@ -0,0 +1,98 @@
 import { Table } from "docs-ui"
 export const metadata = {
  title: `Order Exchange`,
 }
 # {metadata.title}
 In this document, you’ll learn about order exchanges.
 ## What is an Exchange?
 An exchange is the replacement of an item that the customer ordered with another. A merchant creates the exchange, specifying the items to be replaced and the new items to be sent.
 The [Exchange data model](/references/order/models/Exchange) represents an exchange.
 ---
 ## Returned and New Items
 When the exchange is created, a return is created to handle receiving the items back from the customer.
 <Note>
 Learn more about returns in [this guide](../return/page.mdx).
 </Note>
 The [ExchangeItem data model](/references/order/models/ExchangeItem) represents the new items to be sent to the customer.
 ---
 ## Exchange Shipping Methods
 An exchange has shipping methods used to send the new items to the customer. They’re represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod).
 The items returned from the customer are handled by the associated return.
 ---
 ## Exchange Payment
 The `Exchange` data model has a `difference_due` property that stores the outstanding amount.
 <Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell>Condition</Table.HeaderCell>
      <Table.HeaderCell>Result</Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>
      `difference_due < 0`
      </Table.Cell>
      <Table.Cell>
      Merchant refunds the difference_due amount.
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `difference_due > 0`
      </Table.Cell>
      <Table.Cell>
      Merchant requires additional payment from the customer.
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `difference_due = 0`
      </Table.Cell>
      <Table.Cell>
      No payment processing is required.
      </Table.Cell>
    </Table.Row>
  </Table.Body>
 </Table>
 Any payment or refund made is stored in the [Transaction data model](/references/order/models/Transaction).
 ---
 ## How Exchanges Impact an Order’s Version
 When an exchange is created, the order’s version is incremented.
@@ -1,286 +0,0 @@
 import { Table } from "docs-ui"
 export const metadata = {
  title: `Order Change`,
 }
 # {metadata.title}
 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 a merchant suggests exchanging an item with another.
 Order changes are represented by the [OrderChange data model](/references/order/models/OrderChange).
 ---
 ## Order Change Actions
 An order change can have multiple underlying actions. For example, to exchange an item, you have to:
 - Mark an item as returned.
 - Arrange to receive the item from the customer.
 - 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](/references/order/models/OrderChangeAction).
 ### Action Name
 The `action` property of the `OrderChangeAction` holds the name of the action to perform. Based on the action, additional details are stored in the `details` object property of the data model.
 <Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell>Action Name</Table.HeaderCell>
      <Table.HeaderCell>Description</Table.HeaderCell>
      <Table.HeaderCell>Expected details</Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>
      `ITEM_ADD`
      </Table.Cell>
      <Table.Cell>
      Adds a new item to the order.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity of the item to add.
      - `unit_price`: The price of the item.
      - `reference_id`: The ID of the item to add.
      For example:
      `{ quantity: 1; unit_price: 1000; reference_id: "orditem_123" }`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `ITEM_REMOVE`
      </Table.Cell>
      <Table.Cell>
      Removes an item from the order.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity of the item to remove.
      - `unit_price`: The price of the item.
      - `reference_id`: The ID of the item to remove.
      For example:
      `{ quantity: 1; unit_price: 1000; reference_id: "orditem_123" }`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `WRITE_OFF_ITEM`
      </Table.Cell>
      <Table.Cell>
      Removes a quantity of an item.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity to remove of the item.
      - `reference_id`: The ID of the item to remove its quantity.
      `{ quantity: 1; reference_id: "orditem_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `RETURN_ITEM`
      </Table.Cell>
      <Table.Cell>
      Request a return of an item.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity to return of the item.
      - `reference_id`: The ID of the item to return.
      `{ quantity: 1; reference_id: "orditem_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `RECEIVE_RETURN_ITEM`
      </Table.Cell>
      <Table.Cell>
      Mark as received an item whose return was previously requested.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity received of the item.
      - `reference_id`: The ID of the item to mark its return as received.
      `{ quantity: 1; reference_id: "orditem_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `RECEIVE_DAMAGED_RETURN_ITEM`
      </Table.Cell>
      <Table.Cell>
      Mark as received an item whose return was previously requested, but consider the items damaged.
      This changes the order item’s `return_dismissed_quantity` property rather than its `return_received_quantity` property.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity received of the item.
      - `reference_id`: The ID of the item to mark its return as received.
      `{ quantity: 1; reference_id: "orditem_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `CANCEL_RETURN`
      </Table.Cell>
      <Table.Cell>
      Cancel a previously requested return of an item.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity to cancel its return request.
      - `unit_price`: The price of the item.
      - `reference_id`: The ID of the item to cancel its return request.
      `{ quantity: 1; unit_price: 1000; reference_id: "orditem_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `SHIPPING_ADD`
      </Table.Cell>
      <Table.Cell>
      Add a shipping method to an item.
      </Table.Cell>
      <Table.Cell>
      - `amount`: The amount of the shipping.
      - `reference_id`: The ID of the shipping method to add.
      `{ amount: 1000; reference_id: "orditem_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `SHIP_ITEM`
      </Table.Cell>
      <Table.Cell>
      Mark a quantity of an item as shipped. This modifies the `shipped_quantity` property of an order item.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity of the item to ship.
      - `reference_id`: The ID of the item to mark its specified quantity as shipped.
      `{ quantity: 1; reference_id: "ordli_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `FULFILL_ITEM`
      </Table.Cell>
      <Table.Cell>
      Mark a quantity of an item as fulfilled. This modifies the `fulfilled_quantity` property of an order item.
      </Table.Cell>
      <Table.Cell>
      - `quantity`: The quantity of the item to ship.
      - `reference_id`: The ID of the item to mark its specified quantity as shipped.
      `{ quantity: 1; reference_id: "ordli_123"}`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
      `CANCEL`
      </Table.Cell>
      <Table.Cell>
      Cancel the order change.
      </Table.Cell>
      <Table.Cell>
      Doesn’t expect any data.
      </Table.Cell>
    </Table.Row>
  </Table.Body>
 </Table>
 ## Order Change Confirmation
 The `OrderChange` data model has a `status` property 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 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.
@@ -14,20 +14,17 @@ Versioning means assigning a version number to a record, such as an order and it
 ## version Property
-The `Order` and `OrderSummary` data models have a `version` property that indicates the current order version. By default, its value is `1`.
+The `Order` and `OrderSummary` data models have a `version` property that indicates the current version. By default, its value is `1`.
-The `OrderItem` data model also has a `version` property, but it indicates the version it belongs to. For example, original items in the order have version `1`. Then, when a new item is added, its version is `2`. If an existing item is modified, such as its quantity has been changed, its version is updated.
+Other order-related data models, such as `OrderItem`, also has a `version` property, but it indicates the version it belongs to.
 ---
-## Order Change Versioning
+## How the Version Changes
-The `OrderChange` and `OrderChangeAction` data models also have a `version` property. When an order change is created, the `version` property’s value is the associated order’s version incremented.
+When the order is changed, such as an item is exchanged, this changes the version of the order and its related data:
-So, if the order’s `version` is `1`, the order change’s version is `2`.
+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.
-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.
+When the order is retrieved, only the related data having the same version is retrieved.
 ![A diagram showcasing how the version of an order changes](https://res.cloudinary.com/dza7lstvk/image/upload/v1712304242/Medusa%20Resources/order-versioning_rsx2rn.jpg)
 Order items change depending on the version they were added or modified in, as explained in the earlier section.
@@ -64,36 +64,18 @@ const shippingAdjustments =
  })
 ```
-### Returns, Exchanges, and Other Order Changes
+### Returns, Exchanges, and Claims
-<Note title="In Development" type="soon">
+Return or exchange items, with version-based control over the order's timeline.
 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.
 ```ts
-const orderChange = await orderModuleService.createOrderChange({
+const orderReturn = await orderModuleService.createReturn({
-  order_id: "ord_123",
+  order_id: "order_123",
-})
+  items: [{
-
+    id: "orditem_123",
 // add item to the order
 await orderModuleService.addOrderAction({
  order_change_id: orderChange.id,
  action: "ADD_ITEM",
  details: {
    quantity: 1,
-    unit_price: 4000,
+  }]
    reference_id: "orditem_123",
  },
 })
 // confirm order change and apply it to order
 await orderModuleService.confirmOrderChange("ord_123")
 ```
 ---
@@ -18,7 +18,13 @@ The [LineItemAdjustment data model](/references/order/models/LineItemAdjustment)
 ![A diagram showcasing the relation between an order, its items and shipping methods, and their adjustment lines](https://res.cloudinary.com/dza7lstvk/image/upload/v1712306017/Medusa%20Resources/order-adjustments_myflir.jpg)
-The `amount` property 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` property of the adjustment line.
+The `amount` property of the adjustment line indicates the amount to be discounted from the original amount.
 <Note title="Tip">
 The ID of the applied promotion is stored in the `promotion_id` property of the adjustment line.
 </Note>
 ---
@@ -55,7 +61,7 @@ import {
 const order = await orderModuleService.retrieveOrder("ord_123", {
  relations: [
    "items.item.adjustments",
-    "shipping_methods.adjustments",
+    "shipping_methods.shipping_method.adjustments",
  ],
 })
 // retrieve the line item adjustments
@@ -95,6 +101,8 @@ const actions = await promotionModuleService.computeActions(
  {
    items: lineItemAdjustments,
    shipping_methods: shippingMethodAdjustments,
    // TODO infer from cart or region
    currency_code: "usd"
  }
 )
 ```
@@ -0,0 +1,54 @@
 export const metadata = {
  title: `Order Return`,
 }
 # {metadata.title}
 In this document, you’ll learn about order returns.
 ## What is a Return?
 A return is the return of items delivered to the customer back to the merchant. It is represented by the [Return data model](/references/order/models/Return).
 A return is requested either by the customer or the merchant, supporting an automated Return Merchandise Authorization (RMA) flow.
 ![Diagram showcasing the automated RMA flow.](https://res.cloudinary.com/dza7lstvk/image/upload/v1719578128/Medusa%20Resources/return-rma_pzprwq.jpg)
 Once the merchant receives the returned items, they mark the return as received.
 ---
 ## Returned Items
 The items to be returned are represented by the [ReturnItem data model](references/order/models/ReturnItem).
 ---
 ## Return Shipping Methods
 A return has shipping methods used to return the items to the merchant. The shipping methods are represented by the [OrderShippingMethod data model](references/order/models/OrderShippingMethod).
 ---
 ## Refund Payment
 The `refund_amount` property of the `Return` data model holds the amount a merchant must refund the customer.
 The [Transaction data model](references/order/models/Transaction) represents the refunds made for the return.
 ---
 ## Returns in Exchanges and Claims
 When a merchant creates an exchange or a claim, it includes returning items from the customer.
 The `Return` data model also represents the return of these items. In this case, the return is associated with the exchange or claim it was created for.
 ---
 ## How Returns Impact an Order’s Version
 The order’s version is incremented when:
 1. A return is requested.
 2. A return is marked as received.
@@ -12,7 +12,9 @@ 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](/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.
+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.
 ![A diagram showcasing the relation between orders, items and shipping methods, and tax lines](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307225/Medusa%20Resources/order-tax-lines_sixujd.jpg)
@@ -18,7 +18,19 @@ The transaction’s main purpose is to ensure a correct balance between paid and
 ## Checking Outstanding Amount
-The order’s total is stored in the `OrderSummary`'s `total` property. To check the outstanding amount of the order, its transaction amounts are summed. Then, the following conditions are checked:
+The order’s total amounts are stored in the `OrderSummary`'s `totals` property, which is a JSON object holding the total details of the order.
 ```json
 {
  "totals": {
    "total": 30,
    "subtotal": 30,
    // ...
  }
 }
 ```
 To check the outstanding amount of the order, its transaction amounts are summed. Then, the following conditions are checked:
 <Table>
  <Table.Header>
@@ -71,9 +83,9 @@ The order’s total is stored in the `OrderSummary`'s `total` property. To check
 ## 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 Order Module doesn’t provide payment processing functionalities, so it doesn’t store payments that can be processed. Payment functionalities are provided by the [Payment Module](../../payment/page.mdx).
 The `Transaction` data model has two properties 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`: indicates the table’s name in the database. For example, `payment` from the Payment Module.
 - `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.
@@ -303,13 +303,17 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/commerce-modules/order/_events/page.mdx",
    "pathname": "/commerce-modules/order/_events"
  },
  {
    "filePath": "/www/apps/resources/app/commerce-modules/order/claim/page.mdx",
    "pathname": "/commerce-modules/order/claim"
  },
  {
    "filePath": "/www/apps/resources/app/commerce-modules/order/concepts/page.mdx",
    "pathname": "/commerce-modules/order/concepts"
  },
  {
-    "filePath": "/www/apps/resources/app/commerce-modules/order/order-change/page.mdx",
+    "filePath": "/www/apps/resources/app/commerce-modules/order/exchange/page.mdx",
-    "pathname": "/commerce-modules/order/order-change"
+    "pathname": "/commerce-modules/order/exchange"
  },
  {
    "filePath": "/www/apps/resources/app/commerce-modules/order/order-versioning/page.mdx",
@@ -327,6 +331,10 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/commerce-modules/order/relations-to-other-modules/page.mdx",
    "pathname": "/commerce-modules/order/relations-to-other-modules"
  },
  {
    "filePath": "/www/apps/resources/app/commerce-modules/order/return/page.mdx",
    "pathname": "/commerce-modules/order/return"
  },
  {
    "filePath": "/www/apps/resources/app/commerce-modules/order/tax-lines/page.mdx",
    "pathname": "/commerce-modules/order/tax-lines"
@@ -2299,15 +2299,29 @@ export const generatedSidebar = [
              {
                "loaded": true,
                "isPathHref": true,
-                "path": "/commerce-modules/order/order-change",
+                "path": "/commerce-modules/order/order-versioning",
-                "title": "Order Change",
+                "title": "Order Versioning",
                "children": []
              },
              {
                "loaded": true,
                "isPathHref": true,
-                "path": "/commerce-modules/order/order-versioning",
+                "path": "/commerce-modules/order/return",
-                "title": "Order Versioning",
+                "title": "Return",
                "children": []
              },
              {
                "loaded": true,
                "isPathHref": true,
                "path": "/commerce-modules/order/exchange",
                "title": "Exchange",
                "children": []
              },
              {
                "loaded": true,
                "isPathHref": true,
                "path": "/commerce-modules/order/claim",
                "title": "Claim",
                "children": []
              },
              {
@@ -514,14 +514,22 @@ export const sidebar = sidebarAttachHrefCommonOptions([
                path: "/commerce-modules/order/transactions",
                title: "Transactions",
              },
              {
                path: "/commerce-modules/order/order-change",
                title: "Order Change",
              },
              {
                path: "/commerce-modules/order/order-versioning",
                title: "Order Versioning",
              },
              {
                path: "/commerce-modules/order/return",
                title: "Return",
              },
              {
                path: "/commerce-modules/order/exchange",
                title: "Exchange",
              },
              {
                path: "/commerce-modules/order/claim",
                title: "Claim",
              },
              {
                path: "/commerce-modules/order/relations-to-other-modules",
                title: "Relations to Other Modules",