@spree/docs 0.1.176 → 0.1.178

package/dist/api-reference/store.yaml

@@ -879,8 +879,8 @@ paths:
               example:
                 data:
                 - id: prod_UkLWZg9DAJ
-                  name: Product 1426979
-                  slug: product-1426979
+                  name: Product 1496979
+                  slug: product-1496979
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1054,8 +1054,8 @@ paths:
               example:
                 data:
                 - id: prod_UkLWZg9DAJ
-                  name: Product 1879085
-                  slug: product-1879085
+                  name: Product 1949085
+                  slug: product-1949085
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1086,8 +1086,8 @@ paths:
                   original_price:
                   seller_id:
                 - id: prod_gbHJdmfrXB
-                  name: Product 1888209
-                  slug: product-1888209
+                  name: Product 1958209
+                  slug: product-1958209
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1215,8 +1215,8 @@ paths:
             application/json:
               example:
                 id: prod_UkLWZg9DAJ
-                name: Product 2156885
-                slug: product-2156885
+                name: Product 2226885
+                slug: product-2226885
                 meta_title:
                 meta_description:
                 meta_keywords:
@@ -1565,8 +1565,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 116715
-                    slug: product-116715
+                    name: Product 123715
+                    slug: product-123715
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -1674,8 +1674,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 1172171
-                    slug: product-1172171
+                    name: Product 1242171
+                    slug: product-1242171
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -1969,7 +1969,7 @@ paths:
                 total_quantity: 0
                 warnings:
                 - code: line_item_removed
-                  message: Product 121307 was removed because it was sold out
+                  message: Product 128307 was removed because it was sold out
                   line_item_id: li_UkLWZg9DAJ
                   variant_id: variant_UkLWZg9DAJ
                 coupon_code:
@@ -2177,8 +2177,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1223263
-                  slug: product-1223263
+                  name: Product 1293263
+                  slug: product-1293263
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2453,8 +2453,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1248992
-                  slug: product-1248992
+                  name: Product 1318992
+                  slug: product-1318992
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2657,8 +2657,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1274794
-                  slug: product-1274794
+                  name: Product 1344794
+                  slug: product-1344794
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2986,8 +2986,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1534241
-                  slug: product-1534241
+                  name: Product 1604241
+                  slug: product-1604241
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3175,8 +3175,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1553461
-                  slug: product-1553461
+                  name: Product 1623461
+                  slug: product-1623461
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3347,8 +3347,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1578182
-                  slug: product-1578182
+                  name: Product 1648182
+                  slug: product-1648182
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3633,8 +3633,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1595702
-                  slug: product-1595702
+                  name: Product 1665702
+                  slug: product-1665702
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3877,8 +3877,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1639569
-                  slug: product-1639569
+                  name: Product 1709569
+                  slug: product-1709569
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4021,10 +4021,10 @@ paths:
                 total_quantity: 2
                 warnings:
                 - code: delivery_unavailable
-                  message: Product 16663 cannot be delivered to the selected address
+                  message: Product 17363 cannot be delivered to the selected address
                   line_item_id: li_UkLWZg9DAJ
                 - code: delivery_unavailable
-                  message: Product 167298 cannot be delivered to the selected address
+                  message: Product 174298 cannot be delivered to the selected address
                   line_item_id: li_gbHJdmfrXB
                 coupon_code:
                 item_total: '29.99'
@@ -4078,8 +4078,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 16663
-                  slug: product-16663
+                  name: Product 17363
+                  slug: product-17363
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4109,8 +4109,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 167298
-                  slug: product-167298
+                  name: Product 174298
+                  slug: product-174298
                   options_text: ''
                   price: '19.99'
                   display_price: "$19.99"
@@ -4324,8 +4324,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1739165
-                  slug: product-1739165
+                  name: Product 1809165
+                  slug: product-1809165
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5116,8 +5116,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2359789
-                  slug: product-2359789
+                  name: Product 2429789
+                  slug: product-2429789
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5324,8 +5324,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 237179
-                  slug: product-237179
+                  name: Product 244179
+                  slug: product-244179
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5485,8 +5485,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 177496
-                  slug: product-177496
+                  name: Product 184496
+                  slug: product-184496
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -6575,8 +6575,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 1435270
-                    slug: product-1435270
+                    name: Product 1505270
+                    slug: product-1505270
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -6875,8 +6875,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1455633
-                  slug: product-1455633
+                  name: Product 1525633
+                  slug: product-1525633
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -9203,7 +9203,7 @@ paths:
                 variant:
                   id: variant_gbHJdmfrXB
                   product_id: prod_gbHJdmfrXB
-                  sku: SKU-289
+                  sku: SKU-298
                   options_text: ''
                   track_inventory: true
                   media_count: 0

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