diff --git a/www/apps/resources/app/commerce-modules/order/claim/page.mdx b/www/apps/resources/app/commerce-modules/order/claim/page.mdx new file mode 100644 index 0000000000..8d55a6811e --- /dev/null +++ b/www/apps/resources/app/commerce-modules/order/claim/page.mdx @@ -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. + + + +Learn more about returns in [this guide](../return/page.mdx). + + + +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. \ No newline at end of file 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 7c01a388a0..868460fab7 100644 --- a/www/apps/resources/app/commerce-modules/order/concepts/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/concepts/page.mdx @@ -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 diff --git a/www/apps/resources/app/commerce-modules/order/exchange/page.mdx b/www/apps/resources/app/commerce-modules/order/exchange/page.mdx new file mode 100644 index 0000000000..5388fa3fe2 --- /dev/null +++ b/www/apps/resources/app/commerce-modules/order/exchange/page.mdx @@ -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. + + + +Learn more about returns in [this guide](../return/page.mdx). + + + +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. + + + + + Condition + Result + + + + + + + `difference_due < 0` + + + + + Merchant refunds the difference_due amount. + + + + + + + `difference_due > 0` + + + + + Merchant requires additional payment from the customer. + + + + + + + `difference_due = 0` + + + + + No payment processing is required. + + + + +
+ +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. 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 deleted file mode 100644 index 12982241b0..0000000000 --- a/www/apps/resources/app/commerce-modules/order/order-change/page.mdx +++ /dev/null @@ -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. - - - -Order Change is still in development. - - - -## 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. - - - - - Action Name - Description - Expected details - - - - - - - `ITEM_ADD` - - - - - Adds a new item to the order. - - - - - - `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" }` - - - - - - - `ITEM_REMOVE` - - - - - Removes an item from the order. - - - - - - `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" }` - - - - - - - `WRITE_OFF_ITEM` - - - - - Removes a quantity of an item. - - - - - - `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"}` - - - - - - - `RETURN_ITEM` - - - - - Request a return of an item. - - - - - - `quantity`: The quantity to return of the item. - - `reference_id`: The ID of the item to return. - - `{ quantity: 1; reference_id: "orditem_123"}` - - - - - - - `RECEIVE_RETURN_ITEM` - - - - - Mark as received an item whose return was previously requested. - - - - - - `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"}` - - - - - - - `RECEIVE_DAMAGED_RETURN_ITEM` - - - - - 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. - - - - - - `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"}` - - - - - - - `CANCEL_RETURN` - - - - - Cancel a previously requested return of an item. - - - - - - `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"}` - - - - - - - `SHIPPING_ADD` - - - - - Add a shipping method to an item. - - - - - - `amount`: The amount of the shipping. - - `reference_id`: The ID of the shipping method to add. - - `{ amount: 1000; reference_id: "orditem_123"}` - - - - - - - `SHIP_ITEM` - - - - - Mark a quantity of an item as shipped. This modifies the `shipped_quantity` property of an order item. - - - - - - `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"}` - - - - - - - `FULFILL_ITEM` - - - - - Mark a quantity of an item as fulfilled. This modifies the `fulfilled_quantity` property of an order item. - - - - - - `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"}` - - - - - - - `CANCEL` - - - - - Cancel the order change. - - - - - Doesn’t expect any data. - - - - -
- -## 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. 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 9ab2a49786..a30d29c3cc 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 @@ -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. - -![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. +When the order is retrieved, only the related data having the same version is retrieved. diff --git a/www/apps/resources/app/commerce-modules/order/page.mdx b/www/apps/resources/app/commerce-modules/order/page.mdx index 4bd2d898ce..9289451192 100644 --- a/www/apps/resources/app/commerce-modules/order/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/page.mdx @@ -64,36 +64,18 @@ const shippingAdjustments = }) ``` -### Returns, Exchanges, and Other Order Changes +### Returns, Exchanges, and Claims - - -Order Changes are still in development. - - - -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. +Return or exchange items, with version-based control over the order's timeline. ```ts -const orderChange = await orderModuleService.createOrderChange({ - order_id: "ord_123", -}) - -// add item to the order -await orderModuleService.addOrderAction({ - order_change_id: orderChange.id, - action: "ADD_ITEM", - details: { +const orderReturn = await orderModuleService.createReturn({ + order_id: "order_123", + items: [{ + id: "orditem_123", quantity: 1, - unit_price: 4000, - reference_id: "orditem_123", - }, + }] }) - -// confirm order change and apply it to order -await orderModuleService.confirmOrderChange("ord_123") ``` --- diff --git a/www/apps/resources/app/commerce-modules/order/promotion-adjustments/page.mdx b/www/apps/resources/app/commerce-modules/order/promotion-adjustments/page.mdx index c8948e4e09..ae6dfcd62a 100644 --- a/www/apps/resources/app/commerce-modules/order/promotion-adjustments/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/promotion-adjustments/page.mdx @@ -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. + + + +The ID of the applied promotion is stored in the `promotion_id` property of the adjustment line. + + --- @@ -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" } ) ``` diff --git a/www/apps/resources/app/commerce-modules/order/return/page.mdx b/www/apps/resources/app/commerce-modules/order/return/page.mdx new file mode 100644 index 0000000000..b6f99e8d75 --- /dev/null +++ b/www/apps/resources/app/commerce-modules/order/return/page.mdx @@ -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. \ No newline at end of file diff --git a/www/apps/resources/app/commerce-modules/order/tax-lines/page.mdx b/www/apps/resources/app/commerce-modules/order/tax-lines/page.mdx index b3b49240f6..2a98b18bfa 100644 --- a/www/apps/resources/app/commerce-modules/order/tax-lines/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/tax-lines/page.mdx @@ -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) diff --git a/www/apps/resources/app/commerce-modules/order/transactions/page.mdx b/www/apps/resources/app/commerce-modules/order/transactions/page.mdx index 5e01aa1bde..755ba59d37 100644 --- a/www/apps/resources/app/commerce-modules/order/transactions/page.mdx +++ b/www/apps/resources/app/commerce-modules/order/transactions/page.mdx @@ -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: @@ -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`. \ No newline at end of file diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs index 96d02b7f28..badb6d55fe 100644 --- a/www/apps/resources/generated/files-map.mjs +++ b/www/apps/resources/generated/files-map.mjs @@ -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", - "pathname": "/commerce-modules/order/order-change" + "filePath": "/www/apps/resources/app/commerce-modules/order/exchange/page.mdx", + "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" diff --git a/www/apps/resources/generated/sidebar.mjs b/www/apps/resources/generated/sidebar.mjs index 1be600d098..e2dd81a4b3 100644 --- a/www/apps/resources/generated/sidebar.mjs +++ b/www/apps/resources/generated/sidebar.mjs @@ -2299,15 +2299,29 @@ export const generatedSidebar = [ { "loaded": true, "isPathHref": true, - "path": "/commerce-modules/order/order-change", - "title": "Order Change", + "path": "/commerce-modules/order/order-versioning", + "title": "Order Versioning", "children": [] }, { "loaded": true, "isPathHref": true, - "path": "/commerce-modules/order/order-versioning", - "title": "Order Versioning", + "path": "/commerce-modules/order/return", + "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": [] }, { diff --git a/www/apps/resources/sidebar.mjs b/www/apps/resources/sidebar.mjs index 48520d3e53..e6d2fc1677 100644 --- a/www/apps/resources/sidebar.mjs +++ b/www/apps/resources/sidebar.mjs @@ -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",