docs: added refund details related to transactions (#13677)

www/apps/book/public/llms-full.txt

@@ -21821,7 +21821,8 @@ If you ran into an error during your installation, refer to the following troubl
 
 1. [create-medusa-app troubleshooting guides](https://docs.medusajs.com/resources/troubleshooting/create-medusa-app-errors/index.html.md).
 2. [CORS errors](https://docs.medusajs.com/resources/troubleshooting/cors-errors/index.html.md).
-3. [All troubleshooting guides](https://docs.medusajs.com/resources/troubleshooting/index.html.md).
+3. [Errors with pnpm](https://docs.medusajs.com/resources/troubleshooting/pnpm/index.html.md).
+4. [All troubleshooting guides](https://docs.medusajs.com/resources/troubleshooting/index.html.md).
 
 If you can't find your error reported anywhere, please open a [GitHub issue](https://github.com/medusajs/medusa/issues/new/choose).
 
@@ -31630,7 +31631,7 @@ For example, if a line item's amount is `5000`, the tax rate is `10`, and `is_ta
 
 # Transactions
 
-In this document, you’ll learn about an order’s transactions and its use.
+In this guide, you’ll learn about order transactions, how to check an order’s outstanding amount, and how transactions relate to payments and refunds.
 
 ## What is a Transaction?
 
@@ -31638,7 +31639,7 @@ A transaction represents any order payment process, such as capturing or refundi
 
 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.
+Transactions are also associated with returns, claims, and exchanges when additional payment or refunds are required.
 
 ***
 
@@ -31656,7 +31657,7 @@ The order’s total amounts are stored in the `OrderSummary`'s `totals` property
 }
 ```
 
-To check the outstanding amount of the order, its transaction amounts (from the `Transaction` records) are summed. Then, the following conditions are checked:
+To check the outstanding amount of an order, the transaction amounts from the `Transaction` records are summed. Then, the following conditions are evaluated:
 
 |Condition|Result|
 |---|---|---|
@@ -31672,8 +31673,39 @@ The Order Module doesn’t provide payment processing functionalities, so it doe
 
 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`.
+- `reference`: indicates the table’s name in the database. For example, `capture` from the [Payment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md).
+- `reference_id`: indicates the ID of the record in the table. For example, `capt_123`.
+
+### Refund Transactions
+
+When a refund is created for an order, an `OrderTransaction` record is created with its `reference` property set to `refund`. The `reference_id` property is set to the ID of the refund record in the [Payment Module](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/payment/index.html.md).
+
+The transaction's `amount` for refunds will be a negative value, indicating that the merchant owes the customer a refund.
+
+#### Example: Retrieve Order's Refunds
+
+To retrieve an order's refunds, you can retrieve the order's transactions using [Query](https://docs.medusajs.com/docs/learn/fundamentals/module-links/query/index.html.md) and filter the transactions by their `reference` property.
+
+For example:
+
+```ts
+const query = container.resolve("query") // or req.scope.resolve("query")
+
+const { data: [order] } = await query.graph({
+  entity: "order",
+  fields: ["*", "transactions.*"],
+  filters: {
+    id: "order_123",
+  }
+})
+
+const refundTransactions = order.transactions?.filter(
+  (t) => t?.reference === "refund"
+)
+
+// calculate total refunded amount as a positive value
+const totalRefunded = refundTransactions?.reduce((acc, t) => acc + Math.abs(t!.amount || 0), 0)
+```
 
 
 # Commerce Modules

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

@@ -6,7 +6,7 @@ export const metadata = {
 
 # {metadata.title}
 
-In this document, you’ll learn about an order’s transactions and its use.
+In this guide, you’ll learn about order transactions, how to check an order’s outstanding amount, and how transactions relate to payments and refunds.
 
 ## What is a Transaction?
 
@@ -14,7 +14,7 @@ A transaction represents any order payment process, such as capturing or refundi
 
 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.
+Transactions are also associated with returns, claims, and exchanges when additional payment or refunds are required.
 
 ---
 
@@ -32,7 +32,7 @@ The order’s total amounts are stored in the `OrderSummary`'s `totals` property
 }
 ```
 
-To check the outstanding amount of the order, its transaction amounts (from the `Transaction` records) are summed. Then, the following conditions are checked:
+To check the outstanding amount of an order, the transaction amounts from the `Transaction` records are summed. Then, the following conditions are evaluated:
 
 <Table>
   <Table.Header>
@@ -89,5 +89,36 @@ The Order Module doesn’t provide payment processing functionalities, so it doe
 
 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`.
+- `reference`: indicates the table’s name in the database. For example, `capture` from the [Payment Module](../../payment/page.mdx).
+- `reference_id`: indicates the ID of the record in the table. For example, `capt_123`.
+
+### Refund Transactions
+
+When a refund is created for an order, an `OrderTransaction` record is created with its `reference` property set to `refund`. The `reference_id` property is set to the ID of the refund record in the [Payment Module](../../payment/page.mdx).
+
+The transaction's `amount` for refunds will be a negative value, indicating that the merchant owes the customer a refund.
+
+#### Example: Retrieve Order's Refunds
+
+To retrieve an order's refunds, you can retrieve the order's transactions using [Query](!docs!/learn/fundamentals/module-links/query) and filter the transactions by their `reference` property.
+
+For example:
+
+```ts
+const query = container.resolve("query") // or req.scope.resolve("query")
+
+const { data: [order] } = await query.graph({
+  entity: "order",
+  fields: ["*", "transactions.*"],
+  filters: {
+    id: "order_123",
+  }
+})
+
+const refundTransactions = order.transactions?.filter(
+  (t) => t?.reference === "refund"
+)
+
+// calculate total refunded amount as a positive value
+const totalRefunded = refundTransactions?.reduce((acc, t) => acc + Math.abs(t!.amount || 0), 0)
+```

www/apps/resources/generated/edit-dates.mjs

@@ -40,7 +40,7 @@ export const generatedEditDates = {
   "app/commerce-modules/order/promotion-adjustments/page.mdx": "2024-10-09T10:19:19.333Z",
   "app/commerce-modules/order/return/page.mdx": "2025-02-26T11:22:49.675Z",
   "app/commerce-modules/order/tax-lines/page.mdx": "2024-10-09T10:22:49.335Z",
-  "app/commerce-modules/order/transactions/page.mdx": "2025-09-01T15:06:16.923Z",
+  "app/commerce-modules/order/transactions/page.mdx": "2025-10-03T10:35:16.560Z",
   "app/commerce-modules/order/page.mdx": "2025-08-26T09:21:49.780Z",
   "app/commerce-modules/payment/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00",
   "app/commerce-modules/payment/_events/page.mdx": "2024-07-03T19:27:13+03:00",