@spree/docs 0.1.230 → 0.1.232

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

@@ -163,6 +163,7 @@ how postage records work in general.
 
 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')
 
@@ -173,32 +174,70 @@ await adminClient.orders.claims.resolve('or_xxx', 'clm_xxx', {
 })
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/clm_xxx/approve' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/clm_xxx/resolve' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "resolution": "refund_and_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')
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch_xxx/approve' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch_xxx/receive' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch_xxx/fulfill' \
+  -H 'X-Spree-API-Key: sk_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' } })
+const pending = await adminClient.returns.list({ status_eq: 'approved' })
 
 // Claims opened this month
 const claims = await adminClient.claims.list({
-  filter: { created_at_gt: '2026-08-01' },
+  created_at_gt: '2026-08-01',
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/returns?q[status_eq]=approved' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl 'https://api.mystore.com/api/v3/admin/claims?q[created_at_gt]=2026-08-01' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 ## 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.

package/dist/developer/core-concepts/search-filtering.md

@@ -278,8 +278,7 @@ See [Querying](../../api-reference/store-api/querying.md) for the full list of f
 
 Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
 
-```ruby
-# config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
 ```
 

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

@@ -52,12 +52,62 @@ stateDiagram-v2
 
 Only an **approved** seller can sell, and even then not while they're on holiday — sellers can pause their own listings without the marketplace suspending them.
 
+## What a seller owns
+
+A seller is a tenant inside the marketplace: their own catalogue, their own
+stock, their own shipping setup and their own money trail. Delivery profiles and
+zones stay with the operator — a seller picks from them rather than defining
+them.
+
+```mermaid
+erDiagram
+    Store ||--o{ Seller : "hosts"
+    Seller ||--o{ Product : "lists"
+    Seller ||--o{ StockLocation : "ships from"
+    Seller ||--o{ DeliveryMethod : "own rates"
+    Seller ||--o{ PackageType : "own packaging"
+    Seller ||--o{ Order : "fulfils"
+    Seller ||--o{ CommissionLine : "charged"
+    Seller ||--o{ SellerTransfer : "earns"
+    Seller ||--o{ SellerPayout : "paid out"
+    Seller ||--o{ SellerRequirementSubmission : "onboarding"
+    Seller ||--o{ Policy : "publishes"
+
+    Seller {
+        string name
+        string slug
+        string status
+        string contact_email
+    }
+```
+
+A seller's delivery methods are their own — internal rates and manual
+fulfillment, since carrier accounts stay with the operator. Their package types
+sit alongside the marketplace's shared ones, so they can pack into the
+operator's standard cartons or record their own.
+
+
 ```typescript Admin SDK
 await adminClient.sellers.invite('sel_xxx')
 await adminClient.sellers.approve('sel_xxx')
 await adminClient.sellers.suspend('sel_xxx', { reason: 'Unresolved delivery complaints' })
 ```
 
+```bash cURL
+# Invite, approve, suspend
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/invite' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/approve' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/suspend' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "reason": "Unresolved delivery complaints" }'
+```
+
+
 Status is never set by writing to the field — each move is its own action, so approving a seller can run the checks that belong to approving.
 
 ## Onboarding requirements
@@ -66,17 +116,35 @@ What a vendor must do before selling differs by marketplace. A hardware marketpl
 
 So the checklist is **configured, not hardcoded**. Each store defines its own:
 
+
 ```typescript Admin SDK
 const { data: types } = await adminClient.sellerRequirements.types()
 
 await adminClient.sellerRequirements.create({
-  type: 'Spree::SellerRequirements::MinimumProducts',
+  type: 'minimum_products',
   name: 'List at least three products',
   required: true,
   preferences: { minimum_count: 3 },
 })
 ```
 
+```bash cURL
+# Requirement kinds this marketplace offers
+curl 'https://api.mystore.com/api/v3/admin/seller_requirements/types' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+# Add one to the checklist
+curl -X POST 'https://api.mystore.com/api/v3/admin/seller_requirements' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "minimum_products",
+    "name": "List at least three products",
+    "required": true
+  }'
+```
+
+
 Requirements come in three flavours, which is what lets one mechanism cover very different demands:
 
 | Kind | How it's satisfied |
@@ -89,6 +157,7 @@ Shipped out of the box: accepting terms, completing the profile, a billing addre
 
 A seller sees their checklist and its progress:
 
+
 ```typescript Seller SDK
 const onboarding = await sellerClient.onboarding.get()
 
@@ -102,6 +171,13 @@ onboarding.requirements.forEach((r) => {
 await sellerClient.onboarding.submitForReview()
 ```
 
+```bash cURL
+curl 'https://marketplace.example.com/api/v3/seller/onboarding' \
+  -H 'Authorization: Bearer $SELLER_JWT' \
+  -H 'X-Spree-Seller-Id: sel_xxx'
+```
+
+
 The checklist is **worked out when read**, never stored on the seller. So a requirement added next month applies immediately to everyone, and nothing has to be backfilled.
 
 > **NOTE:** The checklist is enforced at exactly two moments — submitting for review, and approval. Approval refuses while a required item is outstanding, unless an operator deliberately overrides it.
@@ -114,11 +190,26 @@ A product can name a seller. No seller means it's the marketplace's own stock
 
 Sellers don't publish; they **submit**, and the marketplace decides. That review flow, and the statuses behind it, are covered in [Products](products.md#seller-submissions).
 
+
 ```typescript Seller SDK
 const product = await sellerClient.products.create({ name: 'Handmade Vase' })
 await sellerClient.products.submit(product.id)
 ```
 
+```bash cURL
+# Create a product, then submit it for review
+curl -X POST 'https://marketplace.example.com/api/v3/seller/products' \
+  -H 'Authorization: Bearer $SELLER_JWT' \
+  -H 'X-Spree-Seller-Id: sel_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "name": "Handmade Vase" }'
+
+curl -X POST 'https://marketplace.example.com/api/v3/seller/products/prod_xxx/submit' \
+  -H 'Authorization: Bearer $SELLER_JWT' \
+  -H 'X-Spree-Seller-Id: sel_xxx'
+```
+
+
 Stores that trust their vendors can turn auto-approval on and skip the queue.
 
 ## One checkout, several sellers
@@ -156,12 +247,19 @@ Two details worth knowing:
 
 Commission is what the marketplace charges for the sale — configured as **rates**, and recorded per sale as immutable **commission lines**.
 
+
 ```typescript Admin SDK
 const { data: lines } = await adminClient.commissionLines.list({
-  filter: { seller_id_eq: 'sel_xxx' },
+  seller_id_eq: 'sel_xxx',
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/commission_lines?q[seller_id_eq]=sel_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 Three things are worth knowing here; the rest is on its own page.
 
 - **Rates are tried in list order**, and the first whose rules match wins. A rate with no rules matches everything, so the marketplace default belongs at the bottom.
@@ -184,6 +282,7 @@ Sellers get their own application — not access to the marketplace's dashboard.
 
 That last point is the security property worth relying on: a seller cannot ask for another seller's data, because there's nowhere in the request to name one.
 
+
 ```typescript Seller SDK
 import { createSellerClient } from '@spree/seller-sdk'
 
@@ -197,6 +296,14 @@ await sellerClient.orders.fulfillments.fulfill(orderId, fulfillmentId, {
 })
 ```
 
+```bash cURL
+# Sign in, then use the returned JWT on every seller call
+curl -X POST 'https://marketplace.example.com/api/v3/seller/auth/login' \
+  -H 'Content-Type: application/json' \
+  -d '{ "email": "vendor@example.com", "password": "…" }'
+```
+
+
 Sellers can manage their profile, invite their own team, list and submit products, see and fulfil their orders, manage their stock locations, delivery methods and packaging, and work through onboarding. They cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.
 
 What a seller's staff may do is governed by [roles](staff-roles.md) owned by the seller — the same permission system as the back office, with a narrower set of keys, so a seller role can never reach store settings.

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

@@ -59,7 +59,7 @@ If a slug already exists, Spree appends the SKU or a unique identifier to ensure
 
 Category slugs include the full parent path, making them hierarchical:
 
-```
+```text
 clothing                       → "clothing"
 clothing/shirts                → "clothing/shirts"
 clothing/shirts/t-shirts       → "clothing/shirts/t-shirts"

package/dist/developer/core-concepts/staff-roles.md

@@ -44,6 +44,7 @@ Because roles are scoped to their owner, two stores can each define a "Manager"
 
 A permission key is a verb and a resource — `read_orders`, `write_products`. Roles hold a list of them:
 
+
 ```typescript Admin SDK
 const role = await adminClient.roles.create({
   name: 'Fulfillment staff',
@@ -52,12 +53,31 @@ const role = await adminClient.roles.create({
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/roles' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Fulfillment staff",
+    "description": "Can see orders and ship them, nothing else",
+    "permissions": ["read_orders", "write_fulfillments", "read_products"]
+  }'
+```
+
+
 Every grantable key is discoverable, so a permission picker never needs a hardcoded list:
 
+
 ```typescript Admin SDK
 const { data: permissions } = await adminClient.permissions.list()
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/permissions' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 Keys are grouped so they can be presented sensibly — orders, catalog, marketing, customers, settings, access and analytics.
 
 | Group | Covers |
@@ -84,13 +104,13 @@ A role is deletable only when nothing depends on it: staff assignments and pendi
 
 Use the Spree CLI to create admin users:
 
-```bash
+```bash Spree CLI
 spree user create
 ```
 
 The CLI will prompt you for the email and password. You can also pass them directly:
 
-```bash
+```bash Spree CLI
 spree user create --email admin@example.com --password secret123
 ```
 
@@ -140,7 +160,7 @@ You can invite new admins through the Admin Panel or programmatically.
 
 Using the [Admin SDK](../sdk/admin/quickstart.md), call `client.invitations.create`:
 
-```typescript
+```typescript Admin SDK
 import { createAdminClient } from '@spree/admin-sdk'
 
 const client = createAdminClient({

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

@@ -74,26 +74,22 @@ erDiagram
 | `currency` | Currency code | `USD` |
 | `memo` | Optional note about the credit | `Refund for order #R123` |
 
-### Store Credit Categories
+### Why a Credit Exists
 
-Categories help organize store credits by their purpose:
+Store credits carry no category and no type — both were retired in Spree 6.0
+because neither answered a question anything asked. Two fields cover it
+instead:
 
-| Category | Description |
-|----------|-------------|
-| Default | General purpose store credit (also the default reimbursement category) |
-| Expiring | Store credit that may expire |
-| Non-expiring | Store credit that does not expire |
+| Field | What it tells you |
+|-------|-------------------|
+| `originator` | The return, exchange, claim or gift card that issued the credit, or nothing when an admin issued it by hand |
+| `memo` | The free-text reason, written by the refund workflows or by the admin |
 
-> **INFO:** "Gift Card" is not a seeded category but a special name recognized by the model: any category named "Gift Card" (or one listed in `Spree::Config[:non_expiring_credit_types]`) is treated as non-expiring via `StoreCreditCategory#non_expiring?`.
+Store credits do not expire; only gift cards carry an expiry, on their own
+record. Which credit is spent first is decided by `Spree::StoreCredit.oldest_first`.
 
-### Store Credit Types
-
-Types define the priority in which store credits are applied at checkout:
-
-| Type | Description |
-|------|-------------|
-| Expiring | Credits that may expire (applied first) |
-| Non-expiring | Credits that don't expire (applied last) |
+> **NOTE:** `Spree::StoreCreditCategory` and `Spree::StoreCreditType` survive as deprecated
+> shells for one release and are removed in 6.1. Nothing writes them.
 
 ### Store Credit Events
 
@@ -115,7 +111,7 @@ Store credits are managed in the Admin Panel:
 2. Select a customer
 3. Go to the **Store Credits** tab
 4. Click **Add Store Credit**
-5. Enter the amount, category, and optional memo
+5. Enter the amount, currency, and optional memo
 6. Click **Create**
 
 Store credits can also be created via the [Admin API](../../api-reference/admin-api/introduction.md), as a nested resource under the customer:
@@ -132,7 +128,6 @@ const client = createAdminClient({
 const credit = await client.customers.storeCredits.create('cus_xxx', {
   amount: '25.00',
   currency: 'USD',
-  category_id: 'sccat_xxx',
   memo: 'Goodwill credit for delayed shipment',
 })
 ```
@@ -141,12 +136,55 @@ const credit = await client.customers.storeCredits.create('cus_xxx', {
 spree api post /customers/cus_xxx/store_credits -d '{
   "amount": "25.00",
   "currency": "USD",
-  "category_id": "sccat_xxx",
   "memo": "Goodwill credit"
 }'
 ```
 
 
+### Listing Store Credits Across Customers
+
+Credits are written per customer, but read across them. The Admin API exposes a
+read-only list so an integration can answer what the store owes without walking
+every customer:
+
+
+```typescript Admin SDK
+const { data: credits, meta } = await client.storeCredits.list({
+  outstanding: true,
+  expand: ['customer', 'created_by'],
+})
+
+// One row per currency, summed over the same filter as the page.
+meta.totals.forEach((total) => {
+  console.log(total.currency, total.display_amount_remaining)
+})
+```
+
+```bash CLI
+spree api get /store_credits -q 'outstanding=true'
+```
+
+
+Filters mirror the questions a merchant asks: `customer_id`,
+`customer_email_cont`, `currency`, `created_by_id`, `memo_cont`, a
+`created_at` range, and two scopes — `outstanding` (money still owed versus
+money spent) and `from_gift_card` (whether a gift card redemption created it).
+
+Each credit's ledger is its own endpoint:
+
+
+```typescript Admin SDK
+const { data: events } = await client.storeCredits.events.list('credit_xxx')
+```
+
+```bash CLI
+spree api get /store_credits/credit_xxx/events
+```
+
+
+Creating, updating and deleting a credit remain nested under the customer that
+holds it — a credit without an owner has nobody to pay.
+
 ### Store Credit Events
 
 The store credit system publishes lifecycle events:
@@ -387,10 +425,9 @@ flowchart TB
 
 ### Store Credit Priority
 
-When a registered customer has multiple store credits, they are applied in order of priority:
-
-1. **Expiring credits** - Applied first to ensure they're used before expiration
-2. **Non-expiring credits** - Applied after expiring credits
+When a registered customer holds several store credits, the oldest is spent
+first (`Spree::StoreCredit.oldest_first`). Store credits do not expire — only
+gift cards carry an expiry, on their own record.
 
 ## Related Documentation
 

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

@@ -7,6 +7,27 @@ description: Understand Spree Stores — the top-level tenant boundary that scop
 
 The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).
 
+```mermaid
+erDiagram
+    Store ||--o{ Channel : "sells through"
+    Store ||--o{ Market : "trades in"
+    Store ||--o{ Product : "catalogs"
+    Store ||--o{ Order : "records"
+    Store ||--o{ PaymentMethod : "accepts"
+    Store ||--o{ StockLocation : "ships from"
+    Store ||--o{ Policy : "publishes"
+    Store ||--o{ Seller : "hosts"
+
+    Store {
+        string name
+        string code
+        string url
+        string default_currency
+        string default_locale
+        boolean default
+    }
+```
+
 ## Store Attributes
 
 | Attribute | Description |

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

@@ -36,6 +36,7 @@ Every product carries one. If you don't choose, the default is used.
 | `is_default` | Used by products that don't pick one | `true` |
 | `tax_code` | The code your tax service knows it by | `1257L` |
 
+
 ```typescript Admin SDK
 const reduced = await adminClient.taxCategories.create({
   name: 'Reduced rate',
@@ -43,6 +44,14 @@ const reduced = await adminClient.taxCategories.create({
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/tax_categories' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "name": "Reduced rate", "tax_code": "1257L" }'
+```
+
+
 `tax_code` matters once you connect an external service — it is how you tell that service what kind of thing this is, in the vocabulary it already uses.
 
 ## Tax rates
@@ -57,6 +66,7 @@ A tax rate is the number itself, plus where it applies and whether it's already
 | `country_code` / `state_code` | Where it applies | `DE`, or `US` + `CA` |
 | `tax_category` | What it applies to | `Standard` |
 
+
 ```typescript Admin SDK
 const { data: rates } = await adminClient.taxRates.list()
 
@@ -69,6 +79,25 @@ await adminClient.taxRates.create({
 })
 ```
 
+```bash cURL
+# List tax rates
+curl 'https://api.mystore.com/api/v3/admin/tax_rates' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+# Create one
+curl -X POST 'https://api.mystore.com/api/v3/admin/tax_rates' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "VAT 20%",
+    "amount": "0.2",
+    "included_in_price": true,
+    "country_code": "GB",
+    "tax_category_id": "taxcat_xxx"
+  }'
+```
+
+
 Rates name their country and state by **ISO code**, not by an ID — `DE`, `US` + `CA`. There's no separate region record to create first.
 
 ## Included or added on
@@ -120,10 +149,17 @@ Whatever works out the tax, the record is the same: a tax line per charge, sayin
 | `amount` / `display_amount` | The tax charged |
 | `line_item_id` / `fulfillment_id` / `fee_id` | What was taxed — exactly one is set |
 
+
 ```typescript Admin SDK
 const { data: taxLines } = await adminClient.orders.taxLines.list('or_xxx')
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/orders/or_xxx/tax_lines' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 Tax lines attach to a line item, a [fulfillment](fulfillments.md), or a [fee](fees.md) — so tax on goods and tax on delivery stay separately visible, which is what a tax return needs.
 
 Each line also keeps its own copy of the rate and label. If someone edits that tax rate next year, the order still says what the customer was actually charged.
@@ -153,10 +189,17 @@ Spree's built-in rate tables are fine when the rules are simple — one country,
 
 For those, connect a real tax service. **The provider is chosen per [Market](markets.md)**, which means one store can use its own rates in a simple market and an external service in a complicated one.
 
+
 ```typescript Admin SDK
 const { data: providers } = await adminClient.taxProviders.list()
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/tax_providers' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 A provider declares up front what it cannot do — no US local tax, no reverse charge — so the dashboard can warn a merchant who pairs it with a market that needs it, rather than quietly under-collecting.
 
 Whichever provider is in use, the result is the same: tax lines on the order, in the same shape. Your storefront code doesn't change.

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

@@ -87,6 +87,7 @@ Merchants translate in the dashboard, switching locale on the record they're edi
 
 Translations can also be written through the Admin API, which is what you'd use to sync from an external translation service:
 
+
 ```typescript Admin SDK
 await adminClient.products.update('prod_xxx', {
   translations: {
@@ -99,6 +100,14 @@ await adminClient.products.update('prod_xxx', {
 const { data: resources } = await adminClient.translatableResources.list()
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "translations": { "de": { "name": "Baumwolltasche" } } }'
+```
+
+
 Asking the API which resources are translatable means a translation tool doesn't need a hardcoded list that goes stale.
 
 ## Translating the interface