docs: improve commerce modules [3/n] (#9510)

Improve and add docs for Order and Payment modules [3/n] Closes DOCS-966 Closes #9485
2024-10-14 07:20:35 +00:00
parent 74b286b701
commit 11120a8b7e
30 changed files with 662 additions and 314 deletions
@@ -10,7 +10,7 @@ In this document, you’ll learn about order claims.

 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.
+The [OrderClaim data model](/references/order/models/OrderClaim) represents a claim.

 ---

@@ -25,7 +25,7 @@ The `Claim` data model has a `type` property whose value indicates the type of t

 ## Old and Replacement Items

-When the claim is created, a return is also created to handle receiving the old items from the customer.
+When the claim is created, a return, represented by the [Return data model](/references/order/models/Return), is also created to handle receiving the old items from the customer.

 <Note>

@@ -33,15 +33,15 @@ 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).
+If the claim’s type is `replace`, replacement items are represented by the [ClaimItem data model](/references/order/models/OrderClaimItem).

 ---

 ## 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).
+A claim 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.
+The shipping methods for the returned items are associated with the claim's return, as explained in [this guide](../return/page.mdx#return-shipping-methods).

 ---

@@ -49,10 +49,10 @@ The items returned from the customer are handled by the associated return.

 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.
+The [Transaction data model](/references/order/models/OrderTransaction) 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.
+When a claim is confirmed, the order’s version is incremented.
@@ -14,7 +14,7 @@ The items purchased in the order are represented by the [OrderItem data model](/

 ### Item’s Product Details

-The details of the purchased products are represented by the [LineItem data model](/references/order/models/LineItem). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.
+The details of the purchased products are represented by the [LineItem data model](/references/order/models/OrderLineItem). Not only does a line item hold the details of the product, but also details related to its price, adjustments due to promotions, and taxes.

 ---

@@ -22,15 +22,15 @@ The details of the purchased products are represented by the [LineItem data mode

 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).
+Each shipping method is represented by the [OrderShippingMethod data model](/references/order/models/OrderShippingMethod) that holds its details. The shipping method is linked to the order through the [OrderShipping data model](/references/order/models/OrderShipping).

 ![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

-When fulfilling the order, you may use a third-party fulfillment provider that requires additional custom data to be passed along from the order creation process.
+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.

-The `ShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.
+The `OrderShippingMethod` data model has a `data` property. It’s an object used to store custom data relevant later for fulfillment.

 The Medusa application passes the `data` property to the Fulfillment Module when fulfilling items.

@@ -44,7 +44,7 @@ The order’s total amounts (including tax total, total after an item is returne

 ## Order Payments

-Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [Transaction data model](/references/order/models/Transaction).
+Payments made on an order, whether they’re capture or refund payments, are recorded as transactions represented by the [OrderTransaction data model](/references/order/models/OrderTransaction).

 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.

@@ -0,0 +1,57 @@
+export const metadata = {
+  title: `Order Edit`,
+}
+
+# {metadata.title}
+
+In this document, you'll learn about order edits.
+
+## What is an Order Edit?
+
+A merchant can edit an order to add new items or change the quantity of existing items in the order.
+
+An order edit is represented by the [OrderChange data model](/references/order/models/OrderChange).
+
+The `OrderChange` data model is associated with any type of change, including a return or exchange. However, its `change_type` property distinguishes the type of change it's making.
+
+In the case of an order edit, the `OrderChange`'s type is `edit`.
+
+---
+
+## Add Items in an Order Edit
+
+When the merchant adds new items to the order in the order edit, the item is added as an [OrderItem](/references/order/models/OrderItem).
+
+Also, an `OrderChangeAction` is created. The [OrderChangeAction data model](/references/order/models/OrderChangeAction) represents a change made by an `OrderChange`, such as an item added.
+
+So, when an item is added, an `OrderChangeAction` is created with the type `ITEM_ADD`. In its `details` property, the item's ID, price, and quantity are stored.
+
+---
+
+## Update Items in an Order Edit
+
+A merchant can update an existing item's quantity or price.
+
+This change is added as an `OrderChangeAction` with the type `ITEM_UPDATE`. In its `details` property, the item's ID, new price, and new quantity are stored.
+
+---
+
+## Shipping Methods of New Items in the Edit
+
+Adding new items to the order requires adding shipping methods for those items.
+
+These shipping methods are represented by the [OrderShippingMethod data model](/references/order/models/OrderItem). Also, an `OrderChangeAction` is created with the type `SHIPPING_ADD`
+
+---
+
+## How Order Edits Impact an Order’s Version
+
+When an order edit is confirmed, the order’s version is incremented.
+
+---
+
+## Payments and Refunds for Order Edit Changes
+
+Once the Order Edit is confirmed, any additional payment or refund required can be made on the original order.
+
+This is determined by the comparison between the `OrderSummary` and the order's transactions, as mentioned in [this guide](../transactions/page.mdx#checking-outstanding-amount).
@@ -10,15 +10,17 @@ 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.
+An exchange is the replacement of an item that the customer ordered with another.

-The [Exchange data model](/references/order/models/Exchange) represents an exchange.
+A merchant creates the exchange, specifying the items to be replaced and the new items to be sent.
+
+The [OrderExchange data model](/references/order/models/OrderExchange) 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.
+When the exchange is created, a return, represented by the [Return data model](/references/order/models/Return), is created to handle receiving the items back from the customer.

 <Note>

@@ -26,7 +28,7 @@ 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.
+The [OrderExchangeItem data model](/references/order/models/OrderExchangeItem) represents the new items to be sent to the customer.

 ---

@@ -34,7 +36,7 @@ The [ExchangeItem data model](/references/order/models/ExchangeItem) represents

 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.
+The shipping methods for the returned items are associated with the exchange's return, as explained in [this guide](../return/page.mdx#return-shipping-methods).

 ---

@@ -58,7 +60,7 @@ The `Exchange` data model has a `difference_due` property that stores the outsta
      </Table.Cell>
      <Table.Cell>

-      Merchant refunds the difference_due amount.
+      Merchant owes the customer a refund of the `difference_due` amount.

      </Table.Cell>
    </Table.Row>
@@ -70,7 +72,7 @@ The `Exchange` data model has a `difference_due` property that stores the outsta
      </Table.Cell>
      <Table.Cell>

-      Merchant requires additional payment from the customer.
+      Merchant requires additional payment from the customer of the `difference_due` amount.

      </Table.Cell>
    </Table.Row>
@@ -89,10 +91,10 @@ The `Exchange` data model has a `difference_due` property that stores the outsta
  </Table.Body>
 </Table>

-Any payment or refund made is stored in the [Transaction data model](/references/order/models/Transaction).
+Any payment or refund made is stored in the [Transaction data model](/references/order/models/OrderTransaction).

 ---

 ## How Exchanges Impact an Order’s Version

-When an exchange is created, the order’s version is incremented.
+When an exchange is confirmed, the order’s version is incremented.
@@ -0,0 +1,46 @@
+export const metadata = {
+  title: `Links between Order Module and Other Modules`,
+}
+
+# {metadata.title}
+
+This document showcases the module links defined between the Order Module and other commerce modules.
+
+## Cart Module
+
+The Cart Module provides cart-management features.
+
+Medusa defines a link between the `Order` and `Cart` data models. The order is linked to the cart used for the purchased.
+
+![A diagram showcasing an example of how data models from the Cart and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728375735/Medusa%20Resources/cart-order_ijwmfs.jpg)
+
+---
+
+## Fulfillment Module
+
+A fulfillment is created for an orders' items. Medusa defines a link between the `Fulfillment` and `Order` data models.
+
+![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716549903/Medusa%20Resources/order-fulfillment_h0vlps.jpg)
+
+
+A fulfillment is also created for a return's items. So, Medusa defines a link between the `Fulfillment` and `Return` data models.
+
+![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1728399052/Medusa%20Resources/Social_Media_Graphics_2024_Order_Return_vetimk.jpg)
+
+---
+
+## Payment Module
+
+An order's payment details are stored in a payment collection. This also applies for claims and exchanges.
+
+So, Medusa defines links between the `PaymentCollection` data model and the `Order`, `OrderClaim`, and `OrderExchange` data models.
+
+![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
+
+---
+
+## Promotion Module
+
+An order is associated with the promotion applied on it. Medusa defines a link between the `Order` and `Promotion` data models.
+
+![A diagram showcasing an example of how data models from the Order and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555015/Medusa%20Resources/order-promotion_dgjzzd.jpg)
@@ -0,0 +1,204 @@
+import { Table } from "docs-ui"
+
+export const metadata = {
+  title: `Order Change`,
+}
+
+# {metadata.title}
+
+In this document, you'll learn about the Order Change data model and possible actions in it.
+
+## 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.
+
+Its `change_type` property indicates what the order change is created for:
+
+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).
+
+Once the order change is confirmed, its changes are applied on 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 `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 following table lists the possible `action` values that Medusa uses and what `details` they carry.
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Action</Table.HeaderCell>
+      <Table.HeaderCell>Description</Table.HeaderCell>
+      <Table.HeaderCell className="w-2/4">Details</Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>
+      
+      `ITEM_ADD`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Add an item to the order.
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      `details` is an object having the following properties:
+
+      - `reference_id`: the ID of the new item.
+      - `quantity`: The item's quantity.
+      - `unit_price`: The item's unit price.
+      - `metadata`: The item's metadata.
+
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      `ITEM_UPDATE`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Update an item in the order.
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      `details` is an object having the following properties:
+
+      - `reference_id`: the ID of the item.
+      - `quantity`: The item's quantity.
+      - `unit_price`: The item's unit price.
+
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      `RETURN_ITEM`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Set an item to be returned.
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      `details` is an object having the following properties:
+
+      - `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>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      `RECEIVE_RETURN_ITEM`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Mark a return item as received.
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      `details` is an object having the following properties:
+
+      - `reference_id`: the ID of the item.
+      - `quantity`: The quantity received. This quantity is added to the inventory quantity of the item's variant when the return is confirmed.
+
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      `RECEIVE_DAMAGED_RETURN_ITEM`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Mark a return item that's damaged as received.
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      `details` is an object having the following properties:
+
+      - `reference_id`: the ID of the item.
+      - `quantity`: The quantity received. This quantity isn't added to the item variant's inventory quantity, as the quantity is damaged.
+
+      </Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>
+      
+      `SHIPPING_ADD`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Add a shipping method for new or returned items.
+
+      </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>
+      
+      `SHIPPING_ADD`
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      Add a shipping method for new or returned items.
+
+      </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>
+      
+      `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.
+
+      </Table.Cell>
+      <Table.Cell>
+      
+      `details` is an object having the following properties:
+
+      - `reference_id`: the ID of the item.
+      - `quantity`: The quantity to write off.
+      - `reason`: The claim reason.
+
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
@@ -10,6 +10,8 @@ In this document, you’ll learn how an order and its 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.

+When changes are made on an order, such as an item is added or returned, the order's version changes.
+
 ---

 ## version Property
@@ -6,7 +6,7 @@ export const metadata = {

 # {metadata.title}

-The Order Module is the `@medusajs/medusa/order` NPM package that provides order-related features in your Medusa and Node.js applications.
+The Order Module provides order-related features in your Medusa and Node.js applications.

 ## How to Use Order Module's Service

@@ -15,18 +15,32 @@ You can use the Order Module's main service by resolving from the Medusa contain
 For example:

 <CodeTabs groupId="resource-type">
+  <CodeTab label="Workflow Step" value="workflow-step">
+
+```ts title="src/workflows/hello-world/step1.ts"
+import { createStep } from "@medusajs/framework/workflows-sdk"
+import { Modules } from "@medusajs/framework/utils"
+
+const step1 = createStep("step-1", async (_, { container }) => {
+  const orderModuleService = container.resolve(
+    Modules.ORDER
+  )
+  const orders = await orderModuleService.listOrders()
+})
+```
+
+  </CodeTab>
  <CodeTab label="API Route" value="api-route">

-  ```ts title="src/api/store/custom/route.ts"
-  import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-  import { IOrderModuleService } from "@medusajs/framework/types"
-  import { Modules } from "@medusajs/framework/utils"
+```ts title="src/api/store/custom/route.ts"
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { Modules } from "@medusajs/framework/utils"

 export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
 ): Promise<void> {
-  const orderModuleService: IOrderModuleService = req.scope.resolve(
+  const orderModuleService = req.scope.resolve(
    Modules.ORDER
  )

@@ -39,34 +53,17 @@ export async function GET(
  </CodeTab>
  <CodeTab label="Subscriber" value="subscribers">

-  ```ts title="src/subscribers/custom-handler.ts"
-  import { SubscriberArgs } from "@medusajs/framework"
-  import { IOrderModuleService } from "@medusajs/framework/types"
-  import { Modules } from "@medusajs/framework/utils"
+```ts title="src/subscribers/custom-handler.ts"
+import { SubscriberArgs } from "@medusajs/framework"
+import { Modules } from "@medusajs/framework/utils"

 export default async function subscriberHandler({ container }: SubscriberArgs) {
-  const orderModuleService: IOrderModuleService = container.resolve(
+  const orderModuleService = container.resolve(
    Modules.ORDER
  )

  const orders = await orderModuleService.listOrders()
 }
-```
-
-  </CodeTab>
-  <CodeTab label="Workflow Step" value="workflow-step">
-
-  ```ts title="src/workflows/hello-world/step1.ts"
-  import { createStep } from "@medusajs/framework/workflows-sdk"
-  import { IOrderModuleService } from "@medusajs/framework/types"
-  import { Modules } from "@medusajs/framework/utils"
-
-const step1 = createStep("step-1", async (_, { container }) => {
-  const orderModuleService: IOrderModuleService = container.resolve(
-    Modules.ORDER
-  )
-  const orders = await orderModuleService.listOrders()
-})
 ```

  </CodeTab>
@@ -108,6 +105,7 @@ const draftOrder = await orderModuleService.createOrders({
  currency_code: "usd",
  // other details...
  status: "draft",
+  is_draft_order: true,
 })
 ```

@@ -116,14 +114,14 @@ const draftOrder = await orderModuleService.createOrders({
 Apply promotions or discounts to the order's items and shipping methods by adding adjustment lines that are factored into their subtotals.

 ```ts
-const lineAdjustments = await orderModuleService.addLineItemAdjustments({
+const lineAdjustments = await orderModuleService.createOrderLineItemAdjustments({
  item_id: "cali_123",
  code: "50OFF",
  amount: 500,
 })

 const shippingAdjustments =
-  await orderModuleService.addShippingMethodAdjustments({
+  await orderModuleService.createOrderShippingMethodAdjustments({
    shipping_method_id: "casm_123",
    code: "FREESHIPPING",
    amount: 1000,
@@ -14,7 +14,7 @@ In this document, you’ll learn how a promotion is applied to an order’s item

 An adjustment line indicates a change to a line item or a shipping method’s amount. It’s used to apply promotions or discounts on an order.

-The [LineItemAdjustment data model](/references/order/models/LineItemAdjustment) represents changes on a line item, and the [ShippingMethodAdjustment data model](/references/order/models/ShippingMethodAdjustment) represents changes on a shipping method.
+The [OrderLineItemAdjustment data model](/references/order/models/OrderLineItemAdjustment) represents changes on a line item, and the [OrderShippingMethodAdjustment data model](/references/order/models/OrderShippingMethodAdjustment) represents changes on a shipping method.

 ![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)

@@ -30,7 +30,7 @@ The ID of the applied promotion is stored in the `promotion_id` property of the

 ## Discountable Option

-The `LineItem` data model has an `is_discountable` property that indicates whether promotions can be applied to the line item. It’s enabled by default.
+The `OrderLineItem` data model has an `is_discountable` property that indicates whether promotions can be applied to the line item. It’s enabled by default.

 When disabled, a promotion can’t be applied to a line item. In the context of the Promotion Module, the promotion isn’t applied to the line item even if it matches its rules.

@@ -120,14 +120,14 @@ import {

 // ...

-await orderModuleService.setLineItemAdjustments(
+await orderModuleService.setOrderLineItemAdjustments(
  order.id,
  actions.filter(
    (action) => action.action === "addItemAdjustment"
  ) as AddItemAdjustmentAction[]
 )

-await orderModuleService.setShippingMethodAdjustments(
+await orderModuleService.setOrderShippingMethodAdjustments(
  order.id,
  actions.filter(
    (action) =>
@@ -1,63 +0,0 @@
-export const metadata = {
-  title: `Relations between Order Module and Other Modules`,
-}
-
-# {metadata.title}
-
-This document showcases the link modules defined between the Order Module and other commerce modules.
-
-## Customer Module
-
-An order is associated with the customer that placed it. Medusa defines a link module that builds a relationship between the `Order` and `Customer` data models.
-
-![A diagram showcasing an example of how data models from the Order and Customer modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716545470/Medusa%20Resources/customer-order_pkla6f.jpg)
-
---
-
-## Fulfillment Module
-
-A fulfillment is created for an orders' items. Medusa defines a link module that builds a relationship between the `Fulfillment` and `Order` data models.
-
-![A diagram showcasing an example of how data models from the Fulfillment and Order modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716549903/Medusa%20Resources/order-fulfillment_h0vlps.jpg)
-
---
-
-## Payment Module
-
-An order's payment is stored in a payment collection. Medusa defines a link module that builds a relationship between the `Order` and `PaymentCollection` data models.
-
-![A diagram showcasing an example of how data models from the Order and Payment modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716554726/Medusa%20Resources/order-payment_ubdwok.jpg)
-
---
-
-## Product Module
-
-An order's line item is associated with the purchased product and its variant. Medusa defines a link module that builds a relationship between the `LineItem`, `Product`, and `ProductVariant` data models.
-
-![A diagram showcasing an example of how data models from the Order and Product modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716556100/Medusa%20Resources/order-product_l6ylte.jpg)
-
---
-
-## Promotion Module
-
-An order is associated with the promotion applied on it. Medusa defines a link module that builds a relationship between the `Order` and `Promotion` data models.
-
-![A diagram showcasing an example of how data models from the Order and Promotion modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555015/Medusa%20Resources/order-promotion_dgjzzd.jpg)
-
---
-
-## Region Module
-
-An order is associated with the customer's region. Medusa defines a link module that builds a relationship between the `Order` and `Region` data models.
-
-![A diagram showcasing an example of how data models from the Order and Region modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1716555119/Medusa%20Resources/order-region_ihkp2u.jpg)
-
---
-
-## Sales Channel Module
-
-Orders can be scoped to a sales channel. Medusa defines a link module that builds a relationship between the `Order` and the `SalesChannel` data models.
-
-![A diagram showcasing an example of how resources from the Order and Sales Channel modules are linked](https://res.cloudinary.com/dza7lstvk/image/upload/v1712315409/Medusa%20Resources/order-sales-channel_dy72gx.jpg)
-
-This is useful for omnichannel purposes. Associating an order with a sales channel in turn ensures that associated products, inventory, and other details are also scoped to that sales channel.
@@ -8,9 +8,9 @@ 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 the return of items delivered from 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.
+A return is requested either by the customer from the storefront, or the merchant from the admin. Medusa supports 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)

@@ -22,19 +22,26 @@ Once the merchant receives the returned items, they mark the return as received.

 The items to be returned are represented by the [ReturnItem data model](references/order/models/ReturnItem).

+The `ReturnItem` model has two properties storing the item's quantity:
+
+1. `received_quantity`: The quantity of the item that's received and can be added to the item's inventory quantity.
+2. `damaged_quantity`: The quantity of the item that's damaged, meaning it can't be sold again or added to the item's inventory quantity.
+
 ---

 ## 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).

+In the Medusa application, the shipping method for a return is created only from a shipping option, provided by the Fulfillment Module, that has the rule `is_return` enabled.
+
 ---

 ## 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.
+The [OrderTransaction data model](references/order/models/OrderTransaction) represents the refunds made for the return.

 ---

@@ -14,7 +14,7 @@ In this document, you’ll learn about tax lines in an order.

 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.
+The [OrderLineItemTaxLine data model](/references/order/models/OrderLineItemTaxLine) represents a line item’s tax line, and the [OrderShippingMethodTaxLine data model](/references/order/models/OrderShippingMethodTaxLine) 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)

@@ -34,4 +34,6 @@ The following diagram is a simplified showcase of how a subtotal is calculated f

 </Note>

-![A diagram showcasing how a subtotal is calculated from the tax perspective](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307395/Medusa%20Resources/order-tax-inclusive_oebdnm.jpg)
+![A diagram showcasing how a subtotal is calculated from the tax perspective](https://res.cloudinary.com/dza7lstvk/image/upload/v1712307395/Medusa%20Resources/order-tax-inclusive_oebdnm.jpg)
+
+For example, if a line item's amount is `5000`, the tax rate is `10`, and `is_tax_inclusive` is enabled, the tax amount is 10% of `5000`, which is `500`. The item's unit price becomes `4500`.
@@ -10,10 +10,12 @@ In this document, you’ll learn about an order’s transactions and its use.

 ## What is a Transaction?

-A transaction represents any order payment process, such as capturing or refunding an amount. It’s represented by the [Transaction data model](/references/order/models/Transaction).
+A transaction represents any order payment process, such as capturing or refunding an amount. It’s represented by the [OrderTransaction data model](/references/order/models/OrderTransaction).

 The transaction’s main purpose is to ensure a correct balance between paid and outstanding amounts.

+Transactions are also associated with returns, claims, and exchanges if additional payment or refund is required.
+
 ---

 ## Checking Outstanding Amount
@@ -79,11 +81,13 @@ To check the outstanding amount of the order, its transaction amounts are summed
  </Table.Body>
 </Table>

+---
+
 ## Transaction Reference

 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:
+The `OrderTransaction` 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` from the Payment Module.
 - `reference_id`: indicates the ID of the record in the table. For example, `pay_123`.