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

Improve and add docs for Order and Payment modules

[3/n]

Closes DOCS-966
Closes #9485

www/apps/resources/app/commerce-modules/order/claim/page.mdx

@@ -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,34 +25,34 @@ 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>
 
 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).
 
 ---
 
 ## 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.
+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.

www/apps/resources/app/commerce-modules/order/concepts/page.mdx

@@ -14,23 +14,23 @@ 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.
 
 ---
 
 ## 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. 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.
 

www/apps/resources/app/commerce-modules/order/edit/page.mdx

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

www/apps/resources/app/commerce-modules/order/exchange/page.mdx

@@ -10,31 +10,33 @@ 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>
 
 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.
 
 ---
 
 ## 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.
+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.

www/apps/resources/app/commerce-modules/order/links-to-other-modules/page.mdx

@@ -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)