@spree/docs 0.1.182 → 0.1.184

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

@@ -0,0 +1,253 @@
+---
+title: Commissions
+description: What a marketplace charges its sellers — rates and the rules that target them, how a fee is calculated, and the settlement record left behind.
+---
+
+## Overview
+
+A marketplace earns by taking a cut of what its sellers sell. Commissions are how you describe that cut and how Spree records what was actually charged.
+
+There are two halves, and — as with [promotions and discounts](promotions.md) — keeping them apart is what makes the whole thing work:
+
+| | |
+|---|---|
+| **Commission rate** | Configuration. What you charge, and when. Editable. |
+| **Commission line** | The record of one charge on one sale. Frozen. |
+
+Editing a rate changes what the *next* sale is charged and never what a past one was.
+
+```mermaid
+flowchart LR
+    Sale["A seller's item sells"] --> Resolve["Find the first<br/>matching rate"]
+    Resolve --> Calc["Calculate the fee<br/>and its tax"]
+    Calc --> Line["Commission line<br/><i>frozen</i>"]
+
+    style Line fill:#e8f5e9,stroke:#2e7d32
+```
+
+> **NOTE:** **A commission is not a [fee](fees.md).** A fee is charged to the shopper and rolls into the order total. A commission is a settlement between the marketplace and the seller — the customer never sees it, and it never touches the order total.
+
+## Rates
+
+A rate says what to charge. It's either a percentage of the sale or a flat amount.
+
+```typescript Admin SDK
+await adminClient.commissionRates.create({
+  name: 'Electronics',
+  code: 'electronics',
+  kind: 'percentage',
+  value: '12.5',
+  enabled: true,
+})
+```
+
+| Attribute | Description |
+|---|---|
+| `name` | What operators call it |
+| `code` | An optional short handle, unique per store |
+| `kind` | `percentage` or `fixed` |
+| `value` | The percentage, for a percentage rate |
+| `enabled` | Whether it's in play |
+| `position` | Where it sits in the list — see below |
+| `tax_inclusive` | Whether the fee is charged on the gross or net amount |
+| `include_shipping` | Whether delivery is commissioned too |
+| `commission_tax_rate` | An explicit tax rate for the fee, overriding the default |
+
+## The list is the precedence
+
+This is the most important thing to understand about commission rates, and it's deliberately different from how you might expect.
+
+When a sale happens, Spree walks the store's enabled rates **in list order** and takes **the first one whose rules match**. There's no scoring, and no built-in hierarchy where a product rule beats a category rule.
+
+> **INFO:** What an operator sees in the table is exactly what resolution does. A marketplace that wants a different answer drags a row up or down, rather than reasoning about which rule type counts as "more specific".
+
+Two consequences worth planning around:
+
+**A rate with no rules matches everything.** That's how you express a default — and it belongs at the **bottom** of the list, because anything below it is unreachable.
+
+**New rates are created at the top.** A rate is created to say something more specific than what's already there, and appending it below the catch-all would leave it dead on arrival.
+
+```mermaid
+flowchart TB
+    R1["1. Electronics — 12.5%<br/><i>category rule</i>"] --> R2
+    R2["2. Trusted sellers — 8%<br/><i>seller rule</i>"] --> R3
+    R3["3. Default — 15%<br/><i>no rules</i>"]
+
+    style R3 fill:#fff3e0,stroke:#e65100
+```
+
+If nothing matches, **no commission is charged**. That's a real answer, not a fallback — a marketplace with no rate covering a sale charges nothing rather than inventing a default nobody configured.
+
+## Rules
+
+Rules narrow when a rate applies. A rate can hold several, and **all of them must match** — while the IDs listed *within* one rule are alternatives.
+
+So "electronics **and** these three sellers" is two rules on one rate.
+
+```typescript Admin SDK
+// Every rule kind, with the schema describing its settings — so an editor
+// is built from what this marketplace actually has, not a hardcoded list
+const { data: types } = await adminClient.commissionRates.ruleTypes()
+
+await adminClient.commissionRates.update('crate_xxx', {
+  rules: [
+    { type: 'category_rule', preferences: { category_ids: ['ctg_xxx'] } },
+    { type: 'seller_rule', preferences: { seller_ids: ['sel_xxx', 'sel_yyy'] } },
+  ],
+})
+```
+
+Rules are replaced wholesale on update — send the full set you want.
+
+### The four rule types
+
+<details>
+<summary>Product rule — these specific products</summary>
+
+Charges the rate only for the products named.
+
+    Products are stored as real references rather than a list of IDs in a field, so a marketplace naming a thousand products stays workable.
+
+</details>
+
+  <details>
+<summary>Category rule — anything filed here</summary>
+
+Charges the rate for products in the named categories.
+
+    **A category matches its descendants too.** A rate on "Electronics" governs a camera under Electronics → Cameras, so you don't restate the rule every time someone adds a subcategory.
+
+</details>
+
+  <details>
+<summary>Seller rule — these sellers</summary>
+
+Charges the rate only when the seller is one of those named. This is how a negotiated rate for a large vendor is expressed.
+
+    A rule naming nobody narrows nothing — and rather than silently charging every seller, it's treated as not matching.
+
+</details>
+
+  <details>
+<summary>Item total rule — sales in a value band</summary>
+
+Charges the rate only on sales within a value range. "15% under 50, 10% above" is two rates, each holding one of these.
+
+    Bounds are **inclusive at the bottom and exclusive at the top**, so two bands can meet at a number without overlapping or leaving a gap.
+
+    The band is weighed against exactly the same figure the fee is charged on, so a band can never admit a sale the fee then treats as worth something different.
+
+</details>
+
+
+One rule of each type per rate. Rules can only name products and sellers belonging to the same store — pointing one at another marketplace's catalog is refused rather than quietly ignored.
+
+## What the fee is charged on
+
+Two settings on the rate decide the base, and both matter more than they first appear.
+
+### Gross or net
+
+`tax_inclusive` decides whether the fee is charged on the amount including the customer's tax, or excluding it.
+
+**The default is net**, and that default is deliberate: the customer's VAT isn't the seller's revenue, and charging commission on it would tax the same money twice under two different regimes.
+
+Discounts come off either way. Commission is charged on what the customer actually paid, so a promotion is the seller's concession.
+
+### Delivery
+
+`include_shipping` adds a commission on the delivery charge as well as the goods.
+
+> **WARNING:** A **flat** rate cannot commission delivery. A flat fee is charged per sale, so charging the same amount again on the parcel would double it. A marketplace wanting a flat charge on delivery states it as its own rate.
+
+## Amounts and currencies
+
+Money is stated per currency, never converted:
+
+```typescript Admin SDK
+// A percentage, with a floor and a cap in each currency
+await adminClient.commissionRates.create({
+  name: 'Standard',
+  kind: 'percentage',
+  value: 10,
+  bounds: {
+    USD: { min_amount: 1, max_amount: 50 },
+    EUR: { min_amount: 1, max_amount: 45 },
+  },
+})
+
+// A flat fee, stated per currency
+await adminClient.commissionRates.create({
+  name: 'Listing fee',
+  kind: 'fixed',
+  value: 0,
+  amounts: { USD: '5.00', GBP: '4.00' },
+})
+```
+
+- **`amounts`** — what a flat fee charges, per currency
+- **`bounds`** — the floor and cap a percentage charges within, per currency
+
+Both replace the whole set on write, and writing `bounds` never disturbs `amounts`.
+
+Percentages and flat fees behave differently across currencies, for a good reason:
+
+| | Behaviour in a currency with no stated amount |
+|---|---|
+| **Flat rate** | Doesn't apply — resolution falls through to the next rate. Converting one currency's figure into another would invent a fee nobody set. |
+| **Percentage** | Still applies, uncapped. A ratio travels; its floor and cap don't. A marketplace that capped its dollar fees hasn't thereby said it wants no commission on euro sales. |
+
+A flat fee is charged **per unit**, not per line. Otherwise buying three cameras together would earn a third of buying them separately — letting the shopper decide the marketplace's revenue.
+
+## Tax on commission
+
+The commission is the marketplace's own service to the seller. That's a separate taxable supply from the seller's sale to the customer, with its own place of supply — which is why the two taxes are worked out independently and never mix.
+
+The tax rate is resolved in this order:
+
+1. An explicit `commission_tax_rate` on the rate
+2. The store's tax engine, using the **seller's** address
+3. The store's default commission tax rate
+
+> **WARNING:** Commission tax follows the **seller's** jurisdiction, not the shopper's. A German marketplace charging a French seller is a cross-border B2B supply, and the shopper's location has nothing to do with it.
+
+Each line carries a `taxability_reason` — `standard_rated`, `zero_rated`, `reverse_charge` — using the same vocabulary as [tax lines](taxes.md) on goods. An invoice explaining why a marketplace fee was reverse-charged should use the same words as one explaining it for goods.
+
+## Commission lines
+
+When an order is placed, the resolved rate is applied and the result frozen as a commission line — one per item, plus one per delivery where the rate includes it.
+
+| Attribute | Description |
+|---|---|
+| `amount` | The fee |
+| `tax_amount` | Tax on the fee |
+| `total` | The two added together |
+| `rate` / `kind` | A snapshot of what was applied |
+| `tax_rate` / `taxability_reason` | How it was taxed, and why |
+| `country_code` / `state_code` | The seller's jurisdiction |
+| `currency` | The sale's currency |
+| `line_item_id` / `fulfillment_id` | What was commissioned — exactly one |
+| `commission_rate_id` | The rate, if it still exists |
+
+```typescript Admin SDK
+const { data: lines } = await adminClient.commissionLines.list({
+  filter: { seller_id_eq: 'sel_xxx' },
+})
+```
+
+**Every field is a snapshot.** Editing the rate afterwards changes nothing here, and neither does deleting it — a retired rate is soft-deleted precisely so "which rate charged this" stays answerable.
+
+There is **no write path**. Lines are read-only in the API, and correcting a charge means recording a reversal rather than editing history — the discipline any ledger needs.
+
+## What this doesn't do
+
+Commission lines say what the marketplace charged. They don't move money.
+
+> **WARNING:** Open source has **no payout ledger**. Paying sellers means connecting a provider such as Stripe Connect, or building against the commission lines and [payment splits](sellers.md#one-checkout-several-sellers). Scheduled payout runs, refund clawbacks and reconciliation are Enterprise features.
+
+## Related
+
+- [Sellers](sellers.md) — marketplaces, order splitting and payment splits
+- [Taxes](taxes.md) — the tax vocabulary commission lines share
+- [Fees](fees.md) — buyer-facing charges, which commissions are not
+- [Promotions](promotions.md) — the same rules-and-record split, on the buyer side

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

@@ -0,0 +1,240 @@
+---
+title: Companies
+description: B2B buyers as organizations — a company tree with members, shared addresses, and purchases made on the company's behalf.
+---
+
+## Overview
+
+Selling to businesses breaks an assumption most storefronts make: that a customer is a person. A business buyer is a person acting *for* an organization — one that has other buyers, several delivery sites, a VAT number, and a finance team who wants to see everything anyone ordered.
+
+A company in Spree models that. And because real organizations aren't flat, a company can be a **tree**: a parent with subsidiaries, divisions, regional units, each with its own people and addresses.
+
+```mermaid
+flowchart TB
+    Root["Acme Group<br/><i>company</i>"]
+    Root --> EU["Acme Europe<br/><i>company</i>"]
+    Root --> US["Acme US<br/><i>company</i>"]
+    EU --> Sales["Sales<br/><i>division</i>"]
+    EU --> Ops["Operations<br/><i>division</i>"]
+
+    style Root fill:#e3f2fd,stroke:#0077ff
+    style EU fill:#e3f2fd,stroke:#0077ff
+    style US fill:#e3f2fd,stroke:#0077ff
+```
+
+A node is one of two kinds, and the difference is about tax, not hierarchy:
+
+| Kind | What it is |
+|---|---|
+| `company` | A legal entity — it can hold a tax registration |
+| `division` | An organizational unit inside one — it cannot |
+
+Trees are capped at five levels, and the root must always be a `company`.
+
+```mermaid
+erDiagram
+    Company ||--o{ Company : "parent of"
+    Company ||--o{ CompanyMembership : "members"
+    Company ||--o{ Address : "address book"
+    Company ||--o{ CompanyInvitation : "pending invites"
+    Company ||--o{ TaxIdentifier : "legal entities only"
+    Company ||--o{ Order : "purchases"
+
+    Company {
+        string name
+        string kind
+        string parent_id
+    }
+    CompanyMembership {
+        string customer_id
+        string email
+    }
+```
+
+## Membership covers a subtree
+
+Someone belongs to a company through a membership, and **that standing reaches everything below the node** — not just the node itself.
+
+So a buyer attached to "Acme Europe" can act for Sales and Operations beneath it, without anyone creating three memberships. Give someone standing at the root and they cover the whole group.
+
+This is why authorization always asks "does this person have standing on this node *or any of its ancestors*", never "is this person a member of exactly this node".
+
+```typescript Store SDK
+// Which companies can this customer act for?
+const { data: memberships } = await client.account.companies()
+
+memberships.forEach((m) => {
+  m.company.name      // "Acme Europe"
+  m.company.ancestors // [{ name: "Acme Group", … }] — the path above it
+})
+```
+
+> **NOTE:** **In open source, every member can do everything within their standing** — buy, see the subtree's orders, and manage addresses and members. There are no company roles; the `role` label on a membership is cosmetic.
+> 
+> To restrict what individual people may do, see [company governance](#company-governance) below.
+
+## Adding people
+
+Both the dashboard and the storefront add members the same way — by email:
+
+```typescript Store SDK
+const result = await client.companies.members.create('comp_xxx', {
+  customer_email: 'buyer@acme.com',
+})
+```
+
+What comes back depends on whether that email is already a customer:
+
+- **An existing customer** becomes a member straight away.
+- **An unknown email** produces an invitation, valid for 30 days, and an email with a link.
+
+You can tell which by the ID prefix — `cmem_` for a membership, `cinv_` for an invitation.
+
+Accepting an invitation either signs an existing customer in, or registers a new account with the invited email. Either way it ends as a membership:
+
+```typescript Store SDK
+// The token comes from the invitation email — no sign-in needed to read it
+const invitation = await client.companyInvitations.lookup(token)
+invitation.company_name
+
+await client.companyInvitations.accept(token, {
+  first_name: 'Dana',
+  last_name: 'Reid',
+  password: 'a-strong-password',
+})
+```
+
+Memberships are always active and always backed by a real customer. Anything still waiting lives on the invitation, so there's no such thing as a half-active member.
+
+## Buying for a company
+
+A cart and an order can name a company. That's what turns a personal purchase into a company one — it decides which addresses are on offer, whose tax registration applies, and who else will see the order.
+
+```typescript Store SDK
+await client.carts.update(cartId, { company_id: 'comp_xxx' })
+```
+
+A buyer with exactly one membership doesn't need to choose; it resolves on its own. A buyer who belongs to several names the node — and it must be one they have standing on.
+
+The company is **frozen onto the order** at completion, like the addresses and prices. Reorganize the tree next year and last year's order still explains itself.
+
+```typescript Store SDK
+// Everything anyone in the subtree has bought
+const { data: orders } = await client.companies.orders.list('comp_xxx')
+```
+
+That subtree rollup is the feature a finance team actually asks for: one place showing what the whole organization spent, without chasing individual accounts.
+
+## The shared address book
+
+A company keeps its own addresses — ship-to sites, a billing address — separate from any individual's. They're labelled, and one of each kind can be the default.
+
+```typescript Store SDK
+await client.companies.addresses.create('comp_xxx', {
+  label: 'Northern Warehouse',
+  first_name: 'Goods',
+  last_name: 'Inwards',
+  address1: '14 Dock Road',
+  city: 'Rotterdam',
+  country_code: 'NL',
+  postal_code: '3011',
+  default_shipping: true,
+})
+```
+
+Note that a delivery site is just an address. Ten warehouses do not mean ten company nodes — nodes exist for organizational and legal structure, addresses for where things go.
+
+## Tax
+
+Tax registrations and exemption certificates live **only on legal entities**, and a purchase resolves tax through the node's nearest `company` ancestor.
+
+```typescript Admin SDK
+await adminClient.companies.taxIdentifiers.create('comp_xxx', {
+  kind: 'eu_vat',
+  value: 'NL123456789B01',
+})
+
+// Validation runs against the official registry, in the background
+await adminClient.companies.taxIdentifiers.validate('comp_xxx', 'txid_xxx')
+```
+
+> **WARNING:** The walk stops at the first `company` node, **whether or not it holds a registration**. A subsidiary with no VAT number of its own therefore has none — it never quietly borrows its parent's, because in most jurisdictions that would be a false declaration.
+
+Exemption certificates hang off a legal entity and are scoped to the country or state that issued them. Check whether a certificate is `active` rather than reading its status — a verified certificate stops exempting once it expires, and `active` accounts for that.
+
+See [Taxes](taxes.md) for how these reach the tax calculation.
+
+## Company governance
+
+Open source deliberately trusts every member equally. That's the right default for a company of five people, and the wrong one for a company of five hundred — where a junior buyer should not be able to place a £40,000 order, remove their manager, or see what another division spent.
+
+Company governance adds that control. It works through the same endpoints and the same data, so nothing about your storefront integration changes when it's switched on — the calls you already make simply start enforcing.
+
+- [Requires a Spree Enterprise licence](https://spreecommerce.org/enterprise/) — Company roles, order approvals, spending limits and governance audit history are part of Spree Enterprise. See what's included, or talk to the team about your use case.
+
+### Company roles
+
+Where open source has a cosmetic label, Enterprise has real roles built from a fixed set of capabilities:
+
+| Capability | Allows |
+|---|---|
+| `place_orders` | Completing a purchase |
+| `approve_orders` | Approving what others submit |
+| `view_node_purchases` | Seeing this node's orders |
+| `view_company_purchases` | Seeing the whole subtree's orders |
+| `manage_company_members` | Adding and removing people |
+| `manage_company_addresses` | Editing the address book |
+
+Roles are **data, edited by the company's own administrator** rather than by your staff — the buying organization manages its own structure, which is the point of self-service. Guards prevent someone granting themselves more than they hold.
+
+These are entirely separate from [staff roles](staff-roles.md). A company role never reaches anything belonging to the store.
+
+### Order approvals
+
+A member without `place_orders` submits their basket instead of completing it. Someone with `approve_orders` reviews and releases it.
+
+```mermaid
+flowchart LR
+    Buyer["Buyer submits"] --> Pending["Awaiting approval"]
+    Pending --> Approved["Approved → order placed"]
+    Pending --> Rejected["Rejected, with a reason"]
+```
+
+Checkout returns a well-known `approval_required` response rather than a generic failure, so a storefront can show the right message and the right next step. The approval history is append-only — who asked, who decided, when.
+
+### Spending limits
+
+Limits are set per member or per node, with a reset period — £5,000 a month for a buyer, £50,000 for a division. They're enforced at completion, alongside approvals, so an over-limit basket is caught before payment rather than after.
+
+### Restricted self-service
+
+The same storefront endpoints — the company directory, address book, member management, order history — become capability-gated. A member without `view_company_purchases` sees their own node's orders and not the group's; a member without `manage_company_members` can read the team but not change it.
+
+> **INFO:** **Nothing about the data model changes.** Governance enforces through a policy layer and the checkout validation hooks, over the same companies, memberships and endpoints described on this page. You can build a B2B storefront against open source today and have it work unchanged when governance is enabled.
+
+Payment terms and net invoicing, quotes, and a packaged buyer portal are on the Enterprise roadmap — [talk to the team](https://spreecommerce.org/enterprise/) if those matter to your timeline.
+
+## Managing companies as staff
+
+```typescript Admin SDK
+// Roots only
+const { data: roots } = await adminClient.companies.list({ parent_id_null: 1 })
+
+// Children of one node
+const { data: children } = await adminClient.companies.list({ parent_id_eq: 'comp_xxx' })
+
+const division = await adminClient.companies.create({
+  name: 'Sales',
+  kind: 'division',
+  parent_id: 'comp_xxx',
+})
+```
+
+Moving a branch is an update with a new `parent_id`. Deleting a node removes its whole subtree, and is refused outright once any order exists beneath it — history doesn't get deleted to tidy up an org chart.
+
+## Related
+
+- [Catalogs](catalogs.md) — giving a company its own range and prices
+- [Customers](customers.md) — the accounts memberships are built on
+- [Taxes](taxes.md) — registrations and exemptions
+- [Orders](orders.md) — company purchases

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

@@ -3,8 +3,6 @@ title: Customers
 description: How Spree models customer accounts — registration, authentication, addresses, order history, store credits, and guest checkout behavior.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
@@ -193,7 +191,6 @@ On success, the user is automatically logged in and a JWT token is returned. The
 
 ## Newsletter Subscriptions
 
-
 Headless storefronts often need to collect newsletter signups before account creation (footer forms, popup overlays). The Store API exposes a double opt-in subscription flow that mirrors the password reset webhook pattern.
 
 ### Step 1: Subscribe

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

@@ -0,0 +1,133 @@
+---
+title: Discounts
+description: The record of money taken off one order — where a discount comes from, and why it is spread across the items it applied to.
+---
+
+## Overview
+
+A discount is one line on one order saying money came off, and why.
+
+> **NOTE:** **A discount is not a promotion.** A [promotion](promotions.md) is a *rule* — "20% off shoes in July" — that exists on its own, before anybody buys anything. A discount is the *result* on a particular order.
+> 
+> Think of the promotion as the sign in the shop window and the discount as the line on the receipt. One promotion produces thousands of discounts over its life.
+
+That separation is what lets an order stay truthful. The promotion can be edited, paused or deleted next month; the discount row on last month's order still says exactly what that customer was given.
+
+It also means **not every discount has a promotion behind it.** When a support agent takes $10 off as a goodwill gesture, that's a discount with no campaign attached — which is what the `kind` field distinguishes.
+
+```mermaid
+erDiagram
+    Promotion ||--o{ Discount : "produces many, over time"
+    Order ||--o{ Discount : "has many"
+    LineItem ||--o{ Discount : "reduced by"
+    Fulfillment ||--o{ Discount : "reduced by"
+
+    Promotion {
+        string name
+        string code
+        datetime expires_at
+    }
+    Discount {
+        string label
+        string kind
+        string code
+        string value
+        string amount
+    }
+```
+
+| | [Promotion](promotions.md) | Discount |
+|---|---|---|
+| What it is | A campaign rule | A row on one order |
+| Exists | Before any order | Only once money comes off |
+| How many | One | One per order it applies to |
+| Can change later | Yes — edit or end it | No — it's a financial record |
+| Set up by | A merchant, in advance | Created automatically, or by staff |
+
+## Discount attributes
+
+| Attribute | Description |
+|---|---|
+| `label` | What the customer sees — `Summer Sale` |
+| `kind` | `promotion` or `manual` |
+| `code` | The coupon code used, if there was one |
+| `value` / `value_type` | The rule behind it — `"10"` and `percent` |
+| `amount` / `display_amount` | What actually came off, as a negative amount |
+| `promotion_id` | The promotion responsible, for promotion discounts |
+| `line_item_id` / `fulfillment_id` | What it reduced |
+
+Note the difference between `value` and `amount`. `value` is the rule — "10 percent". `amount` is the money — "-$12.00". You need the rule to explain the discount and the amount to add up the order.
+
+## Reading discounts on an order
+
+Whatever produced them, the rows read the same way:
+
+```typescript Store SDK
+const cart = await client.carts.get(cartId)
+
+cart.display_discount_total // "-$12.00"
+
+cart.discounts.forEach((discount) => {
+  discount.label          // "Summer Sale"
+  discount.kind           // "promotion" or "manual"
+  discount.code           // "SUMMER20", when a code was used
+  discount.display_amount // "-$12.00"
+})
+```
+
+Applying a coupon code, and what decides whether it's accepted, belongs to [Promotions](promotions.md).
+
+## Manual discounts
+
+Sometimes there's no promotion — a price match, an apology for a late delivery. Staff can add a discount directly:
+
+
+```typescript Admin SDK
+// 10% off one line item
+await adminClient.orders.discounts.create('or_xxx', {
+  label: 'Goodwill discount',
+  value: '10',
+  value_type: 'percent',
+  line_item_id: 'li_xxx',
+})
+
+// A flat amount across the order
+await adminClient.orders.discounts.create('or_xxx', {
+  label: 'Price match',
+  value: '15.00',
+  value_type: 'flat',
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/discounts' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "label": "Goodwill discount", "value": "10", "value_type": "percent" }'
+```
+
+
+> **WARNING:** Only **manual** discounts can be edited or deleted. Changing one that came from a promotion returns a `422`.
+> 
+> That row belongs to the promotion that created it. If staff could edit it, an order would start disagreeing with the promotion it claims to have used — and the reporting behind "how did the summer sale do" stops adding up.
+
+## How a discount is spread
+
+An order-level discount isn't kept as one lump sum. It's divided across the items it applied to, in proportion to what they cost.
+
+This looks like an implementation detail until someone returns one item out of three. Then the question is: how much of that $30 discount belonged to the returned shirt? If the discount were one lump, you'd have to guess. Because it was spread at the time, the answer is already recorded, and the refund is right without anyone doing arithmetic on the phone.
+
+The same reasoning applies to tax — the tax on a partially returned order follows the same split.
+
+## Discounts on placed orders
+
+Once an order exists, its discounts stop being regenerated. Editing a placed order re-applies the rows it already has rather than re-running today's promotions.
+
+The alternative would mean an order quietly changing because a sale ended overnight — which is indefensible to a customer holding a confirmation email.
+
+## Related
+
+- [Promotions](promotions.md) — the rules that create most discounts
+- [Order totals](order-totals.md) — how discounts roll into the total
+- [Gift cards & store credit](store-credits-gift-cards.md) — payment, not discount
+- [Returns](returns-exchanges-claims.md) — how a discount is unwound on a return