@spree/docs 0.1.286 → 0.1.288

package/dist/api-reference/store.yaml

@@ -12427,6 +12427,14 @@ components:
           type: string
         paid_amount:
           type: string
+        pre_tax_amount:
+          type: string
+        included_tax_total:
+          type: string
+        additional_tax_total:
+          type: string
+        tax_total:
+          type: string
         display_refund_amount:
           type: string
         variant_id:
@@ -12447,6 +12455,10 @@ components:
       - description
       - refund_amount
       - paid_amount
+      - pre_tax_amount
+      - included_tax_total
+      - additional_tax_total
+      - tax_total
       - display_refund_amount
       - variant_id
       - replacement_variant_id
@@ -13246,6 +13258,7 @@ components:
             - cod
             - payment
             - duty
+            - exchange
           - type: string
           description: What sort of charge this is. `duty` is a customs duty on a
             cross-border order and is not taxed; the other kinds are. Extensions may
@@ -15019,6 +15032,18 @@ components:
           type: string
         display_pre_tax_amount:
           type: string
+        included_tax_total:
+          type: string
+        additional_tax_total:
+          type: string
+        tax_total:
+          type: string
+        display_tax_total:
+          type: string
+        refund_amount:
+          type: string
+        display_refund_amount:
+          type: string
         variant_id:
           type: string
           nullable: true
@@ -15037,6 +15062,12 @@ components:
       - resellable
       - pre_tax_amount
       - display_pre_tax_amount
+      - included_tax_total
+      - additional_tax_total
+      - tax_total
+      - display_tax_total
+      - refund_amount
+      - display_refund_amount
       - variant_id
       - line_item_id
       - fulfillment_item_id
@@ -15084,6 +15115,10 @@ components:
           type: string
         display_refund_total:
           type: string
+        refund_tax_total:
+          type: string
+        display_refund_tax_total:
+          type: string
         approved_at:
           type: string
           nullable: true
@@ -15110,6 +15145,8 @@ components:
       - reason_id
       - refund_total
       - display_refund_total
+      - refund_tax_total
+      - display_refund_tax_total
       - approved_at
       - received_at
       - refunded_at
@@ -15391,6 +15428,8 @@ components:
           type: string
         included:
           type: boolean
+        credit:
+          type: boolean
         rate:
           type: string
         tax_rate_id:
@@ -15405,6 +15444,15 @@ components:
         fee_id:
           type: string
           nullable: true
+        return_line_item_id:
+          type: string
+          nullable: true
+        claim_line_item_id:
+          type: string
+          nullable: true
+        exchange_line_item_id:
+          type: string
+          nullable: true
         amount:
           type: string
           nullable: true
@@ -15415,11 +15463,15 @@ components:
       - id
       - label
       - included
+      - credit
       - rate
       - tax_rate_id
       - line_item_id
       - fulfillment_id
       - fee_id
+      - return_line_item_id
+      - claim_line_item_id
+      - exchange_line_item_id
       - amount
       - display_amount
       x-typelizer: true

package/dist/developer/core-concepts/fees.md

@@ -44,6 +44,7 @@ When neither ID is set, the fee applies to the whole order.
 | `cod` | Cash on delivery |
 | `payment` | A payment method surcharge |
 | `duty` | Customs duty — see [below](#customs-duties) |
+| `exchange` | What a customer owes when an [exchange](returns-exchanges-claims.md#settling-the-difference)'s replacement costs more. Spree adds it; you don't |
 
 The list is open — an extension can add its own kind.
 

package/dist/developer/core-concepts/reporting.md

@@ -129,6 +129,10 @@ the period of the original order. A report over a past range can therefore
 change after the fact, which is the conventional treatment and the only one an
 open accounting period can produce.
 
+A refund from a return, claim or exchange gives tax back with the goods, so it
+is split: the goods come off `returns` and `net_sales`, and the tax comes off
+`taxes`. `total_sales` loses the whole refund.
+
 `cost_of_goods`, `gross_profit` and `gross_margin` read the line item's
 `cost_price`. That column is nullable, so a variant with no cost contributes
 zero and margin over an incompletely-costed catalogue reads high.

package/dist/developer/core-concepts/returns-exchanges-claims.md

@@ -116,6 +116,14 @@ Receiving takes the quantities the warehouse actually counted, because partial a
 
 Leave `items` out to receive everything as requested. Refunds default to whatever the return is still owed, and can go back to the original payment method or to store credit. A returned item is worth what the customer paid for it after discounts, not its list price, so a free gift sent back refunds nothing. Refunding a return that is owed nothing completes it with no money moved and no refund email; an amount of zero is refused on any return the customer is still owed money on.
 
+### Tax on returns
+
+A return gives back the tax the customer paid on what came back. A $25.00 shirt sold with 10% tax added on top refunds $27.50, and on a store whose prices include VAT the VAT inside the price goes back with it. Delivery and its tax are not refunded.
+
+Each return line shows its worth the way an order line does: `pre_tax_amount` before tax, `included_tax_total` and `additional_tax_total` beside it, and `refund_amount` with the tax included. The return's `refund_tax_total` says how much of `refund_total` is tax, and `expand=return_line_items.tax_lines` (Admin API) lists the tax given back rate by rate.
+
+The store's [tax provider](taxes.md) works this out when the return opens, and again just before the money goes back, for the units the warehouse counted. Refunding less than the return is worth — keeping a restocking fee, say — gives the tax back in the same proportion as the goods. If the tax service cannot answer, the return is not opened (or not refunded) and the customer can try again. Claims and exchanges follow the same rules.
+
 ### Where the goods come back to
 
 A return is received at a stock location. By default that is wherever the goods
@@ -191,9 +199,32 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/claim_x
 
 A replacement creates a new [fulfillment](fulfillments.md) on the original order, so the customer doesn't have to place a second one.
 
-The replacement is filed under the order line it replaces, but it doesn't count toward that line's quantity. Editing the line later, from a claim or an [exchange](#exchanges), adds or removes only the goods the customer paid for and leaves the replacement where it is.
+The replacement is filed under the order line it replaces, but it doesn't count toward that line's quantity. Editing the line later, from a claim or an [exchange](#exchanges), adds or removes only the goods the customer paid for and leaves the replacement where it is. Adding a fulfillment for that line works the same way: it takes only the goods the customer paid for, and the replacement stays in its own fulfillment.
+
+If a replacement's fulfillment is canceled, for example because the courier lost the booking, send the goods again by naming that fulfillment as the source of a new one. The new fulfillment takes everything the canceled one held and reserves its stock again. It is priced like any new fulfillment, so pass `cost: 0` to carry over the canceled fulfillment's delivery cost instead, which keeps a free replacement free.
+
+
+```typescript Admin SDK
+await adminClient.orders.fulfillments.create('or_xxx', {
+  stock_location_id: 'sloc_xxx',
+  source_fulfillment_id: 'ful_xxx', // the canceled replacement fulfillment
+  cost: 0,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "stock_location_id": "sloc_xxx",
+    "source_fulfillment_id": "ful_xxx",
+    "cost": 0
+  }'
+```
 
-A claim never refunds more than the customer paid for the claimed items after discounts. Each claim line reports that ceiling as `paid_amount`.
+
+A claim never refunds more than the customer paid for the claimed items after discounts, tax included. Each claim line reports that ceiling as `paid_amount`, and the `refund_amount` you enter for a line includes its tax. The tax goes back in proportion to the money: refunding half of what a line is worth gives back half its tax, and resolving with a replacement alone gives none back.
 
 ## Exchanges
 
@@ -218,6 +249,16 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch
 ```
 
 
+### Settling the difference
+
+An exchange credits what came back and sells the replacement, each with its tax:
+
+- `original_price` is what the customer paid for the items coming back, after discounts and with their tax.
+- `new_variant_price` is the replacement, with its own tax. It keeps the deal the customer had: an item bought at 10% off is replaced at 10% off its price, so swapping a size costs nothing.
+- `price_difference` is the second less the first.
+
+When you fulfill, a cheaper replacement refunds the difference, to store credit or the original payment. A dearer one adds the difference to the order as an `exchange` [fee](fees.md), so the order shows a balance due. Spree never charges a stored card for it; take the payment through the order's [payments](payments.md).
+
 ## Reporting
 
 Because each one is its own record, you can query them directly:

package/dist/developer/core-concepts/sellers.md

@@ -325,6 +325,8 @@ The amount is payment-source-agnostic — store credit and gift cards are how th
 
 A refund never edits an earning. `refund.created` writes a second row of kind `refund_reversal` against the same order, so what a seller has earned is always the sum of their transfers, and a reversal that lands after a payout closed falls into the next period rather than rewriting a settlement that already happened.
 
+A reversal takes back only the seller's share of what was refunded. When a return or claim refunds goods and their tax, the goods come back less the commission charged on them; the tax comes back from the seller only if the seller collected it, and stays with the marketplace when the marketplace remits it.
+
 ### Payouts — what was sent
 
 On schedule, a seller's confirmed, unsettled earnings are batched into one `Spree::SellerPayout` per currency and handed to the provider. A payout names exactly which transfers it settled, which is what a seller needs to reconcile a deposit.

package/dist/developer/core-concepts/taxes.md

@@ -148,6 +148,8 @@ Whatever works out the tax, the record is the same: a tax line per charge, sayin
 | `included` | Whether the tax was already inside the displayed price |
 | `amount` / `display_amount` | The tax charged |
 | `line_item_id` / `fulfillment_id` / `fee_id` | What was taxed — exactly one is set |
+| `return_line_item_id` / `claim_line_item_id` / `exchange_line_item_id` | After the sale: the return, claim or exchange line the tax belongs to |
+| `credit` | `true` for tax given back on a return, claim or exchange |
 
 
 ```typescript Admin SDK
@@ -166,6 +168,10 @@ Each line also keeps its own copy of the rate and label. If someone edits that t
 
 You never create tax lines yourself; they're written whenever the total is worked out.
 
+### Tax given back
+
+When a customer returns something, the tax they paid on it goes back with the money. That tax is recorded as tax lines too, marked `credit`, on the [return, claim or exchange](returns-exchanges-claims.md) line rather than the order line. Each one names the sale's tax line it gives back (`original_tax_line_id`, Admin API), keeps that line's rate and label, and covers only the units that came back. They never change the order's own tax totals, and the order's tax lines list above shows only what was charged.
+
 ## When tax is worked out
 
 Tax is recalculated whenever the answer could have changed — an item added, an address entered, a delivery option chosen. Every one of those requests returns the updated cart, so a storefront never needs a separate "refresh the tax" call.
@@ -204,6 +210,27 @@ A provider declares up front what it cannot do — no US local tax, no reverse c
 
 Whichever provider is in use, the result is the same: tax lines on the order, in the same shape. Your storefront code doesn't change.
 
+The provider also decides the tax given back on returns, claims and exchanges, and the refund pays exactly what it answers. Spree's own rates give back each returned unit's share of the tax the sale actually charged, so the customer gets back what they paid even if a rate has been edited since. An external service may calculate it itself instead, for example at the rates in force on the day of the sale. If it cannot be reached, the return is refused until it can, rather than refunding tax nobody worked out.
+
+If you are writing a provider, these are the calls Spree makes after the sale:
+
+| Method | When | What it does |
+|---|---|---|
+| `estimate_refund` | A return, claim or exchange opens, and again before its money moves | Writes the credit tax lines the refund will carry |
+| `estimate_replacement` | An exchange opens and is fulfilled | Taxes the replacement as a new sale |
+| `refund` | After the money has moved | Files the credit with your service — no more than the credit lines hold |
+| `commit_replacement` | After an exchange is fulfilled | Files the replacement sale |
+
+`estimate_refund` and `estimate_replacement` have no default — a provider without them cannot open a return, claim or exchange. To give back exactly what the sale charged, as Spree's own rates do, answer `estimate_refund` with `Spree::TaxProvider::RecordedShare`:
+
+```ruby server/app/models/my_app/tax_provider.rb
+def estimate_refund(order, items, amounts: nil, tax_date: nil)
+  Spree::TaxProvider::RecordedShare.new(order: order, items: items, amounts: amounts).call
+end
+```
+
+`refund` and `commit_replacement` are optional: by default they do nothing, which suits a service that keeps no record of sales.
+
 ## Tax-exempt customers
 
 Business customers are often exempt, and the paperwork is real. Spree records a customer's or company's **tax identifier** — a VAT number, an ABN — and can validate it. Companies can also hold exemption certificates, scoped to the country or state that issued them.
@@ -214,5 +241,6 @@ Exemption is decided when tax is worked out, not stored as a flag on the custome
 
 - [Order totals](order-totals.md) — how tax rolls into what a customer pays
 - [Markets](markets.md) — where tax treatment and provider are chosen
+- [Returns, exchanges and claims](returns-exchanges-claims.md) — how tax goes back with a refund
 - [Addresses](addresses.md) — what determines the rate
 - [Companies](companies.md) — B2B tax identifiers and exemptions

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -366,7 +366,7 @@ A handler receives the workflow (so it can read `order`, `items`, `created_by`,
 ### Other behavioral changes
 
 - **`Return#refunded_total` counts store credits.** Store credit is a separate ledger and never creates a `Spree::Refund` row, so the old sum reported zero for a store-credit refund.
-- **`Order#outstanding_balance` dropped its reimbursement term** rather than replacing it — refunds already net out of `payment_total`, so that term was double-counting.
+- **`Order#outstanding_balance` replaced its reimbursement term** with refunds made for returns, claims and exchanges (`returned_items_refund_total`). Those refunds net out of `payment_total`, and adding them back is what keeps a refunded return from reading as a balance due. A refund made for nothing in return still reads as owed, as in 5.x.
 - **The reimbursement email is now `Spree::ReturnMailer#refunded_email`**, sent on `return.refunded` (in the optional `spree_emails` gem, like the other transactional mail).
 - **`Refund#originator`** points at the new records.
 - Events are `return.requested` / `.approved` / `.received` / `.refunded` / `.canceled`, and the matching `exchange.*` and `claim.*` families.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.286",
+  "version": "0.1.288",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",