@spree/docs 0.1.177 → 0.1.179

package/dist/developer/cli/quickstart.md

@@ -1,6 +1,6 @@
 ---
 title: Spree CLI
-sidebarTitle: Overview
+sidebarTitle: Spree CLI
 description: Install and use the @spree/cli to scaffold, run, build, and migrate Spree projects — and call the Admin API directly from the command line.
 ---
 

package/dist/developer/contributing/creating-an-extension.md

@@ -237,8 +237,8 @@ While this tutorial uses decorators to extend Spree's core behavior, modern Spre
 | React to model changes | [Events subscribers](../core-concepts/events.md) |
 | External service integration | [Webhooks](../core-concepts/webhooks.md) |
 | Replace core services | [Dependencies injection](../customization/dependencies.md) |
-| Add admin UI elements | [Admin Partials](../admin/extending-ui.md) |
-| Add admin menu items | [Admin Navigation](../admin/navigation.md) |
+| Add admin UI elements | [Admin Partials](../dashboard/customization/quickstart.md) |
+| Add admin menu items | [Admin Navigation](../dashboard/customization/navigation.md) |
 
 For example, if your extension needs to sync data with an external service when products are updated, use an Events subscriber instead of a decorator callback:
 

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

@@ -243,7 +243,7 @@ For countries without predefined states, addresses accept a free-text `state_nam
 
 ## Zones
 
-Zones group countries or states together for [tax](taxes.md) and [shipping](shipments.md) rules. A zone is either **country-based** or **state-based**.
+Zones group countries or states together for [tax](taxes.md) and [shipping](fulfillments.md) rules. A zone is either **country-based** or **state-based**.
 
 **Examples:**
 - **EU VAT** (country zone) — Germany, France, Italy, Spain, ... → applies EU VAT rates
@@ -252,7 +252,7 @@ Zones group countries or states together for [tax](taxes.md) and [shipping](ship
 
 When a customer enters their address at checkout, Spree matches it against zones to determine:
 1. Which **tax rates** apply (see [Taxes](taxes.md))
-2. Which **shipping methods** are available (see [Shipments](shipments.md))
+2. Which **shipping methods** are available (see [Shipments](fulfillments.md))
 
 Zones are configured in the admin dashboard — storefront developers don't interact with them directly via the API.
 
@@ -275,7 +275,7 @@ Here's how geography flows through a typical checkout:
 
 - [Markets](markets.md) — Multi-region commerce with currency, locale, and country grouping
 - [Taxes](taxes.md) — How zones and addresses affect taxation
-- [Shipments](shipments.md) — How zones and addresses affect shipping availability
+- [Shipments](fulfillments.md) — How zones and addresses affect shipping availability
 - [Orders](orders.md) — Order billing and shipping addresses
 - [Account SDK guide](../sdk/store/account.md) — Managing the logged-in customer's address book with `client.customer.addresses`
 - [Store API authentication](../../api-reference/store-api/authentication.md) — How to obtain and send the customer JWT (`Authorization: Bearer` header)

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

@@ -57,11 +57,11 @@ flowchart TB
 
 2. **Shopping** — Customers add Variants to their cart, creating an [Order](orders.md) with Line Items
 
-3. **Checkout** — The Order collects [Addresses](addresses.md), calculates [Shipping](shipments.md) options, and processes [Payments](payments.md)
+3. **Checkout** — The Order collects [Addresses](addresses.md), calculates [Shipping](fulfillments.md) options, and processes [Payments](payments.md)
 
-4. **Fulfillment** — [Shipments](shipments.md) are created from Stock Locations, tracking individual [Inventory Units](inventory.md#inventory-units)
+4. **Fulfillment** — [Shipments](fulfillments.md) are created from Stock Locations, tracking individual [Inventory Units](inventory.md#inventory-units)
 
-5. **Pricing & Adjustments** — [Taxes](taxes.md) and [Promotions](promotions.md) create [Adjustments](adjustments.md) that modify order totals
+5. **Pricing & Adjustments** — [Taxes](taxes.md) and [Promotions](promotions.md) create [Adjustments](taxes-discounts-fees.md) that modify order totals
 
 ## Core Model Relationships
 
@@ -172,5 +172,5 @@ Spree is distributed as a set of packages:
 - [Products](products.md) — Product catalog and variants
 - [Orders](orders.md) — Order lifecycle and state machine
 - [Payments](payments.md) — Payment processing
-- [Shipments](shipments.md) — Shipping and fulfillment
+- [Shipments](fulfillments.md) — Shipping and fulfillment
 - [Customization Quickstart](../customization/quickstart.md) — How to extend Spree

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

@@ -45,7 +45,7 @@ erDiagram
 **Key relationships:**
 - **Calculator** computes amounts for various features
 - Used by **[Tax Rates](taxes.md)** to calculate tax amounts
-- Used by **[Shipping Methods](shipments.md)** to calculate shipping costs
+- Used by **[Shipping Methods](fulfillments.md)** to calculate shipping costs
 - Used by **[Promotion Actions](promotions.md)** to calculate discounts
 - Calculators store [preferences (rates, percentages, etc.)](../customization/model-preferences.md) for their calculations
 
@@ -299,5 +299,5 @@ The module does not define `create_adjustment`, `update_adjustment`, or `compute
 
 ## Related Documentation
 
-- [Adjustments](adjustments.md) — the records calculators compute amounts for.
+- [Adjustments](taxes-discounts-fees.md) — the records calculators compute amounts for.
 - [Dependencies](../customization/dependencies.md) — swap out calculators via the Dependencies system.

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

@@ -0,0 +1,207 @@
+---
+title: Carts
+description: How Spree models the shopping and checkout phase — a cart collects items and customer details, then completing it creates an order.
+---
+
+## Overview
+
+A cart is everything that happens before a purchase is final: adding items, entering an address, choosing delivery, and paying. Completing a cart creates an [Order](orders.md) — a separate, permanent record.
+
+The two are kept apart because they want opposite things. A cart changes constantly, tolerates half-finished states, and is often abandoned. An order is a financial record: it must not change quietly, and it has to keep saying what the customer actually agreed to pay.
+
+```mermaid
+erDiagram
+    Cart ||--o{ LineItem : "has many"
+    Cart ||--o{ Fulfillment : "has many"
+    Cart ||--o| Order : "completes into"
+    Cart }o--|| Customer : "belongs to"
+
+    Cart {
+        string token
+        string email
+        string currency
+        string total
+        datetime completed_at
+    }
+
+    Order {
+        string number
+        string payment_status
+        string fulfillment_status
+        string total
+    }
+```
+
+## Cart attributes
+
+| Attribute | Description |
+|---|---|
+| `id` | Cart ID, e.g. `cart_86Rf07xd4z` |
+| `token` | Guest cart token — save it so a guest can return to their cart |
+| `email` | Customer's email address |
+| `currency` | Cart currency, e.g. `USD` |
+| `total_quantity` | Total number of items |
+| `requirements` | What the cart still needs before it can be completed |
+| `item_total` / `display_item_total` | Sum of line item prices |
+| `delivery_total` / `display_delivery_total` | Delivery cost |
+| `tax_total` / `display_tax_total` | Total tax |
+| `discount_total` / `display_discount_total` | Total discount |
+| `total` / `display_total` | Cart total |
+| `amount_due` / `display_amount_due` | Still to pay after store credit and gift cards |
+| `warnings` | Items removed or changed since the customer last looked |
+| `completed_at` | Set once checkout succeeded |
+
+Every amount comes in two forms: `total` is the raw value (`"135.60"`) and [`display_total` is formatted for the currency](../../api-reference/store-api/monetary-amounts.md) (`"$135.60"`). Render the `display_` one.
+
+> **NOTE:** Money is sent as a **string**, not a number. JavaScript numbers can't represent every decimal exactly — `0.1 + 0.2` gives `0.30000000000000004` — which is not something you want inside a price. Let Spree do the arithmetic and render the formatted strings.
+
+## Creating a cart and adding items
+
+
+```typescript Store SDK
+// Create a cart
+const cart = await client.carts.create()
+// cart.token => "abc123" (save this for guest checkout)
+
+// Add an item
+await client.carts.items.create(cart.id, {
+  variant_id: 'var_xxx',
+  quantity: 2,
+})
+
+// Update quantity
+await client.carts.items.update(cart.id, 'li_xxx', { quantity: 3 })
+
+// Remove an item
+await client.carts.items.delete(cart.id, 'li_xxx')
+```
+
+```bash cURL
+# Create a cart
+curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
+  -H 'X-Spree-API-Key: pk_xxx'
+
+# Add an item
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "variant_id": "var_xxx", "quantity": 2 }'
+
+# Update quantity
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "quantity": 3 }'
+```
+
+
+Every change returns the whole cart with new totals, so you never need a second request to refresh the summary.
+
+When a guest signs in, attach their cart to the account:
+
+```typescript Store SDK
+await client.carts.associate(cartId, { spreeToken: 'abc123' })
+```
+
+## Checkout requirements
+
+A cart tells you what it still needs before it can be completed:
+
+```json
+{
+  "requirements": [
+    {
+      "step": "address",
+      "field": "email",
+      "code": "email_required",
+      "message": "Email address is required"
+    }
+  ]
+}
+```
+
+An empty `requirements` array means the cart is ready.
+
+This is what lets you design your own checkout. Spree tells you what's missing; you decide how and when to ask for it — one long page, a few steps, or whatever suits your storefront.
+
+## Checkout
+
+**Step 1: Add the customer's details**
+
+```typescript Store SDK
+    await client.carts.update(cartId, {
+      email: 'john@example.com',
+      shipping_address: {
+        first_name: 'John', last_name: 'Doe',
+        address1: '123 Main St', city: 'Los Angeles',
+        country_code: 'US', state_abbr: 'CA', postal_code: '90001',
+      },
+    })
+    ```
+
+  **Step 2: Choose delivery**
+
+Each [fulfillment](fulfillments.md) offers delivery rates. Pick one per fulfillment.
+
+    ```typescript Store SDK
+    const cart = await client.carts.get(cartId)
+    await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
+      selected_delivery_rate_id: 'rate_xxx',
+    })
+    ```
+
+  **Step 3: Take payment**
+
+For providers like Stripe, create a payment session and confirm it with their own SDK.
+
+    ```typescript Store SDK
+    const session = await client.carts.paymentSessions.create(cartId, {
+      payment_method_id: 'pm_xxx',
+    })
+    // session.external_data.client_secret => use with Stripe.js
+
+    await client.carts.paymentSessions.complete(cartId, session.id)
+    ```
+
+  **Step 4: Complete the cart**
+
+```typescript Store SDK
+    const order = await client.carts.complete(cartId)
+    ```
+
+    You get back an [Order](orders.md).
+
+
+Discount codes, gift cards and store credit can be applied any time before completion:
+
+```typescript Store SDK
+await client.carts.discountCodes.apply(cartId, 'SUMMER20')
+await client.carts.giftCards.apply(cartId, 'GIFT-XXXX')
+await client.carts.storeCredits.apply(cartId)
+```
+
+## What completion guarantees
+
+Completing a cart moves real money, so Spree is careful about it:
+
+**Double submission is safe.** A customer double-clicking "Place order" gets the same order back rather than a second charge. This holds even when your app runs on several servers.
+
+**An interrupted completion recovers.** If something dies after the customer was charged, trying again finishes the job instead of charging twice.
+
+**Totals are worked out at the last moment.** The amount charged is calculated when the cart is completed, not taken from an earlier request — so a price or promotion that changed while the customer was reviewing can't lead to the wrong charge.
+
+If a cart can't be completed you get told why — a payment failure, or unmet [requirements](#checkout-requirements) — and the cart is left alone so the customer can fix it and try again.
+
+## Abandoned carts
+
+Carts emit `cart.created`, `cart.updated` and `cart.deleted` [events](events.md), which also reach [webhooks](webhooks.md) — enough to drive abandonment email without polling for changes.
+
+Completed carts are kept rather than deleted, and an order records which cart it came from, so you can measure conversion. Abandoned carts are cleared out on a schedule you control; carts with a payment in progress are never removed.
+
+## Related
+
+- [Orders](orders.md) — the record a cart becomes
+- [Payments](payments.md) — payment methods and sessions
+- [Fulfillments](fulfillments.md) — delivery options

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

@@ -22,7 +22,7 @@ Every store ships with one default channel named *Online Store*. You can add mor
 | `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
 | `storefront_access` | Controls what an anonymous visitor may see: `public`, `prices_hidden`, or `login_required`. Unset inherits the store's setting. See [Storefront Access Gating](#storefront-access-gating) | `login_required` |
 | `guest_checkout` | Whether an order may be placed without an account on this channel. Unset inherits the store's setting | `false` |
-| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](shipments.md#order-routing) strategy | `Spree::OrderRouting::Strategy::Rules` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](fulfillments.md#order-routing) strategy | `Spree::OrderRouting::Strategy::Rules` |
 
 `code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
 
@@ -89,7 +89,7 @@ Product status (`draft` / `active` / `archived`) is the **outer gate**: a Draft
 
 Every order is attributed to one channel. The channel is set from the `X-Spree-Channel` header on cart creation, from the merchant's selection on the "New order" form, or defaults to the store's primary channel.
 
-This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](shipments.md#order-routing).
+This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](fulfillments.md#order-routing).
 
 ### Storefront Access Gating
 
@@ -217,7 +217,7 @@ The write contract is **full-set**: the array represents the complete desired st
 - [Stores](stores.md) — Channels belong to a store
 - [Markets](markets.md) — Different from channels: markets segment geography/currency, channels segment selling surfaces
 - [Products](products.md) — Product catalog and publication
-- [Order Routing](shipments.md#order-routing) — Channels can override the store's routing strategy
+- [Order Routing](fulfillments.md#order-routing) — Channels can override the store's routing strategy
 - [Store SDK: Products](../sdk/store/products.md) — Channel-scoped product listing and filtering
 - [Admin SDK: Resources](../sdk/admin/resources.md) — How `adminClient.channels.addProducts` and other resource methods are structured
 - [Wholesale Portal](../storefront/nextjs/wholesale.md) — A gated channel driving the Next.js storefront's B2B surface

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

@@ -305,5 +305,5 @@ Customers don't need to register to purchase. Guest checkout uses an order token
 - [Account (Store SDK)](../sdk/store/account.md) — Task-oriented walkthrough of registration, login, profile, addresses, and order history
 - [Addresses](addresses.md) — Customer address management
 - [Orders](orders.md) — Order history and checkout
-- [Authentication](../customization/authentication.md) — Custom authentication setup
+- [Authentication](../providers/sso.md) — Custom authentication setup
 - [Staff & Roles](staff-roles.md) — Admin users and permissions

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

@@ -641,4 +641,4 @@ The base class also provides helper methods:
 - [Webhooks & Events Reference](../../api-reference/webhooks-events.md) - Catalog of event and webhook payloads
 - [Customization Quickstart](../customization/quickstart.md) - Overview of all customization options
 - [Decorators](../customization/decorators.md) - When to use decorators vs events
-- [Checkout Flow](../customization/checkout.md) - Using events in checkout customization
+- [Checkout Flow](carts.md) - Using events in checkout customization

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

@@ -0,0 +1,278 @@
+---
+title: Fulfillments
+description: How Spree models getting items to the customer — fulfillments, delivery methods and zones, and delivery types covering shipping, digital and pickup.
+---
+
+## Overview
+
+A fulfillment is one batch of items going to the customer by one method — a parcel from a warehouse, a digital download, or an order waiting at a pickup counter. An order gets one fulfillment per combination of stock location and delivery method, so an order sourced from two warehouses has two.
+
+The word is deliberately broader than "shipment". A digital download has no carrier, no address and no package, and click-and-collect ships nowhere at all — a fulfillment covers all of them without dragging along fields that make no sense for most.
+
+```mermaid
+erDiagram
+    Order ||--o{ Fulfillment : "has many"
+    Fulfillment ||--o{ FulfillmentItem : "has many"
+    Fulfillment ||--o{ DeliveryRate : "offers"
+    Fulfillment }o--|| StockLocation : "sourced from"
+    DeliveryRate }o--|| DeliveryMethod : "priced by"
+    DeliveryMethod }o--o{ DeliveryZone : "serves"
+
+    Fulfillment {
+        string number
+        string status
+        string tracking
+        string cost
+        datetime fulfilled_at
+    }
+```
+
+## Fulfillment attributes
+
+| Attribute | Description |
+|---|---|
+| `id` | Fulfillment ID, e.g. `ful_86Rf07xd4z` |
+| `number` | Fulfillment number, e.g. `F123456789` |
+| `status` | See [statuses](#statuses) below |
+| `tracking` | Carrier tracking number, once it's on its way |
+| `cost` / `display_cost` | Delivery cost for this fulfillment |
+| `delivery_rates` | The options the customer can choose from |
+| `selected_delivery_rate_id` | The chosen option |
+| `fulfilled_at` | When it went out |
+
+## Statuses
+
+A fulfillment's status says what **you** did with the parcel — nothing else.
+
+| Value | Meaning |
+|---|---|
+| `unfulfilled` | Still with you. Nothing has left |
+| `fulfilled` | It went out — handed to the carrier, or waiting at the counter for a pickup order |
+| `delivered` | The customer has it |
+| `canceled` | It won't be sent |
+
+Statuses only move forward: once something has gone out it stays gone out, and a later payment problem changes the order's [payment status](orders.md#statuses) rather than the fulfillment.
+
+Whether a fulfillment *can* go out — the order is paid, nothing is on backorder — is checked when you fulfill it, and the answer comes back with a reason. It is not baked into the status, so a refund never moves a parcel backwards. Staff who need to ship against an invoice can pass `force`.
+
+### Where the parcel actually is
+
+Carrier reports live on a second field, `tracking_status`, and never change `status`:
+
+| Value | Meaning |
+|---|---|
+| `pre_transit` | Label made, carrier hasn't got it yet |
+| `in_transit` | On its way |
+| `out_for_delivery` | On the van |
+| `available_for_pickup` | Waiting at a carrier location |
+| `delivered` | Carrier says it arrived |
+| `return_to_sender` | Coming back to you |
+| `failure` | Delivery failed — a bad address, damage, a refused parcel |
+| `unknown` | The carrier said something we don't recognise |
+
+Keeping the two apart is the point. A parcel that bounces still shows `fulfilled`, because you did hand it over; the trouble shows up as `return_to_sender` and you decide what to do about it. The one report that crosses over is delivery, which also sets `delivered` and `delivered_at`.
+
+`delivered_at` is what return windows and the EU withdrawal period count from, so it records when the carrier says the parcel arrived rather than when you heard about it.
+
+Carriers set this through their provider's webhook. With no carrier integration, staff mark receipt by hand — `markDelivered` in the Admin SDK — which is also how pickup orders get closed out.
+
+## Delivery types
+
+Every delivery method has a type that decides how it behaves:
+
+| Type | Behaviour |
+|---|---|
+| `shipping` | Physical delivery to an address. Someone marks it sent. |
+| `digital` | Available the moment the order is placed. No address needed. |
+| `pickup` | Collection from one of your own stock locations. |
+| `pickup_point` | Collection from a third-party point — a locker or partner shop. |
+
+This is what lets a store sell a downloadable album and a vinyl record in the same order without any special handling in your storefront: the download is ready immediately, the record gets a tracking number.
+
+## Choosing delivery at checkout
+
+Each fulfillment on a cart offers delivery rates. The customer picks one per fulfillment.
+
+
+```typescript Store SDK
+const cart = await client.carts.get(cartId)
+
+cart.fulfillments[0].delivery_rates
+// => [{ id: 'rate_xxx', name: 'DHL Express', display_cost: '$12.00',
+//       estimated_delivery_date: '2026-08-07' }, ...]
+
+await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
+  selected_delivery_rate_id: 'rate_xxx',
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: abc123' \
+  -H 'Content-Type: application/json' \
+  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
+```
+
+
+Rates carry more than a price — carrier, service level and estimated delivery date — so you can show "DHL Express, arrives Tuesday" instead of just a number.
+
+## Pickup
+
+For pickup methods, ask the API where the customer can collect:
+
+
+```typescript Store SDK
+// Your own pickup-enabled locations
+const locations = await client.deliveryMethods.pickupLocations('dm_xxx')
+
+// Third-party pickup points near the customer
+const points = await client.deliveryMethods.pickupPoints('dm_xxx', {
+  latitude: 34.0522,
+  longitude: -118.2437,
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/delivery_methods/dm_xxx/pickup_locations' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
+## Managing fulfillments
+
+
+```typescript Admin SDK
+// What's still with you
+const fulfillments = await adminClient.orders.fulfillments.list('or_xxx')
+
+// Add tracking, then mark it sent
+await adminClient.orders.fulfillments.update('or_xxx', 'ful_xxx', {
+  tracking: '1Z999AA10123456784',
+})
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx')
+
+// Ship only some of it — the chosen units split off and ship,
+// the rest stays open
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx', {
+  items: [{ item_id: 'li_xxx', quantity: 1 }],
+})
+
+// Ship against an unpaid invoice — your call, not the API's
+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx', { force: true })
+
+// Record receipt yourself when no carrier reports it for you
+await adminClient.orders.fulfillments.markDelivered('or_xxx', 'ful_xxx')
+
+// Split it when only part can go now
+await adminClient.orders.fulfillments.split('or_xxx', 'ful_xxx', {
+  items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],
+})
+
+// Cancel
+await adminClient.orders.fulfillments.cancel('or_xxx', 'ful_xxx')
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "tracking": "1Z999AA10123456784" }'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx/fulfill' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
+## Delivery methods and zones
+
+A **delivery method** is what the customer picks — "Standard", "Express", "Collect in store". A **delivery zone** decides where it's available.
+
+Zones match on country and state, and also on postal code prefixes and ranges, so you can offer same-day delivery to a handful of city postcodes without listing every one:
+
+```typescript Admin SDK
+await adminClient.deliveryZones.create({
+  name: 'London same-day',
+  members: [
+    { member_type: 'postal_code', country_code: 'GB', postal_code_prefix: 'SW1' },
+    { member_type: 'postal_code', country_code: 'GB', postal_code_from: 'EC1A', postal_code_to: 'EC1V' },
+  ],
+})
+```
+
+A zone member is either a whole country, a state, or a postal code prefix or range.
+
+> **NOTE:** Delivery zones cover delivery only. Tax is handled separately — see [Taxes](taxes.md).
+
+### Pricing and rules
+
+Delivery is priced either by a rule you configure in the dashboard — flat rate, per item, price bands — or by asking a carrier for live rates.
+
+Methods can also carry conditions that decide when they're offered at all: free shipping over a certain order value, or heavy items excluded from letter post. These are applied in one place, so both kinds of pricing respect them.
+
+## Adding your own statuses
+
+A made-to-order business — print on demand, furniture built after purchase —
+has a stage between "order placed" and "handed to the carrier". There are two
+ways to model it, and the lighter one is usually right.
+
+**Track production in your own model, gate handover with a hook.** A production
+pipeline usually has more resolution than one word — queued, printing, quality
+check, packed — and that detail belongs in your own tables or your
+integration's metadata, not in the parcel's lifecycle vocabulary. What core
+needs to know is only *whether the parcel may go out yet*, and that is exactly
+what the fulfill workflow's validate hook expresses:
+
+```ruby
+Spree.hooks.register('fulfillments.fulfill.validate') do |flow|
+  work_order = MyApp::WorkOrder.find_by(fulfillment: flow.fulfillment)
+  flow.reject!('still in production') unless work_order&.completed?
+end
+```
+
+The fulfillment stays `unfulfilled` while you build the thing; your storefront
+renders "we're making your furniture" as presentation, the same way pickup
+orders render `fulfilled` as "ready for pickup".
+
+**Add a real status when merchants need to act on the stage.** If staff filter
+by it, reports group by it, or webhooks fire on entering it, make it a
+first-class status:
+
+```ruby
+# an initializer
+Spree::Fulfillment.add_status('in_production', after: 'unfulfilled')
+```
+
+That gives you the `in_production?` predicate, the `.in_production` scope and
+a valid value. Moving into it is deliberately not declarative — write a small
+workflow, which is also where the printer submission or the workshop handoff
+belongs:
+
+```ruby
+class MyApp::Fulfillments::StartProduction < Spree::Workflow
+  def perform(fulfillment:)
+    super
+    step :ensure_startable      # refuse unless fulfillment.unfulfilled?
+    step :mark_in_production    # update!(status: 'in_production') + publish an event
+    external_step :submit_to_printer
+    success(fulfillment.reload)
+  end
+end
+```
+
+Core's own actions keep working on your status without overrides: the guards
+ask whether the parcel has *already gone out*, not whether it holds one of the
+built-in values, so an `in_production` fulfillment can still be fulfilled or
+canceled. Statuses are additive only — core workflows guard on core statuses,
+so removing one would silently break them — and confirmed receipt still only
+follows handover.
+
+## Events
+
+Fulfillments publish [events](events.md) — `fulfillment.created`, `fulfillment.fulfilled`, `fulfillment.delivered`, `fulfillment.canceled` — which also reach [webhooks](webhooks.md). Use them to notify a customer, push to a warehouse system, or send tracking emails.
+
+## Related
+
+- [Orders](orders.md) — how delivery status rolls up
+- [Inventory](inventory.md) — stock locations and availability
+- [Returns, Exchanges & Claims](returns-exchanges-claims.md) — items coming back

package/dist/developer/core-concepts/imports-exports.md

@@ -270,24 +270,12 @@ module Spree
     has_many :mappings    # Field mappings
     has_many :rows        # CSV rows to process
 
-    # State machine
-    state_machine initial: :pending do
-      event :start_mapping do
-        transition to: :mapping
-      end
-      event :complete_mapping do
-        transition from: :mapping, to: :completed_mapping
-      end
-      event :start_processing do
-        transition from: :completed_mapping, to: :processing
-      end
-      event :complete do
-        transition from: :processing, to: :completed
-      end
-      event :fail do
-        transition to: :failed
-      end
-    end
+    # Statuses. Each move between them is a workflow — Spree::Imports::
+    # StartMapping, CompleteMapping, StartProcessing, Complete and
+    # RetryFailedRows — so every step of the pipeline can be hooked.
+    include Spree::HasStatus
+    has_status :pending, :mapping, :completed_mapping, :processing, :completed, :failed,
+               default: :pending
 
     # Key methods
     def import_schema        # Returns schema class instance