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
parent d46f9fda21
commit 3e4a96a31c
13 changed files with 297 additions and 338 deletions
@@ -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.