@spree/docs 0.1.177 → 0.1.178

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

@@ -5,23 +5,18 @@ description: Build percentage and fixed-amount discounts, free shipping, BOGO of
 
 ## Overview
 
-Promotions within Spree are used to provide discounts to orders, offer free shipping, or add items at no extra cost (e.g., free gifts). The promotion system is highly flexible, allowing you to create complex promotional campaigns based on various conditions.
-
-### Promotion Model Diagram
+Promotions give money off an order — a percentage off, free shipping, or free items added to the cart. A promotion is a campaign definition: **rules** decide when it applies, **actions** decide what it does. When a promotion applies, its actions write [Discount](taxes-discounts-fees.md#discounts) rows on the order.
 
 ```mermaid
 erDiagram
     Promotion {
         string name
-        string description
         string kind
         string code
-        string path
         datetime starts_at
         datetime expires_at
         integer usage_limit
         string match_policy
-        boolean advertise
     }
 
     PromotionRule {
@@ -31,7 +26,6 @@ erDiagram
 
     PromotionAction {
         string type
-        integer position
     }
 
     CouponCode {
@@ -39,48 +33,33 @@ erDiagram
         string state
     }
 
-    OrderPromotion {
-        integer order_id
-        integer promotion_id
-    }
-
-    Adjustment {
-        decimal amount
+    Discount {
         string label
-        boolean eligible
-        string state
+        string kind
+        string code
+        string amount
     }
 
     Promotion ||--o{ PromotionRule : "has many"
     Promotion ||--o{ PromotionAction : "has many"
     Promotion ||--o{ CouponCode : "has many"
-    Promotion ||--o{ OrderPromotion : "has many"
-    Promotion }o--o{ Store : "available in"
-    PromotionRule }o--o{ Product : "applies to"
-    PromotionRule }o--o{ Taxon : "applies to"
-    PromotionRule }o--o{ User : "applies to"
-    PromotionAction ||--o{ Adjustment : "creates"
-    PromotionAction ||--|| Calculator : "has one"
-    Order ||--o{ OrderPromotion : "has many"
-    CouponCode }o--o| Order : "used by"
+    PromotionAction ||--o{ Discount : "writes"
+    Order ||--o{ Discount : "has many"
 ```
 
-**Key relationships:**
-- **Promotion** defines the campaign with rules and actions
-- **Promotion Rules** determine eligibility conditions (FirstOrder, ItemTotal, Taxon, etc.)
-- **Promotion Actions** define what happens when applied (discount, free shipping, free items)
-- **Coupon Codes** track usage for code-based promotions
-- **[Adjustments](adjustments.md)** are created on orders/line items to apply discounts
-
 Promotions can be activated in two ways:
 
-- **Automatic promotions** - Applied automatically when eligibility rules are met (e.g., free shipping on orders over $50)
-- **Coupon code promotions** - Applied when a customer enters a valid code during checkout
+- **Automatic promotions** — applied on their own when the rules are met (e.g. free shipping on orders over $50)
+- **Coupon code promotions** — applied when a customer enters a valid code during checkout
+
+### How discounts are recorded
+
+Each applied promotion becomes one or more Discount rows on the order — on a specific line item or on a fulfillment, never a loose adjustment. Each row keeps a copy of the coupon code and the configured value ("10% off"), so the order still tells the whole story even if the promotion is deleted later.
 
-Promotions consist of two main components:
+Two things follow from this design:
 
-- **Rules** - Conditions that must be met for the promotion to apply
-- **Actions** - What happens when the promotion is applied (discount, free shipping, etc.)
+- **Only winners are stored.** When several promotions compete for the same item, Spree picks the one that saves the customer the most and writes only that one. Losing candidates are recomputed on every cart change, so a promotion that loses today can win tomorrow without any bookkeeping.
+- **A discount on the whole order is shared out across the items.** If a customer later returns one item, Spree knows exactly how much of the discount belonged to it.
 
 ## Promotion Attributes
 
@@ -89,16 +68,15 @@ Promotions consist of two main components:
 | `name` | The name of the promotion | Summer Sale |
 | `description` | Brief description (max 255 chars) | 20% off all summer items |
 | `kind` | Type: `coupon_code` or `automatic` | `automatic` |
-| `starts_at` | When the promotion becomes active | 2025-06-01 00:00:00 |
-| `expires_at` | When the promotion expires | 2025-09-01 23:59:59 |
+| `starts_at` | When the promotion becomes active | 2026-06-01 00:00:00 |
+| `expires_at` | When the promotion expires | 2026-09-01 23:59:59 |
 | `usage_limit` | Max times the promotion can be used | 500 |
 | `match_policy` | How rules are evaluated: `all` or `any` | `all` |
 | `advertise` | Whether to display on storefront | `true` |
-| `path` | SEO-friendly URL path | `summer-sale` |
 
 ### Multi-Code Promotions
 
-For promotions that need unique codes per customer (e.g., influencer campaigns), Spree supports bulk code generation:
+For promotions that need unique codes per customer (e.g. influencer campaigns), Spree supports bulk code generation:
 
 | Attribute | Description | Example |
 |-----------|-------------|---------|
@@ -106,158 +84,65 @@ For promotions that need unique codes per customer (e.g., influencer campaigns),
 | `number_of_codes` | How many codes to generate | 1000 |
 | `code_prefix` | Prefix for generated codes | `SUMMER` |
 
-Generated codes follow the pattern `{prefix}{random}`, e.g., `SUMMER22A0F62A230BD919`.
+Generated codes follow the pattern `{prefix}{random}`, e.g. `SUMMER22A0F62A230BD919`.
 
 ## Rules
 
-Rules determine when a promotion is eligible. You can combine multiple rules and configure whether **all** rules must match or **any** rule is sufficient (via `match_policy`).
-
-### FirstOrder
-
-Applies only to a customer's first order. Checks both user account and email address to prevent abuse.
-
-**Use case:** Welcome discount for new customers.
-
-### ItemTotal
-
-Requires the order subtotal to meet minimum and/or maximum thresholds.
-
-**Configuration:**
-- `preferred_amount_min` - Minimum order amount (default: 100.00)
-- `preferred_operator_min` - Comparison operator: `gt` (greater than) or `gte` (greater than or equal)
-- `preferred_amount_max` - Maximum order amount (optional)
-- `preferred_operator_max` - Comparison operator: `lt` (less than) or `lte` (less than or equal)
-
-**Use case:** "Free shipping on orders over $50", "10% off orders between $100-$500".
-
-### Product
-
-Requires specific products to be in the order.
-
-**Configuration:**
-- `preferred_match_policy`:
-  - `any` - At least one of the specified products
-  - `all` - All specified products must be present
-  - `none` - None of the specified products (exclusion)
-
-**Use case:** "Buy Product A and get 20% off", "Discount excludes sale items".
-
-### Taxon
-
-Requires products from specific categories (taxons) to be in the order.
-
-**Configuration:**
-- `preferred_match_policy`: `any` or `all`
-
-The rule automatically includes products in child taxons when a parent taxon is selected.
-
-**Use case:** "20% off Electronics", "Buy from Shoes category get 10% off".
-
-### User
-
-Limits the promotion to specific customer accounts.
-
-**Use case:** Employee discounts, VIP customer promotions.
-
-### UserLoggedIn
-
-Requires the customer to be logged in with an account.
-
-**Use case:** Member-only discounts.
-
-### OneUsePerUser
-
-Ensures each customer can only use the promotion once.
-
-**Use case:** One-time welcome offers, limited redemption campaigns.
-
-### Country
-
-Limits the promotion to orders shipping to a specific country.
-
-**Configuration:**
-- `preferred_country_id` or `preferred_country_iso` (ISO 2-letter code)
-
-**Use case:** Regional promotions, country-specific campaigns.
-
-### Currency
-
-Limits the promotion to orders in a specific currency.
-
-**Configuration:**
-- `preferred_currency` - Currency code (e.g., "USD", "EUR")
-
-**Use case:** Currency-specific pricing strategies.
-
-### OptionValue
-
-Requires products with specific option values (e.g., size, color) to be in the order.
-
-**Configuration:**
-- `preferred_eligible_values` - Array of `Spree::OptionValueVariant` IDs (the option-value↔variant join records the rule matches against the order's variants), not variant IDs
-
-**Use case:** "10% off all red items", "Discount on size XL".
-
-### CustomerGroup
-
-Limits the promotion to customers belonging to specific customer groups.
-
-**Configuration:**
-- `preferred_customer_group_ids` - Array of customer group IDs
-
-Customer groups are managed in Admin > Customers > Customer Groups and allow you to segment customers for targeted promotions.
-
-**Use case:** VIP programs, loyalty tiers, wholesale pricing, B2B customer segments.
+Rules decide when a promotion is eligible. You can combine multiple rules and configure whether **all** must match or **any** is enough (via `match_policy`).
+
+| Rule | Applies when |
+|---|---|
+| **FirstOrder** | It's the customer's first order (checked by account and email) |
+| **ItemTotal** | The order subtotal is within configured minimum/maximum thresholds |
+| **Product** | Specific products are in the order (`any` / `all` / `none` match policy) |
+| **Category** | Products from specific categories are in the order — child categories count |
+| **OptionValue** | Products with specific option values (size, color) are in the order |
+| **User** | The customer is one of the listed accounts |
+| **UserLoggedIn** | The customer is logged in |
+| **OneUsePerUser** | The customer hasn't used this promotion before |
+| **CustomerGroup** | The customer belongs to one of the configured customer groups |
+| **Country** | The order ships to a specific country |
+| **Currency** | The order is in a specific currency |
+| **Channel** | The order was placed through one of the configured [channels](channels.md) |
+| **Market** | The order belongs to one of the configured [markets](markets.md) |
+
+You can also [build your own rules](../how-to/custom-promotion.md) for business-specific conditions.
 
 ## Actions
 
-Actions define what happens when a promotion is applied.
+Actions define what happens when a promotion applies.
 
 ### CreateAdjustment
 
-Creates a discount on the entire order total.
+A discount on the whole order. The amount is distributed proportionally across the line items — there is no single order-level row, so per-item reporting and partial returns always know their share.
 
-**Default calculator:** `FlatPercentItemTotal` (percentage off order)
-
-**Available calculators:**
-- `FlatPercentItemTotal` - Percentage off the order total
-- `FlatRate` - Fixed amount off
-- `FlexiRate` - First item at one rate, additional items at another
-- `TieredFlatRate` - Different rates based on order total tiers
-- `TieredPercent` - Different percentages based on order total tiers
+**Default calculator:** `FlatPercentItemTotal` (percentage off the order). Also available: `FlatRate`, `FlexiRate`, `TieredFlatRate`, `TieredPercent`.
 
 **Use case:** "10% off your order", "$20 off orders over $100".
 
 ### CreateItemAdjustments
 
-Creates discounts on individual line items. Only applies to items that match the promotion rules (e.g., items in a specific category).
-
-**Default calculator:** `PercentOnLineItem` (percentage off each item)
+A discount on individual line items. Only items that match the promotion's rules receive it — if a Category rule says "Electronics", only electronics are discounted.
 
-The action respects rule actionability - if a Taxon rule specifies "Electronics", only electronics items receive the discount.
+**Default calculator:** `PercentOnLineItem` (percentage off each item).
 
 **Use case:** "15% off shoes", "Buy 2+ shirts get 10% off each".
 
 ### FreeShipping
 
-Makes all shipments free by creating negative adjustments equal to shipping costs.
+Writes a discount on each fulfillment covering its delivery cost. The row is kept even when the cost is zero — its presence is what marks the order as having free shipping.
 
 **Use case:** "Free shipping on orders over $75", "Free shipping with code FREESHIP".
 
 ### CreateLineItems
 
-Automatically adds specified products to the cart when the promotion is eligible.
-
-**Configuration:**
-- Map of variant IDs to quantities to add
-
-The action checks stock availability before adding items. Items are not automatically removed if eligibility is lost - customers must remove them manually.
+Adds specified products to the cart when the promotion is eligible, checking stock first. Items are not removed automatically if eligibility is lost — customers remove them manually.
 
-**Use case:** "Free gift with purchase", "Buy 2 get 1 free", "Spend $100 get free sample".
+**Use case:** "Free gift with purchase", "Spend $100 get a free sample".
 
 ## Managing Promotions
 
-Create and manage promotions via the [Admin API](../../api-reference/admin-api/introduction.md). Rules and actions can be supplied inline on create — each is a `{ type, preferences }` draft using the rule/action types described above:
+Create and manage promotions via the [Admin API](../../api-reference/admin-api/introduction.md). Rules and actions can be supplied inline on create — each is a `{ type, preferences }` draft using the rule and action types described above:
 
 
 ```typescript Admin SDK
@@ -310,26 +195,18 @@ spree api patch /promotions/promo_xxx -d '{"expires_at": "2026-09-01T00:00:00Z"}
 ```
 
 
-## Coupon Codes
-
-Coupon codes track promotion usage and can be single-use or multi-use.
-
-### Single Code Promotions
-
-Set the `code` attribute directly on the promotion. The `usage_limit` controls how many times it can be redeemed.
+The available rule and action types — including any custom ones you register — are discoverable at `/api/v3/admin/promotion_rules/types` and `/api/v3/admin/promotion_actions/types`, together with their preference schemas. The dashboard's promotion editor is built on these endpoints, so custom types show up there without any UI work.
 
-### Multi-Code Promotions
+> **NOTE:** Deleting a promotion doesn't disturb the orders that used it. Their discount rows stay, keeping the code and value they were created with — only the link back to the promotion is cleared.
 
-For bulk-generated codes, each code tracks its usage state:
+## Coupon Codes
 
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `code` | The unique code | `SUMMER22A0F62A230BD919` |
-| `state` | Usage state | `unused`, `used` |
+Coupon codes track promotion usage and can be single-use or multi-use.
 
-## Applying Coupon Codes via Store API
+- **Single code** — set the `code` attribute on the promotion; `usage_limit` controls how many times it can be redeemed.
+- **Multi-code** — bulk-generated codes each track their own state (`unused` / `used`).
 
-Customers [apply coupon codes during checkout](../sdk/store/cart-checkout.md) via the Store API:
+Customers apply codes on the cart via the Store API:
 
 
 ```typescript Store SDK
@@ -354,26 +231,22 @@ curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/discount_co
 ```
 
 
-Automatic promotions are applied without any customer action — they are evaluated on every order update.
+The returned cart already carries the updated discounts and totals. If the cart doesn't qualify yet — say the code needs a $100 minimum and the cart holds $80 — the code stays on the cart and the discount activates on its own the moment the cart qualifies.
 
-## Promotion Flow
+Automatic promotions need no customer action at all — they are evaluated on every cart change.
 
-How promotions are evaluated and applied:
+## Promotion Flow
 
-1. **Order Update** — When an order is updated, the system checks all eligible promotions
-2. **Eligibility Check** — For each promotion:
-   - Check if within `starts_at` and `expires_at` range
-   - Check if under `usage_limit`
-   - Evaluate all rules based on `match_policy` (all or any)
-3. **Action Execution** — If eligible, each action is applied
-4. **Tracking** — Applied promotions are recorded on the order
-5. **Re-evaluation** — Eligibility is re-checked on every order update; adjustments from ineligible promotions are removed
+1. **Cart change** — every change to a cart (item added, address entered, code applied) triggers a recalculation
+2. **Eligibility** — each connected promotion is checked: active dates, usage limits, then rules per `match_policy`
+3. **Competition** — candidate discounts are computed for every eligible promotion; per item, per fulfillment, and order-wide, the largest saving wins
+4. **Persistence** — winning discounts are written as rows; anything stale from the previous pass is removed; tax is then estimated on the discounted amounts
+5. **Placement** — once the order is placed, its discount rows are frozen; usage counts are recorded against the promotion
 
 ## Related Documentation
 
-- [Build Custom Promotion Rules & Actions](../how-to/custom-promotion.md) - Step-by-step guide to creating custom rules and actions
-- [Calculators](calculators.md) - Learn about promotion calculators
-- [Orders](orders.md) - Understanding order processing
-- [Customization Quickstart](../customization/quickstart.md) - Overview of customization options
-- [Admin SDK Resources](../sdk/admin/resources.md) - The `client.promotions.*` resource-client pattern used in the examples above
-- [Spree CLI Admin API](../cli/admin-api.md) - The `spree api` command reference for the CLI examples above
+- [Taxes, Discounts & Fees](taxes-discounts-fees.md) — the Discount rows promotions write, and manual discounts
+- [Build Custom Promotion Rules & Actions](../how-to/custom-promotion.md) — step-by-step guide to custom rules, actions and adjusters
+- [Calculators](calculators.md) — promotion calculators
+- [Carts](carts.md) — the cart lifecycle promotions act on
+- [Admin SDK Resources](../sdk/admin/resources.md) — the `client.promotions.*` resource-client pattern used above

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

@@ -0,0 +1,173 @@
+---
+title: Returns, Exchanges & Claims
+description: How Spree models what happens after a customer receives an order — three separate records for money back, different items, and something gone wrong.
+---
+
+## Overview
+
+Three things can happen after a customer receives an order, and Spree models each on its own:
+
+| Record | What happened | Outcome |
+|---|---|---|
+| **Return** | Customer sends items back | Money back |
+| **Exchange** | Customer sends items back | Different items |
+| **Claim** | Item arrived damaged, wrong, or never arrived | Refund, replacement, or both — usually without asking for the goods back |
+
+Keeping them separate matters most for claims. Without a record for "it arrived smashed", merchants end up either creating a manual order or opening a return they immediately mark received — which records the wrong thing and makes damage reporting impossible.
+
+```mermaid
+erDiagram
+    Order ||--o{ Return : "has many"
+    Order ||--o{ Exchange : "has many"
+    Order ||--o{ Claim : "has many"
+    Return ||--o{ ReturnLineItem : "has many"
+    Return }o--|| StockLocation : "received at"
+
+    Return {
+        string number
+        string status
+        datetime received_at
+    }
+    Claim {
+        string number
+        string status
+        string resolution
+    }
+```
+
+## Statuses
+
+| Record | Statuses |
+|---|---|
+| **Return** | `requested` → `approved` → `received` → `refunded`, or `canceled` |
+| **Exchange** | `requested` → `approved` → `received` → `fulfilled`, or `canceled` |
+| **Claim** | `open` → `approved` → `resolved`, or `denied` / `canceled` |
+
+Each step is its own API call, because each one needs information the last one didn't have — what actually turned up, how much to refund, what to send instead.
+
+## Customer self-service
+
+Customers can open a return or a claim on their own order and follow its progress. Approving, receiving and refunding stay with the merchant.
+
+
+```typescript Store SDK
+// Request a return — items refer to units that shipped, not cart line items
+const returnRequest = await client.orders.returns.create('or_xxx', {
+  items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],
+  reason_id: 'rsn_xxx',
+  memo: 'Too small',
+})
+
+// Report a problem
+const claim = await client.orders.claims.create('or_xxx', {
+  items: [{ line_item_id: 'li_xxx', quantity: 1, description: 'Arrived cracked' }],
+  reason_id: 'clr_xxx',
+})
+
+// Follow progress
+const returns = await client.orders.returns.list('or_xxx')
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_xxx/returns' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: order_token_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "items": [{ "fulfillment_item_id": "fi_xxx", "quantity": 1 }],
+        "memo": "Too small" }'
+```
+
+
+Claim types are `damaged`, `missing`, `wrong_item` and `other` out of the box, and a store can add its own.
+
+## Processing a return
+
+
+```typescript Admin SDK
+// Approve
+await adminClient.orders.returns.approve('or_xxx', 'ret_xxx')
+
+// Record what actually arrived
+await adminClient.orders.returns.receive('or_xxx', 'ret_xxx', {
+  items: [
+    { return_line_item_id: 'rli_1', quantity: 2, resellable: true },
+    { return_line_item_id: 'rli_2', quantity: 1, resellable: false },
+  ],
+})
+
+// Refund
+await adminClient.orders.returns.refund('or_xxx', 'ret_xxx', {
+  amount: '24.99',
+  refund_method: 'original_payment',
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/returns/ret_xxx/receive' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "items": [{ "return_line_item_id": "rli_1", "quantity": 2, "resellable": true }] }'
+```
+
+
+Receiving takes the quantities the warehouse actually counted, because partial and damaged returns are normal rather than exceptional. A customer says three items are coming; two arrive; one of those can't be sold again. Only resellable goods go back into stock.
+
+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.
+
+## Resolving a claim
+
+What to do about a claim is decided when you resolve it, not when the customer opens it — merchants usually decide once they've seen the photos.
+
+```typescript Admin SDK
+await adminClient.orders.claims.approve('or_xxx', 'clm_xxx')
+
+await adminClient.orders.claims.resolve('or_xxx', 'clm_xxx', {
+  resolution: 'refund_and_replacement',   // or 'refund', 'replacement'
+  refund_method: 'store_credit',
+  replacement_line_item_ids: ['li_xxx'],
+})
+```
+
+A replacement creates a new [fulfillment](fulfillments.md) on the original order, so the customer doesn't have to place a second one.
+
+## Exchanges
+
+An exchange works like a return, but ends by sending different items instead of refunding:
+
+```typescript Admin SDK
+await adminClient.orders.exchanges.approve('or_xxx', 'exch_xxx')
+await adminClient.orders.exchanges.receive('or_xxx', 'exch_xxx')
+await adminClient.orders.exchanges.fulfill('or_xxx', 'exch_xxx')
+```
+
+## Reporting
+
+Because each one is its own record, you can query them directly:
+
+```typescript Admin SDK
+// Everything awaiting action
+const pending = await adminClient.returns.list({ filter: { status_eq: 'approved' } })
+
+// Claims opened this month
+const claims = await adminClient.claims.list({
+  filter: { created_at_gt: '2026-08-01' },
+})
+```
+
+## Return policy
+
+Spree ships no built-in return window. Whether a customer may open a return is store policy, and it's checked when the return is created — so you can hold customers to a 30-day window while letting staff make an exception for a good customer, and vary the rule by market where local law requires it.
+
+Set the return window per market, or express a more specific rule in your own application. See [Configuration](../customization/configuration.md) and [Services & Workflows](../customization/workflows.md).
+
+## Events
+
+Each step publishes an [event](events.md) — `return.received`, `return.refunded`, `exchange.fulfilled`, `claim.resolved` — which also reach [webhooks](webhooks.md).
+
+Returns and claims also update the order's [payment status](orders.md#statuses), so a refunded order reflects it without any manual bookkeeping.
+
+## Related
+
+- [Orders](orders.md) — payment status after refunds
+- [Fulfillments](fulfillments.md) — replacement deliveries
+- [Inventory](inventory.md) — putting returned goods back in stock

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -174,7 +174,7 @@ erDiagram
 
     GiftCard {
         string code
-        string state
+        string status
         decimal amount
         decimal amount_used
         decimal amount_authorized
@@ -199,28 +199,26 @@ erDiagram
 | `code` | Unique redemption code | `abc1234def` |
 | `amount` | Total gift card value | `50.00` |
 | `amount_used` | Amount already redeemed | `0.00` |
-| `state` | Current state | `active` |
+| `status` | Current status | `active` |
 | `currency` | Currency code | `USD` |
 | `expires_at` | Optional expiration date | `2025-12-31` |
 
-### Gift Card States
+### Gift Card Statuses
 
-```mermaid
-stateDiagram-v2
-    [*] --> active: Created
-    active --> partially_redeemed: Partial redemption
-    active --> redeemed: Full redemption
-    active --> canceled: Admin cancels
-    partially_redeemed --> redeemed: Remaining redeemed
-    partially_redeemed --> partially_redeemed: Another partial redemption
-```
+| Status | Description | How it gets there |
+|-------|-------------|-------------------|
+| `active` | Available for redemption | The status a card is created with |
+| `partially_redeemed` | Some value has been redeemed | `Spree::GiftCards::Redeem`, when a balance remains |
+| `redeemed` | Fully redeemed | `Spree::GiftCards::Redeem`, when nothing is left |
+| `canceled` | Voided, and no longer spendable | `Spree::GiftCards::Cancel` |
 
-| State | Description |
-|-------|-------------|
-| `active` | Available for redemption |
-| `partially_redeemed` | Some value has been redeemed |
-| `redeemed` | Fully redeemed |
-| `canceled` | Canceled by admin |
+Redemption does not need the caller to choose: `Spree::GiftCards::Redeem`
+looks at what is left on the card and marks it partially or fully redeemed
+accordingly. A card can be partially redeemed more than once, and each spend
+publishes its own event.
+
+Cancelling is refused once a card has been spent against, so cancellation can
+never take back value a customer has already used.
 
 > **NOTE:** Gift cards can also be `expired` if `expires_at` date has passed and the card hasn't been fully redeemed.
 

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

@@ -74,7 +74,7 @@ Each store owns its own resources. Products, orders, channels, markets, and taxo
 | [**Products**](products.md) | A product belongs to one store. Its visibility across channels is controlled by [publications](channels.md#publishing-products-on-channels). |
 | [**Categories**](products.md#categories) | A category belongs to one store |
 | [**Payment Methods**](payments.md) | A payment method belongs to one store |
-| [**Shipping Methods**](shipments.md) | A shipping method belongs to one store |
+| [**Shipping Methods**](fulfillments.md) | A shipping method belongs to one store |
 | [**Promotions**](promotions.md) | A promotion belongs to one store |
 
 ## Running Multiple Storefronts