Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Documentation update

Damian Legawiec14824bda7b59
diff --git a/README.md b/README.md
index 8ffbad6f0f..795f48869e 100755
--- a/README.md
+++ b/README.md
@@ -39,12 +39,11 @@ This sets up the Spree Commerce backend, the Admin Dashboard, and the [Next.js s
You need to have Node.js (22+) installed and Docker running. Learn more in the [installation docs](https://spreecommerce.org/docs/developer/getting-started/quickstart).
-Or deploy directly to the cloud:
+If you like what you see, consider giving Spree a GitHub star ⭐
-[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/spree/spree-starter)
+Thank you for supporting Spree open-source ❤️
-> **Note**
-> This uses Render's free plan for quick evaluation. Free instances spin down after inactivity and may take 30-60s to wake up. For production, see [recommended sizing](https://spreecommerce.org/docs/developer/deployment/render#production-sizing).
+### Agentic Development
Building with an AI coding agent? Install the [Spree agent skills](https://github.com/spree/agent-skills) — they teach Claude Code, Cursor, Copilot, and 60+ other tools Spree's conventions, customization patterns, and upgrade flows:
@@ -59,20 +58,14 @@ Then connect the [docs MCP server](https://spreecommerce.org/docs/developer/agen
[`@spree/cli`](packages/cli) manages your Spree project from the terminal — boot the stack, run generators and migrations, tail logs — and calls the **Admin API** directly with simple `get`/`post`/`patch`/`delete` commands. It's a fast way to inspect and script your store, and works hands-free for AI agents (zero-config credentials in local dev):
```bash
-spree dev # boot the project (web + worker + db)
-spree generate model Wishlist # Rails generators, in the container
-spree api get /orders -q status_eq=complete --limit 10 # query the Admin API
-spree api post /products -d '{"name":"Classic Tee"}' # create resources
+spree dev # boot the project (web + worker + db)
+spree generate api_resource Brand name:string description:rich_text # Creates full API endpoints, models and database schema for a Brand resource
+spree api get /orders -q status_eq=complete --limit 10 # query the Admin API
+spree api post /products -d '{"name":"Classic Tee"}' # create resources
```
`spree api endpoints` and `spree api schema` explore the full API offline. See the [CLI docs](https://spreecommerce.org/docs/developer/cli/quickstart).
-If you prefer to install Spree manually, you may follow the [Quickstart Guide](https://spreecommerce.org/docs/developer/getting-started/quickstart).
-
-If you like what you see, consider giving Spree a GitHub star ⭐
-
-Thank you for supporting Spree open-source ❤️
-
## Features
Everything below ships in this repository under the BSD 3-Clause license.
@@ -82,15 +75,24 @@ Everything below ships in this repository under the BSD 3-Clause license.
* **[Next.js Storefront](https://github.com/spree/storefront)** — open-source storefront built with Next.js 16, React 19, Tailwind CSS 4, and TypeScript. Full shopping experience, multi-region URL routing, Stripe payments (Apple Pay, Google Pay, Klarna, Affirm), customer accounts, and SEO built in. [Try the demo](https://demo.spreecommerce.org/)
* **[Cross-Border Commerce](https://spreecommerce.org/docs/user/settings/markets)** — Markets bundle currency, language, payment methods, and shipping rules per country. Translations Center for bulk product localization. EU Omnibus Directive compliance with automatic 30-day price history.
* **[B2B & Wholesale](https://spreecommerce.org/docs/developer/core-concepts/products#price-lists)** — [Price Lists](https://spreecommerce.org/docs/developer/core-concepts/products#price-lists) for regional, B2B, and wholesale pricing. [Customer Groups](https://spreecommerce.org/docs/user/customers/customer-groups) for segmentation. Companies, company locations, and company contacts for buyer organizations. Catalogs for curated, per-segment product assortments. Gated storefronts via publishable keys.
-* **[Multi-Store](https://spreecommerce.org/docs/use-case/multi-store/capabilities)** — run multiple storefronts off a single Spree backend, each with its own domain, branding, products, and currency.
-* **[Payment Sessions](https://spreecommerce.org/docs/developer/core-concepts/payments)** — provider-agnostic payment processing. Ship with [Stripe](https://spreecommerce.org/docs/integrations/payments/stripe), [Adyen](https://spreecommerce.org/docs/integrations/payments/adyen) and PayPal without changing storefront checkout code.
-* **[Promotions & Gift Cards](https://spreecommerce.org/docs/user/promotions/create-a-promotion)** — advanced promotions engine and [Gift Cards](https://spreecommerce.org/docs/developer/core-concepts/store-credits-gift-cards).
+* **[Sales Channels](https://spreecommerce.org/docs/developer/core-concepts/channels)** — run multiple storefronts, Points of Sale, B2B panels, mobile apps off a single Spree backend, each with its products, pricing, payment methods, and shipping rules
+* **[Payment Sessions](https://spreecommerce.org/docs/developer/core-concepts/payments)** — provider-agnostic payment processing. Shipped with [Stripe](https://spreecommerce.org/docs/integrations/payments/stripe), [Adyen](https://spreecommerce.org/docs/integrations/payments/adyen) and [PayPal](https://spreecommerce.org/docs/integrations/payments/paypal) plugins ready to use with Next.js storefront. Add your own with the [Payment Provider SDK](https://spreecommerce.org/docs/developer/how-to/custom-payment-method).
+* **[Promotions & Gift Cards](https://spreecommerce.org/docs/user/promotions/create-a-promotion)** — advanced rules-based promotions engine and native [Gift Cards](https://spreecommerce.org/docs/developer/core-concepts/store-credits-gift-cards) support.
* **Products & Catalog** — [Metafields](https://spreecommerce.org/docs/developer/core-concepts/metafields), [CSV importer/exporter](https://spreecommerce.org/docs/user/manage-products/import-products), digital products, product tags, [bulk operations](https://spreecommerce.org/docs/user/manage-products/bulk-product-operations).
* **[MeiliSearch Integration](https://spreecommerce.org/docs/integrations/search/meilisearch)** — typo-tolerant product search and faceted filtering.
* **Admin Dashboard** — built with [Tailwind CSS](https://spreecommerce.org/docs/developer/admin/custom-css) with [role-based permissions](https://spreecommerce.org/docs/developer/customization/permissions).
* **Integrations & Extensibility** — [Event Bus](https://spreecommerce.org/docs/developer/core-concepts/events), [Webhooks 2.0](https://spreecommerce.org/docs/developer/core-concepts/webhooks), native integrations ([GA4](https://spreecommerce.org/docs/integrations/analytics/google-analytics), [GTM](https://spreecommerce.org/docs/integrations/analytics/google-tag-manager), [Klaviyo](https://spreecommerce.org/docs/integrations/marketing/klaviyo)).
* **[Agentic Development](https://spreecommerce.org/docs/developer/agentic/overview)** — [25 agent skills](https://github.com/spree/agent-skills) (`npx skills add spree/agent-skills`) teaching AI coding agents Spree's conventions, a [docs MCP server](https://spreecommerce.org/docs/developer/agentic/mcp), [LLM-ready documentation](https://spreecommerce.org/docs/developer/agentic/llm-docs) (llms.txt, per-page Markdown, offline npm package), and a generated AGENTS.md/CLAUDE.md in every scaffolded project.
+## Deployment
+
+You can quickly deploy a Spree store with the button below, or follow our [deployment guide](https://spreecommerce.org/docs/developer/deployment/overview) for detailed instructions on deploying to various platforms.
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/spree/spree-starter)
+
+> **Note**
+> This uses Render's free plan for quick evaluation. Free instances spin down after inactivity and may take 30-60s to wake up. For production, see [recommended sizing](https://spreecommerce.org/docs/developer/deployment/render#production-sizing).
+
## Screenshots
### [Next.js eCommerce Storefront](https://github.com/spree/storefront)
@@ -142,7 +144,7 @@ Enterprise Edition is built on top of the same open-source REST API and BSD 3-Cl
| Capability | Open-source (this repo) | Enterprise Edition |
|---|---|---|
| **REST API**, **TypeScript SDK**, Next.js storefront | ✅ | ✅ |
-| **Multi-store**, **Markets**, cross-border, multi-currency | ✅ | ✅ |
+| **Sales Channels**, **Markets**, cross-border, multi-currency | ✅ | ✅ |
| **Promotions**, **Gift Cards**, **Digital Products** | ✅ | ✅ |
| Payment integrations: **Stripe**, **Adyen**, **PayPal** | ✅ | ✅ |
| Automatic tax calculation with **Avatax** & **Stripe Tax** | ✅ | ✅ |
diff --git a/docs/api-reference/admin-api/authentication.mdx b/docs/api-reference/admin-api/authentication.mdx
index e82a53d543..abc7616267 100644
--- a/docs/api-reference/admin-api/authentication.mdx
+++ b/docs/api-reference/admin-api/authentication.mdx
@@ -28,14 +28,17 @@ const client = createAdminClient({
const { data: products } = await client.products.list()
```
-```bash cURL
-curl -X GET 'https://store.example.com/api/v3/admin/orders' \
- -H 'X-Spree-Api-Key: sk_xxx'
+```bash CLI
+# Point the CLI at your store + key, then call any endpoint:
+export SPREE_BASE_URL='https://store.example.com'
+export SPREE_API_KEY='sk_xxx'
+
+spree api get /products
```
</CodeGroup>
-Secret API keys are prefixed with `sk_`. Create them in the Spree admin under **Settings → API Keys** or via the Spree CLI:
+Secret API keys are prefixed with `sk_`. Create them with the [Spree CLI](/developer/cli/admin-api) or in the Spree admin under **Settings → API Keys**:
```bash
spree api-key create --type secret --scopes read_orders,write_products # Create a scoped secret key
@@ -159,9 +162,7 @@ If the key lacks the required scope, the API returns `403 Forbidden`:
}
```
-The `details.required_scope` field tells you exactly which scope to add.
-
-Pick scopes when creating the key in **Settings → API Keys**. Choose the narrowest set that covers your integration's needs.
+The `details.required_scope` field tells you exactly which scope to add — and `spree api-key create --type secret --scopes <scope>` mints a key that has it. Choose the narrowest set that covers your integration's needs.
### JWT bearer tokens: CanCanCan abilities
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index e18ba8f57e..3eb1cefe6e 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -51,16 +51,16 @@ paths:
The rotatable refresh token is set in an HttpOnly cookie — it is not
included in the response body.
- Dispatches by the `provider` field to a strategy registered in
- `Spree.admin_authentication_strategies`. When `provider` is omitted it
- defaults to `email`, which uses the built-in email/password strategy.
-
- To plug in a third-party identity provider (Okta, Azure AD, Google
- Workspace SSO, a custom JWT issuer, SAML, etc.), register a
- `Spree::Authentication::Strategies::BaseStrategy` subclass under a
- provider key, then send `{ "provider": "<your_key>", ... }` with the
- fields your strategy requires. The endpoint returns the same Spree-issued
- JWT regardless of which strategy authenticated the request.
+ The `provider` field selects the authentication method. When omitted it
+ defaults to `email`, the built-in email/password login.
+
+ To authenticate against a third-party identity provider (Okta, Azure AD,
+ Google Workspace SSO, a custom JWT issuer, SAML, etc.), send
+ `{ "provider": "<your_key>", ... }` with the fields that provider
+ requires. The endpoint returns the same JWT regardless of which provider
+ authenticated the request. See
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
+ for the list of configured providers and their required fields.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -92,15 +92,15 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImFiZTNmYTYyLThkNzctNDZiOC04YjI2LTNkYmU5NjZhNTgxYiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgxNDcyMTEzfQ.r0lKXmaNf3_BithpQIJLnFmNJYoegMn9n2LkxFJT-ao
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjVhNjhiODdkLWQwMjEtNDhhOC1hMjcxLTUzMTU4OTJiM2UzZiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgxNTI0OTIzfQ.mhyB5Pc3Z_2rq1cvir_ta0dZZ9guMNFfres7uoQANk8
user:
id: admin_UkLWZg9DAJ
- first_name: Dwana
- last_name: Gerlach
- full_name: Dwana Gerlach
- created_at: '2026-06-14T21:16:52.927Z'
- updated_at: '2026-06-14T21:16:52.927Z'
+ first_name: Gerry
+ last_name: Larkin
+ full_name: Gerry Larkin
+ created_at: '2026-06-15T11:57:03.475Z'
+ updated_at: '2026-06-15T11:57:03.475Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -143,10 +143,10 @@ paths:
- password
- title: ProviderLogin
description: |
- Provider-dispatched login. The `provider` key selects a registered
- strategy class; the remaining fields are forwarded to the strategy's
- `authenticate` method. Required fields depend on the registered strategy
- — consult its documentation.
+ Provider-dispatched login. The `provider` key selects a configured
+ authentication provider; the remaining fields are forwarded to it.
+ Required fields depend on the provider — see
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
type: object
properties:
provider:
@@ -198,15 +198,15 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjJkMGQ0YzE4LWI5ZWQtNDU2YS1hNzg3LTA5OTQ3ZjBhMTY2MCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgxNDcyMTE0fQ.oAszsCQPlmwGgG3lhh6ZJ8AcCQBFwsQwlyusxtBI8s4
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjViOTYxZjI5LTlkYzEtNGEzMy04NTQzLWE5ODQwZTBmNTVjYSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgxNTI0OTI0fQ.98mXpyaEPQFGy805D_KjZ--xrcjWUzJOZ_1D_ltY9QY
user:
id: admin_UkLWZg9DAJ
- first_name: Jenniffer
- last_name: Daugherty
- full_name: Jenniffer Daugherty
- created_at: '2026-06-14T21:16:54.024Z'
- updated_at: '2026-06-14T21:16:54.024Z'
+ first_name: Viola
+ last_name: Smith
+ full_name: Viola Smith
+ created_at: '2026-06-15T11:57:04.561Z'
+ updated_at: '2026-06-15T11:57:04.561Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -303,12 +303,12 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Man
- last_name: Satterfield
- full_name: Man Satterfield
- created_at: '2026-06-14T21:17:26.399Z'
- updated_at: '2026-06-14T21:17:26.399Z'
+ first_name: Carleen
+ last_name: Sporer
+ full_name: Carleen Sporer
+ created_at: '2026-06-15T11:57:36.032Z'
+ updated_at: '2026-06-15T11:57:36.032Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -459,8 +459,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-06-14T21:16:48.641Z'
- updated_at: '2026-06-14T21:16:48.641Z'
+ created_at: '2026-06-15T11:56:59.141Z'
+ updated_at: '2026-06-15T11:56:59.141Z'
meta:
page: 1
limit: 25
@@ -544,8 +544,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-06-14T21:16:49.237Z'
- updated_at: '2026-06-14T21:16:49.237Z'
+ created_at: '2026-06-15T11:56:59.745Z'
+ updated_at: '2026-06-15T11:56:59.745Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -632,8 +632,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-06-14T21:16:49.529Z'
- updated_at: '2026-06-14T21:16:49.529Z'
+ created_at: '2026-06-15T11:57:00.036Z'
+ updated_at: '2026-06-15T11:57:00.036Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -694,8 +694,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-06-14T21:16:50.097Z'
- updated_at: '2026-06-14T21:16:50.375Z'
+ created_at: '2026-06-15T11:57:00.644Z'
+ updated_at: '2026-06-15T11:57:00.924Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -815,32 +815,32 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-06-14T21:16:50.964Z'
- updated_at: '2026-06-14T21:16:50.964Z'
+ created_at: '2026-06-15T11:57:01.525Z'
+ updated_at: '2026-06-15T11:57:01.525Z'
revoked_at:
last_used_at:
- plaintext_token: pk_ByqDU3aTd2gNjbTLvuzr4HvY
+ plaintext_token: pk_yts1HG5UBaAgv7hM1J45vvcE
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_EyoR582ih
+ token_prefix: sk_dv3AfZzyx
scopes:
- write_all
- created_at: '2026-06-14T21:16:50.965Z'
- updated_at: '2026-06-14T21:16:50.965Z'
+ created_at: '2026-06-15T11:57:01.527Z'
+ updated_at: '2026-06-15T11:57:01.527Z'
revoked_at:
last_used_at:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: impedit
+ name: ex
key_type: secret
- token_prefix: sk_EKeAhhkTY
+ token_prefix: sk_sVCmCwNgW
scopes:
- write_all
- created_at: '2026-06-14T21:16:50.966Z'
- updated_at: '2026-06-14T21:16:50.966Z'
+ created_at: '2026-06-15T11:57:01.528Z'
+ updated_at: '2026-06-15T11:57:01.528Z'
revoked_at:
last_used_at:
plaintext_token:
@@ -906,15 +906,15 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_And9ziQvP
+ token_prefix: sk_xGxYd1cLS
scopes:
- read_orders
- created_at: '2026-06-14T21:16:51.533Z'
- updated_at: '2026-06-14T21:16:51.533Z'
+ created_at: '2026-06-15T11:57:02.086Z'
+ updated_at: '2026-06-15T11:57:02.086Z'
revoked_at:
last_used_at:
- plaintext_token: sk_And9ziQvPHLxQiaKUq8kJQN6
- created_by_email: [email protected]
+ plaintext_token: sk_xGxYd1cLSghRccW3XGWq2aJ2
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -1003,11 +1003,11 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-06-14T21:16:51.823Z'
- updated_at: '2026-06-14T21:16:51.823Z'
+ created_at: '2026-06-15T11:57:02.370Z'
+ updated_at: '2026-06-15T11:57:02.370Z'
revoked_at:
last_used_at:
- plaintext_token: pk_HPo3wsbdbtew8fjPNybA6erB
+ plaintext_token: pk_T3bgEwM4CPEwPQMWV3qq7x58
created_by_email:
delete:
summary: Delete an API key
@@ -1103,12 +1103,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_wT8M2KqQ8
+ token_prefix: sk_qULApbyvA
scopes:
- write_all
- created_at: '2026-06-14T21:16:52.387Z'
- updated_at: '2026-06-14T21:16:52.663Z'
- revoked_at: '2026-06-14T21:16:52.662Z'
+ created_at: '2026-06-15T11:57:02.934Z'
+ updated_at: '2026-06-15T11:57:03.209Z'
+ revoked_at: '2026-06-15T11:57:03.207Z'
last_used_at:
plaintext_token:
created_by_email:
@@ -1173,16 +1173,16 @@ paths:
active: true
default: true
preferred_order_routing_strategy:
- created_at: '2026-06-14T21:16:47.345Z'
- updated_at: '2026-06-14T21:16:47.345Z'
+ created_at: '2026-06-15T11:56:57.671Z'
+ updated_at: '2026-06-15T11:56:57.671Z'
- id: ch_gbHJdmfrXB
name: Wholesale
code: wholesale
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-14T21:16:54.631Z'
- updated_at: '2026-06-14T21:16:54.631Z'
+ created_at: '2026-06-15T11:57:05.155Z'
+ updated_at: '2026-06-15T11:57:05.155Z'
meta:
page: 1
limit: 25
@@ -1263,8 +1263,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-14T21:16:55.214Z'
- updated_at: '2026-06-14T21:16:55.214Z'
+ created_at: '2026-06-15T11:57:05.733Z'
+ updated_at: '2026-06-15T11:57:05.733Z'
requestBody:
content:
application/json:
@@ -1336,8 +1336,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-14T21:16:55.227Z'
- updated_at: '2026-06-14T21:16:55.227Z'
+ created_at: '2026-06-15T11:57:05.742Z'
+ updated_at: '2026-06-15T11:57:05.742Z'
patch:
summary: Update a channel
tags:
@@ -1387,8 +1387,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-14T21:16:55.517Z'
- updated_at: '2026-06-14T21:16:55.799Z'
+ created_at: '2026-06-15T11:57:06.033Z'
+ updated_at: '2026-06-15T11:57:06.351Z'
requestBody:
content:
application/json:
@@ -1663,8 +1663,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-14T21:16:57.152Z'
- updated_at: '2026-06-14T21:16:57.152Z'
+ created_at: '2026-06-15T11:57:07.675Z'
+ updated_at: '2026-06-15T11:57:07.675Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -1672,8 +1672,8 @@ paths:
field_type: short_text
resource_type: Spree::Order
storefront_visible: true
- created_at: '2026-06-14T21:16:57.153Z'
- updated_at: '2026-06-14T21:16:57.153Z'
+ created_at: '2026-06-15T11:57:07.676Z'
+ updated_at: '2026-06-15T11:57:07.676Z'
meta:
page: 1
limit: 25
@@ -1739,8 +1739,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-14T21:16:57.715Z'
- updated_at: '2026-06-14T21:16:57.715Z'
+ created_at: '2026-06-15T11:57:08.229Z'
+ updated_at: '2026-06-15T11:57:08.229Z'
requestBody:
content:
application/json:
@@ -1837,8 +1837,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-14T21:16:57.719Z'
- updated_at: '2026-06-14T21:16:57.719Z'
+ created_at: '2026-06-15T11:57:08.233Z'
+ updated_at: '2026-06-15T11:57:08.233Z'
patch:
summary: Update a custom field definition
tags:
@@ -1895,8 +1895,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: false
- created_at: '2026-06-14T21:16:58.001Z'
- updated_at: '2026-06-14T21:16:58.278Z'
+ created_at: '2026-06-15T11:57:08.512Z'
+ updated_at: '2026-06-15T11:57:08.791Z'
requestBody:
content:
application/json:
@@ -2038,14 +2038,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-06-14T21:16:58.570Z'
- updated_at: '2026-06-14T21:16:58.570Z'
+ created_at: '2026-06-15T11:57:09.128Z'
+ updated_at: '2026-06-15T11:57:09.128Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-06-14T21:16:58.571Z'
- updated_at: '2026-06-14T21:16:58.571Z'
+ created_at: '2026-06-15T11:57:09.129Z'
+ updated_at: '2026-06-15T11:57:09.129Z'
meta:
page: 1
limit: 25
@@ -2134,8 +2134,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-06-14T21:16:59.449Z'
- updated_at: '2026-06-14T21:16:59.449Z'
+ created_at: '2026-06-15T11:57:09.982Z'
+ updated_at: '2026-06-15T11:57:09.982Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -2244,24 +2244,24 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-06-14T21:17:00.030Z'
- updated_at: '2026-06-14T21:17:00.030Z'
+ created_at: '2026-06-15T11:57:10.554Z'
+ updated_at: '2026-06-15T11:57:10.554Z'
customers:
- id: cus_UkLWZg9DAJ
- first_name: Kory
- last_name: Kertzmann
+ first_name: Karisa
+ last_name: Monahan
phone:
accepts_email_marketing: false
- full_name: Kory Kertzmann
+ full_name: Karisa Monahan
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-14T21:17:00.291Z'
- updated_at: '2026-06-14T21:17:00.291Z'
+ created_at: '2026-06-15T11:57:10.815Z'
+ updated_at: '2026-06-15T11:57:10.815Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -2342,8 +2342,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-06-14T21:17:00.882Z'
- updated_at: '2026-06-14T21:17:01.902Z'
+ created_at: '2026-06-15T11:57:11.412Z'
+ updated_at: '2026-06-15T11:57:11.690Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -2502,8 +2502,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-06-14T21:17:02.749Z'
- updated_at: '2026-06-14T21:17:02.749Z'
+ created_at: '2026-06-15T11:57:12.566Z'
+ updated_at: '2026-06-15T11:57:12.566Z'
customer_id: cus_UkLWZg9DAJ
meta:
page: 1
@@ -2596,8 +2596,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-06-14T21:17:04.131Z'
- updated_at: '2026-06-14T21:17:04.131Z'
+ created_at: '2026-06-15T11:57:13.947Z'
+ updated_at: '2026-06-15T11:57:13.947Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -2711,8 +2711,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-06-14T21:17:04.412Z'
- updated_at: '2026-06-14T21:17:04.985Z'
+ created_at: '2026-06-15T11:57:14.216Z'
+ updated_at: '2026-06-15T11:57:14.754Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -2851,8 +2851,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-06-14T21:17:06.091Z'
- updated_at: '2026-06-14T21:17:06.091Z'
+ created_at: '2026-06-15T11:57:15.845Z'
+ updated_at: '2026-06-15T11:57:15.845Z'
meta:
page: 1
limit: 25
@@ -2942,8 +2942,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-06-14T21:17:06.689Z'
- updated_at: '2026-06-14T21:17:06.689Z'
+ created_at: '2026-06-15T11:57:16.402Z'
+ updated_at: '2026-06-15T11:57:16.402Z'
delete:
summary: Delete a customer credit card
tags:
@@ -3068,8 +3068,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-06-14T21:17:08.067Z'
- updated_at: '2026-06-14T21:17:08.067Z'
+ created_at: '2026-06-15T11:57:17.763Z'
+ updated_at: '2026-06-15T11:57:17.763Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -3148,8 +3148,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-06-14T21:17:09.169Z'
- updated_at: '2026-06-14T21:17:09.169Z'
+ created_at: '2026-06-15T11:57:18.850Z'
+ updated_at: '2026-06-15T11:57:18.850Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -3244,8 +3244,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-06-14T21:17:09.711Z'
- updated_at: '2026-06-14T21:17:09.990Z'
+ created_at: '2026-06-15T11:57:19.457Z'
+ updated_at: '2026-06-15T11:57:19.745Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -3405,8 +3405,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-14T21:17:11.184Z'
- updated_at: '2026-06-14T21:17:11.184Z'
+ created_at: '2026-06-15T11:57:20.863Z'
+ updated_at: '2026-06-15T11:57:20.863Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3493,8 +3493,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-14T21:17:12.015Z'
- updated_at: '2026-06-14T21:17:12.015Z'
+ created_at: '2026-06-15T11:57:21.714Z'
+ updated_at: '2026-06-15T11:57:21.714Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3613,8 +3613,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-14T21:17:12.284Z'
- updated_at: '2026-06-14T21:17:12.284Z'
+ created_at: '2026-06-15T11:57:21.987Z'
+ updated_at: '2026-06-15T11:57:21.987Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3691,8 +3691,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-14T21:17:12.834Z'
- updated_at: '2026-06-14T21:17:13.113Z'
+ created_at: '2026-06-15T11:57:22.536Z'
+ updated_at: '2026-06-15T11:57:22.814Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -4140,11 +4140,11 @@ paths:
example:
data:
- id: exp_UkLWZg9DAJ
- number: EF386620345
+ number: EF522648329
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-14T21:17:17.271Z'
- updated_at: '2026-06-14T21:17:17.271Z'
+ created_at: '2026-06-15T11:57:26.972Z'
+ updated_at: '2026-06-15T11:57:26.972Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4214,11 +4214,11 @@ paths:
application/json:
example:
id: exp_gbHJdmfrXB
- number: EF726918471
+ number: EF246717684
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-14T21:17:17.569Z'
- updated_at: '2026-06-14T21:17:17.569Z'
+ created_at: '2026-06-15T11:57:27.265Z'
+ updated_at: '2026-06-15T11:57:27.265Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4308,11 +4308,11 @@ paths:
application/json:
example:
id: exp_UkLWZg9DAJ
- number: EF017397569
+ number: EF364331730
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-14T21:17:17.839Z'
- updated_at: '2026-06-14T21:17:17.839Z'
+ created_at: '2026-06-15T11:57:27.537Z'
+ updated_at: '2026-06-15T11:57:27.537Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4494,7 +4494,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H13412945093
+ number: H12389981685
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4519,8 +4519,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:29.182Z'
- updated_at: '2026-06-14T21:17:29.261Z'
+ created_at: '2026-06-15T11:57:38.676Z'
+ updated_at: '2026-06-15T11:57:38.777Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -4606,7 +4606,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H02766075096
+ number: H05305220918
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4631,8 +4631,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:29.888Z'
- updated_at: '2026-06-14T21:17:29.947Z'
+ created_at: '2026-06-15T11:57:39.461Z'
+ updated_at: '2026-06-15T11:57:39.522Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -4694,7 +4694,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H34796454043
+ number: H99994265576
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -4719,8 +4719,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:30.545Z'
- updated_at: '2026-06-14T21:17:30.889Z'
+ created_at: '2026-06-15T11:57:40.125Z'
+ updated_at: '2026-06-15T11:57:40.462Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -4793,7 +4793,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H92178779518
+ number: H03474791134
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4810,7 +4810,7 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-06-14T21:17:31Z'
+ fulfilled_at: '2026-06-15T11:57:41Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -4818,8 +4818,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:31.203Z'
- updated_at: '2026-06-14T21:17:31.567Z'
+ created_at: '2026-06-15T11:57:40.798Z'
+ updated_at: '2026-06-15T11:57:41.154Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -4881,7 +4881,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H77092167457
+ number: H95909381827
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4906,8 +4906,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:31.890Z'
- updated_at: '2026-06-14T21:17:32.230Z'
+ created_at: '2026-06-15T11:57:41.477Z'
+ updated_at: '2026-06-15T11:57:41.822Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -4969,7 +4969,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H20159845023
+ number: H73230663693
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4994,8 +4994,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:32.561Z'
- updated_at: '2026-06-14T21:17:32.909Z'
+ created_at: '2026-06-15T11:57:42.158Z'
+ updated_at: '2026-06-15T11:57:42.546Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -5059,7 +5059,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H93541000106
+ number: H54098251113
tracking:
tracking_url:
cost: '10.0'
@@ -5084,8 +5084,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-14T21:17:33.608Z'
- updated_at: '2026-06-14T21:17:33.655Z'
+ created_at: '2026-06-15T11:57:43.274Z'
+ updated_at: '2026-06-15T11:57:43.315Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -5184,8 +5184,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-06-14T21:17:18.432Z'
- updated_at: '2026-06-14T21:17:18.432Z'
+ created_at: '2026-06-15T11:57:28.126Z'
+ updated_at: '2026-06-15T11:57:28.126Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -5269,8 +5269,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-06-14T21:17:19.002Z'
- updated_at: '2026-06-14T21:17:19.002Z'
+ created_at: '2026-06-15T11:57:28.686Z'
+ updated_at: '2026-06-15T11:57:28.686Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: admin_UkLWZg9DAJ
@@ -5374,8 +5374,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-06-14T21:17:19.301Z'
- updated_at: '2026-06-14T21:17:19.301Z'
+ created_at: '2026-06-15T11:57:28.979Z'
+ updated_at: '2026-06-15T11:57:28.979Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -5481,7 +5481,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 2A4B16B393D30934
+ code: AE316E5240A8ACD2
status: active
currency: USD
amount: '50.0'
@@ -5495,12 +5495,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-14T21:17:19.875Z'
- updated_at: '2026-06-14T21:17:19.875Z'
+ created_at: '2026-06-15T11:57:29.558Z'
+ updated_at: '2026-06-15T11:57:29.558Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: 7C597B527F654B4B
+ code: 2FF2A3946F2A95FA
status: active
currency: USD
amount: '25.0'
@@ -5514,8 +5514,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-14T21:17:19.876Z'
- updated_at: '2026-06-14T21:17:19.876Z'
+ created_at: '2026-06-15T11:57:29.559Z'
+ updated_at: '2026-06-15T11:57:29.559Z'
customer_id:
created_by_id:
meta:
@@ -5603,7 +5603,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: 19065E503D86B00D
+ code: B938286342B73105
status: active
currency: USD
amount: '25.0'
@@ -5617,8 +5617,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-14T21:17:20.455Z'
- updated_at: '2026-06-14T21:17:20.455Z'
+ created_at: '2026-06-15T11:57:30.146Z'
+ updated_at: '2026-06-15T11:57:30.146Z'
customer_id:
created_by_id: admin_UkLWZg9DAJ
schema:
@@ -5727,7 +5727,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: E962859FAD392F60
+ code: CBDF26436179F1AC
status: active
currency: USD
amount: '50.0'
@@ -5741,8 +5741,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-14T21:17:20.760Z'
- updated_at: '2026-06-14T21:17:20.760Z'
+ created_at: '2026-06-15T11:57:30.438Z'
+ updated_at: '2026-06-15T11:57:30.438Z'
customer_id:
created_by_id:
schema:
@@ -5805,7 +5805,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 7CD60076E592B5E7
+ code: 79D519CED5F09652
status: active
currency: USD
amount: '75.0'
@@ -5819,8 +5819,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-14T21:17:21.337Z'
- updated_at: '2026-06-14T21:17:21.616Z'
+ created_at: '2026-06-15T11:57:30.999Z'
+ updated_at: '2026-06-15T11:57:31.278Z'
customer_id:
created_by_id:
schema:
@@ -5976,8 +5976,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-14T21:17:23.369Z'
- updated_at: '2026-06-14T21:17:23.369Z'
+ created_at: '2026-06-15T11:57:33.013Z'
+ updated_at: '2026-06-15T11:57:33.013Z'
meta:
page: 1
limit: 25
@@ -6070,8 +6070,8 @@ paths:
supported_locales:
- en
- fr
- created_at: '2026-06-14T21:17:23.956Z'
- updated_at: '2026-06-14T21:17:23.956Z'
+ created_at: '2026-06-15T11:57:33.643Z'
+ updated_at: '2026-06-15T11:57:33.643Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -6207,8 +6207,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-14T21:17:24.294Z'
- updated_at: '2026-06-14T21:17:24.294Z'
+ created_at: '2026-06-15T11:57:33.968Z'
+ updated_at: '2026-06-15T11:57:33.968Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -6287,8 +6287,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-14T21:17:24.909Z'
- updated_at: '2026-06-14T21:17:25.191Z'
+ created_at: '2026-06-15T11:57:34.587Z'
+ updated_at: '2026-06-15T11:57:34.866Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -6468,8 +6468,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-14T21:17:26.515Z'
- updated_at: '2026-06-14T21:17:26.515Z'
+ created_at: '2026-06-15T11:57:36.082Z'
+ updated_at: '2026-06-15T11:57:36.082Z'
meta:
page: 1
limit: 25
@@ -6563,8 +6563,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-14T21:17:27.130Z'
- updated_at: '2026-06-14T21:17:27.130Z'
+ created_at: '2026-06-15T11:57:36.663Z'
+ updated_at: '2026-06-15T11:57:36.663Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -6688,8 +6688,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-14T21:17:27.422Z'
- updated_at: '2026-06-14T21:17:27.422Z'
+ created_at: '2026-06-15T11:57:36.951Z'
+ updated_at: '2026-06-15T11:57:36.951Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -6762,8 +6762,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-14T21:17:27.990Z'
- updated_at: '2026-06-14T21:17:28.267Z'
+ created_at: '2026-06-15T11:57:37.513Z'
+ updated_at: '2026-06-15T11:57:37.787Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -6914,7 +6914,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: F93A9F82E32BC612
+ code: 056B495CBD84460D
status: active
currency: USD
amount: '10.0'
@@ -6928,8 +6928,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-14T21:17:34.051Z'
- updated_at: '2026-06-14T21:17:34.381Z'
+ created_at: '2026-06-15T11:57:43.653Z'
+ updated_at: '2026-06-15T11:57:43.980Z'
customer_id:
created_by_id:
requestBody:
@@ -7068,8 +7068,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 123060
- slug: product-123060
+ name: Product 121823
+ slug: product-121823
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -7101,12 +7101,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:17:35.098Z'
- updated_at: '2026-06-14T21:17:35.098Z'
+ created_at: '2026-06-15T11:57:44.674Z'
+ updated_at: '2026-06-15T11:57:44.674Z'
digital_links: []
metadata: {}
- created_at: '2026-06-14T21:17:35.382Z'
- updated_at: '2026-06-14T21:17:35.382Z'
+ created_at: '2026-06-15T11:57:44.960Z'
+ updated_at: '2026-06-15T11:57:44.960Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -7176,8 +7176,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 145013
- slug: product-145013
+ name: Product 145166
+ slug: product-145166
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -7209,12 +7209,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:17:36.299Z'
- updated_at: '2026-06-14T21:17:36.299Z'
+ created_at: '2026-06-15T11:57:45.889Z'
+ updated_at: '2026-06-15T11:57:45.889Z'
digital_links: []
metadata: {}
- created_at: '2026-06-14T21:17:36.327Z'
- updated_at: '2026-06-14T21:17:36.327Z'
+ created_at: '2026-06-15T11:57:45.925Z'
+ updated_at: '2026-06-15T11:57:45.925Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -7306,8 +7306,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 158983
- slug: product-158983
+ name: Product 157539
+ slug: product-157539
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -7339,12 +7339,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:17:36.397Z'
- updated_at: '2026-06-14T21:17:36.397Z'
+ created_at: '2026-06-15T11:57:46.016Z'
+ updated_at: '2026-06-15T11:57:46.016Z'
digital_links: []
metadata: {}
- created_at: '2026-06-14T21:17:36.726Z'
- updated_at: '2026-06-14T21:17:36.726Z'
+ created_at: '2026-06-15T11:57:46.311Z'
+ updated_at: '2026-06-15T11:57:46.311Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -7409,8 +7409,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 167629
- slug: product-167629
+ name: Product 16548
+ slug: product-16548
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -7442,12 +7442,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:17:37.059Z'
- updated_at: '2026-06-14T21:17:37.059Z'
+ created_at: '2026-06-15T11:57:46.654Z'
+ updated_at: '2026-06-15T11:57:46.654Z'
digital_links: []
metadata: {}
- created_at: '2026-06-14T21:17:37.342Z'
- updated_at: '2026-06-14T21:17:37.637Z'
+ created_at: '2026-06-15T11:57:46.971Z'
+ updated_at: '2026-06-15T11:57:47.344Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -7567,8 +7567,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R922536541
+ number: R437407505
customer_note:
currency: USD
locale: en
@@ -7611,8 +7611,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:44.496Z'
- updated_at: '2026-06-14T21:17:44.564Z'
+ created_at: '2026-06-15T11:57:54.376Z'
+ updated_at: '2026-06-15T11:57:54.432Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -7789,8 +7789,8 @@ paths:
- id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R427814673
+ number: R939826144
customer_note:
currency: USD
locale: en
@@ -7833,8 +7833,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:46.318Z'
- updated_at: '2026-06-14T21:17:46.318Z'
+ created_at: '2026-06-15T11:57:56.161Z'
+ updated_at: '2026-06-15T11:57:56.161Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -7985,7 +7985,7 @@ paths:
id: or_gbHJdmfrXB
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R964626740
+ number: R742415841
customer_note:
currency: USD
@@ -8029,8 +8029,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:48.033Z'
- updated_at: '2026-06-14T21:17:48.036Z'
+ created_at: '2026-06-15T11:57:57.843Z'
+ updated_at: '2026-06-15T11:57:57.846Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
tags: []
internal_note:
@@ -8217,8 +8217,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R830716695
+ number: R084617541
customer_note:
currency: USD
locale: en
@@ -8261,8 +8261,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:48.312Z'
- updated_at: '2026-06-14T21:17:48.312Z'
+ created_at: '2026-06-15T11:57:58.122Z'
+ updated_at: '2026-06-15T11:57:58.122Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8337,7 +8337,7 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R655667539
+ number: R591008734
customer_note:
currency: USD
@@ -8381,8 +8381,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:49.433Z'
- updated_at: '2026-06-14T21:17:49.727Z'
+ created_at: '2026-06-15T11:57:59.274Z'
+ updated_at: '2026-06-15T11:57:59.565Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8569,8 +8569,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R579397150
+ number: R027445451
customer_note:
currency: USD
locale: en
@@ -8597,7 +8597,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-06-14T21:17:50.641Z'
+ completed_at: '2026-06-15T11:58:00.460Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8613,8 +8613,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:50.586Z'
- updated_at: '2026-06-14T21:17:50.667Z'
+ created_at: '2026-06-15T11:58:00.408Z'
+ updated_at: '2026-06-15T11:58:00.484Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8698,8 +8698,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R188114055
+ number: R182455510
customer_note:
currency: USD
locale: en
@@ -8726,7 +8726,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-06-14T21:17:51.900Z'
+ completed_at: '2026-06-15T11:58:01.811Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8740,10 +8740,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-06-14T21:17:52.187Z'
+ canceled_at: '2026-06-15T11:58:02.098Z'
approved_at:
- created_at: '2026-06-14T21:17:51.848Z'
- updated_at: '2026-06-14T21:17:52.244Z'
+ created_at: '2026-06-15T11:58:01.758Z'
+ updated_at: '2026-06-15T11:58:02.134Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8805,8 +8805,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R169505496
+ number: R938240100
customer_note:
currency: USD
locale: en
@@ -8833,7 +8833,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-06-14T21:17:52.604Z'
+ completed_at: '2026-06-15T11:58:02.478Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8848,9 +8848,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-06-14T21:17:52.895Z'
- created_at: '2026-06-14T21:17:52.548Z'
- updated_at: '2026-06-14T21:17:52.603Z'
+ approved_at: '2026-06-15T11:58:02.765Z'
+ created_at: '2026-06-15T11:58:02.430Z'
+ updated_at: '2026-06-15T11:58:02.478Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8912,8 +8912,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R667641367
+ number: R832897984
customer_note:
currency: USD
locale: en
@@ -8940,7 +8940,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-06-14T21:17:53.235Z'
+ completed_at: '2026-06-15T11:58:03.094Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8954,10 +8954,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-06-14T21:17:53.514Z'
+ canceled_at: '2026-06-15T11:58:03.377Z'
approved_at:
- created_at: '2026-06-14T21:17:53.180Z'
- updated_at: '2026-06-14T21:17:53.671Z'
+ created_at: '2026-06-15T11:58:03.047Z'
+ updated_at: '2026-06-15T11:58:03.459Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -9019,8 +9019,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R503477345
+ number: R499414291
customer_note:
currency: USD
locale: en
@@ -9047,7 +9047,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-06-14T21:17:54.046Z'
+ completed_at: '2026-06-15T11:58:03.794Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -9063,8 +9063,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-14T21:17:53.975Z'
- updated_at: '2026-06-14T21:17:54.045Z'
+ created_at: '2026-06-15T11:58:03.741Z'
+ updated_at: '2026-06-15T11:58:03.793Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -9142,8 +9142,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-06-14T21:17:54.352Z'
- updated_at: '2026-06-14T21:17:54.353Z'
+ created_at: '2026-06-15T11:58:04.094Z'
+ updated_at: '2026-06-15T11:58:04.095Z'
preferences: {}
preference_schema: []
meta:
@@ -9205,12 +9205,12 @@ paths:
label: Bogus
description:
preference_schema:
- - key: dummy_secret_key
- type: password
- default:
- key: dummy_key
type: string
default: PUBLICKEY123
+ - key: dummy_secret_key
+ type: password
+ default:
- type: custom_payment_source_method
label: Custom Payment Source Method
description:
@@ -9289,8 +9289,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-06-14T21:17:54.943Z'
- updated_at: '2026-06-14T21:17:54.944Z'
+ created_at: '2026-06-15T11:58:04.673Z'
+ updated_at: '2026-06-15T11:58:04.674Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -9361,8 +9361,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-c7a682f9372a
- number: PRSJFMUG
+ response_code: BGS-cb609acb7159
+ number: P5FMWXUR
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9380,14 +9380,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-14T21:17:38.624Z'
- updated_at: '2026-06-14T21:17:38.627Z'
+ created_at: '2026-06-15T11:57:48.473Z'
+ updated_at: '2026-06-15T11:57:48.476Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-14T21:17:38.626Z'
- updated_at: '2026-06-14T21:17:38.626Z'
+ created_at: '2026-06-15T11:57:48.475Z'
+ updated_at: '2026-06-15T11:57:48.475Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -9457,7 +9457,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: P1U2NKAZ
+ number: PRACICOR
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -9468,8 +9468,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-14T21:17:39.958Z'
- updated_at: '2026-06-14T21:17:39.958Z'
+ created_at: '2026-06-15T11:57:49.833Z'
+ updated_at: '2026-06-15T11:57:49.833Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -9562,8 +9562,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-7e4d0a847f3e
- number: PSD5RBQV
+ response_code: BGS-ca8018bf4009
+ number: PBQAPADY
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9581,14 +9581,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-14T21:17:40.341Z'
- updated_at: '2026-06-14T21:17:40.344Z'
+ created_at: '2026-06-15T11:57:50.209Z'
+ updated_at: '2026-06-15T11:57:50.212Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-14T21:17:40.343Z'
- updated_at: '2026-06-14T21:17:40.343Z'
+ created_at: '2026-06-15T11:57:50.211Z'
+ updated_at: '2026-06-15T11:57:50.211Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -9651,8 +9651,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-858e0cb8544e
- number: P7K3XMX6
+ response_code: BGS-c61490927e3f
+ number: P61XR5WJ
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9670,14 +9670,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-14T21:17:41.047Z'
- updated_at: '2026-06-14T21:17:41.050Z'
+ created_at: '2026-06-15T11:57:50.860Z'
+ updated_at: '2026-06-15T11:57:50.863Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-14T21:17:41.049Z'
- updated_at: '2026-06-14T21:17:41.385Z'
+ created_at: '2026-06-15T11:57:50.862Z'
+ updated_at: '2026-06-15T11:57:51.179Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -9749,8 +9749,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-488e4011c88f
- number: PVCNBH41
+ response_code: void-BGS-6c9f322bfbc4
+ number: PPN8XNXH
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -9768,14 +9768,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-14T21:17:42.562Z'
- updated_at: '2026-06-14T21:17:42.566Z'
+ created_at: '2026-06-15T11:57:52.447Z'
+ updated_at: '2026-06-15T11:57:52.449Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-14T21:17:42.564Z'
- updated_at: '2026-06-14T21:17:42.868Z'
+ created_at: '2026-06-15T11:57:52.448Z'
+ updated_at: '2026-06-15T11:57:52.748Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -9863,8 +9863,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:55.231Z'
- updated_at: '2026-06-14T21:17:55.231Z'
+ created_at: '2026-06-15T11:58:04.955Z'
+ updated_at: '2026-06-15T11:58:04.955Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9878,8 +9878,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:55.232Z'
- updated_at: '2026-06-14T21:17:55.232Z'
+ created_at: '2026-06-15T11:58:04.956Z'
+ updated_at: '2026-06-15T11:58:04.956Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9993,8 +9993,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:56.201Z'
- updated_at: '2026-06-14T21:17:56.203Z'
+ created_at: '2026-06-15T11:58:05.927Z'
+ updated_at: '2026-06-15T11:58:05.929Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -10157,8 +10157,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:56.563Z'
- updated_at: '2026-06-14T21:17:56.563Z'
+ created_at: '2026-06-15T11:58:06.224Z'
+ updated_at: '2026-06-15T11:58:06.224Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10233,8 +10233,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:58.119Z'
- updated_at: '2026-06-14T21:17:58.396Z'
+ created_at: '2026-06-15T11:58:07.771Z'
+ updated_at: '2026-06-15T11:58:08.046Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10422,8 +10422,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:58.707Z'
- updated_at: '2026-06-14T21:17:58.989Z'
+ created_at: '2026-06-15T11:58:08.336Z'
+ updated_at: '2026-06-15T11:58:08.611Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -10486,8 +10486,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-14T21:17:59.001Z'
- updated_at: '2026-06-14T21:17:59.284Z'
+ created_at: '2026-06-15T11:58:08.619Z'
+ updated_at: '2026-06-15T11:58:08.905Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10601,8 +10601,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-14T21:17:59.338Z'
- updated_at: '2026-06-14T21:17:59.338Z'
+ created_at: '2026-06-15T11:58:08.961Z'
+ updated_at: '2026-06-15T11:58:08.961Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -10613,8 +10613,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-14T21:17:59.342Z'
- updated_at: '2026-06-14T21:17:59.342Z'
+ created_at: '2026-06-15T11:58:08.965Z'
+ updated_at: '2026-06-15T11:58:08.965Z'
meta:
page: 1
limit: 25
@@ -10696,8 +10696,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-06-14T21:17:59.993Z'
- updated_at: '2026-06-14T21:17:59.993Z'
+ created_at: '2026-06-15T11:58:09.620Z'
+ updated_at: '2026-06-15T11:58:09.620Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -10784,8 +10784,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-14T21:18:00.057Z'
- updated_at: '2026-06-14T21:18:00.057Z'
+ created_at: '2026-06-15T11:58:09.692Z'
+ updated_at: '2026-06-15T11:58:09.692Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -10850,8 +10850,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-14T21:18:00.744Z'
- updated_at: '2026-06-14T21:18:01.021Z'
+ created_at: '2026-06-15T11:58:10.370Z'
+ updated_at: '2026-06-15T11:58:10.647Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -11163,8 +11163,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-06-14T21:18:02.553Z'
- updated_at: '2026-06-14T21:18:02.553Z'
+ created_at: '2026-06-15T11:58:12.051Z'
+ updated_at: '2026-06-15T11:58:12.051Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -11234,8 +11234,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-06-14T21:18:03.159Z'
- updated_at: '2026-06-14T21:18:03.159Z'
+ created_at: '2026-06-15T11:58:12.643Z'
+ updated_at: '2026-06-15T11:58:12.643Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -11334,8 +11334,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-06-14T21:18:03.508Z'
- updated_at: '2026-06-14T21:18:03.508Z'
+ created_at: '2026-06-15T11:58:13.000Z'
+ updated_at: '2026-06-15T11:58:13.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -11399,8 +11399,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-06-14T21:18:03.825Z'
- updated_at: '2026-06-14T21:18:04.115Z'
+ created_at: '2026-06-15T11:58:13.310Z'
+ updated_at: '2026-06-15T11:58:13.585Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -11556,8 +11556,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 571567
- slug: product-571567
+ name: Product 574324
+ slug: product-574324
meta_title:
meta_description:
meta_keywords:
@@ -11567,28 +11567,29 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Explicabo consectetur natus quia doloremque. Incidunt
- distinctio iure architecto amet. Facilis asperiores sunt iure
- et a. Quos delectus fuga ipsa autem. Sapiente nulla dolore repellat
- qui occaecati officiis. Reiciendis tempora eius officia itaque
- eaque ullam vero. Cumque eius odit ipsam quo. Totam minus magni
- a sint at dignissimos ea eaque. Laudantium cumque velit consectetur
- sequi enim. Eveniet mollitia ipsam repellendus dignissimos accusamus
- soluta reiciendis provident. Porro quaerat ex magnam harum dolorem
- illum. Qui dolore velit unde provident asperiores. Dolore maiores
- debitis facere voluptatibus eveniet repudiandae. Atque exercitationem
- adipisci enim veniam saepe voluptate quod voluptatum. Quo suscipit
- adipisci dignissimos voluptas totam. Aliquid porro ipsum esse
- dolores. Explicabo deleniti ratione ea accusamus commodi iste.
- Reiciendis non aperiam quasi ex doloremque. Repudiandae tenetur
- deserunt ipsam soluta corporis. Ipsa eligendi asperiores odit
- autem explicabo.
+ description: Aut provident aliquam mollitia non. Placeat sunt maxime
+ in tenetur eius sed sapiente excepturi. Esse beatae architecto
+ ad fuga ipsam similique consectetur adipisci. Modi consequuntur
+ rem illum accusamus. Voluptas voluptates voluptatem pariatur mollitia
+ labore sint blanditiis. Rerum sapiente hic cumque nihil consectetur
+ magnam. Facere fugiat minima explicabo quos illum. Aliquid impedit
+ illum fugiat quam. Ad beatae perspiciatis perferendis nobis iure
+ non dolore vero. Laudantium nesciunt laborum fuga aliquid recusandae.
+ Itaque sint sequi enim nesciunt earum. Cumque nemo labore quibusdam
+ deleniti distinctio ducimus necessitatibus. Aliquid qui suscipit
+ officiis molestias officia dolorem. Reiciendis eligendi error
+ beatae fugit ipsum. Autem rem et nobis necessitatibus. Laboriosam
+ itaque cum aliquid laudantium ullam in. Repellendus similique
+ ullam facere quis. Ut quasi harum repudiandae consequuntur. Minus
+ provident voluptates nemo labore fuga. Atque incidunt harum minus
+ voluptatem voluptatum eveniet. Id assumenda pariatur minus sit
+ ad ab. Iste inventore quidem sed quibusdam.
description_html: |-
- Explicabo consectetur natus quia doloremque. Incidunt distinctio iure architecto amet. Facilis asperiores sunt iure et a. Quos delectus fuga ipsa autem.
- Sapiente nulla dolore repellat qui occaecati officiis. Reiciendis tempora eius officia itaque eaque ullam vero. Cumque eius odit ipsam quo. Totam minus magni a sint at dignissimos ea eaque.
- Laudantium cumque velit consectetur sequi enim. Eveniet mollitia ipsam repellendus dignissimos accusamus soluta reiciendis provident. Porro quaerat ex magnam harum dolorem illum. Qui dolore velit unde provident asperiores.
- Dolore maiores debitis facere voluptatibus eveniet repudiandae. Atque exercitationem adipisci enim veniam saepe voluptate quod voluptatum. Quo suscipit adipisci dignissimos voluptas totam.
- Aliquid porro ipsum esse dolores. Explicabo deleniti ratione ea accusamus commodi iste. Reiciendis non aperiam quasi ex doloremque. Repudiandae tenetur deserunt ipsam soluta corporis. Ipsa eligendi asperiores odit autem explicabo.
+ Aut provident aliquam mollitia non. Placeat sunt maxime in tenetur eius sed sapiente excepturi. Esse beatae architecto ad fuga ipsam similique consectetur adipisci. Modi consequuntur rem illum accusamus.
+ Voluptas voluptates voluptatem pariatur mollitia labore sint blanditiis. Rerum sapiente hic cumque nihil consectetur magnam. Facere fugiat minima explicabo quos illum. Aliquid impedit illum fugiat quam. Ad beatae perspiciatis perferendis nobis iure non dolore vero.
+ Laudantium nesciunt laborum fuga aliquid recusandae. Itaque sint sequi enim nesciunt earum. Cumque nemo labore quibusdam deleniti distinctio ducimus necessitatibus. Aliquid qui suscipit officiis molestias officia dolorem. Reiciendis eligendi error beatae fugit ipsum.
+ Autem rem et nobis necessitatibus. Laboriosam itaque cum aliquid laudantium ullam in. Repellendus similique ullam facere quis.
+ Ut quasi harum repudiandae consequuntur. Minus provident voluptates nemo labore fuga. Atque incidunt harum minus voluptatem voluptatum eveniet. Id assumenda pariatur minus sit ad ab. Iste inventore quidem sed quibusdam.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -11603,14 +11604,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:04.490Z'
- updated_at: '2026-06-14T21:18:04.490Z'
+ created_at: '2026-06-15T11:58:13.919Z'
+ updated_at: '2026-06-15T11:58:13.919Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-14T21:18:04.475Z'
- updated_at: '2026-06-14T21:18:04.496Z'
+ created_at: '2026-06-15T11:58:13.911Z'
+ updated_at: '2026-06-15T11:58:13.924Z'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
@@ -11746,8 +11747,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-06-14T21:18:05.164Z'
- updated_at: '2026-06-14T21:18:05.166Z'
+ created_at: '2026-06-15T11:58:14.567Z'
+ updated_at: '2026-06-15T11:58:14.569Z'
tax_category_id:
schema:
"$ref": "#/components/schemas/Product"
@@ -11930,8 +11931,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 616538
- slug: product-616538
+ name: Product 613358
+ slug: product-613358
meta_title:
meta_description:
meta_keywords:
@@ -11941,28 +11942,20 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Tempore eaque maxime numquam ex vitae sit quidem est.
- Unde veniam rem recusandae debitis enim. Dolor minus velit magnam
- repellendus blanditiis necessitatibus in dicta. Ratione eum id odio
- expedita doloremque. Esse nisi sint dolor quae corrupti nostrum.
- Iste ratione molestias mollitia quia expedita voluptatibus eligendi
- officia. Natus quo minima assumenda ipsum quaerat officiis. Quae
- exercitationem facilis ut doloribus. Ratione impedit ducimus voluptatibus
- adipisci voluptas esse illo. Explicabo deleniti laborum ducimus
- iste nemo ratione. Necessitatibus sint accusamus recusandae sequi.
- Voluptates natus ea nisi aut quod error laudantium dignissimos.
- Recusandae corporis laborum tempora architecto itaque totam beatae
- atque. Facilis at a delectus omnis molestiae aperiam. Odit id architecto
- unde suscipit. Amet atque aut dolorem autem eos. Doloremque repellat
- vel explicabo voluptatum facilis expedita. Illo voluptate ad maiores
- totam alias. Expedita tenetur optio quos quae sunt. Totam optio
- cumque nisi explicabo ipsa praesentium perferendis.
+ description: Facere delectus praesentium nulla laboriosam. Recusandae
+ dolorum rem veritatis voluptas odit. Sequi non asperiores quia sint
+ veritatis soluta dolorem amet. Fugit modi ratione exercitationem
+ illo magni molestias atque laudantium. Iure libero provident nihil
+ minus doloribus deleniti voluptates. Ad magni explicabo nobis minus.
+ Odit provident odio aliquid reprehenderit repellat asperiores quidem.
+ Voluptatum unde exercitationem recusandae tempore et quae. Magni
+ perspiciatis sed reiciendis repudiandae culpa voluptate in quasi.
+ Sunt nemo rem aspernatur cupiditate. Aliquam corporis architecto
+ alias aspernatur tenetur quibusdam fugiat quam.
description_html: |-
- Tempore eaque maxime numquam ex vitae sit quidem est. Unde veniam rem recusandae debitis enim. Dolor minus velit magnam repellendus blanditiis necessitatibus in dicta. Ratione eum id odio expedita doloremque.
- Esse nisi sint dolor quae corrupti nostrum. Iste ratione molestias mollitia quia expedita voluptatibus eligendi officia. Natus quo minima assumenda ipsum quaerat officiis. Quae exercitationem facilis ut doloribus. Ratione impedit ducimus voluptatibus adipisci voluptas esse illo.
- Explicabo deleniti laborum ducimus iste nemo ratione. Necessitatibus sint accusamus recusandae sequi. Voluptates natus ea nisi aut quod error laudantium dignissimos.
- Recusandae corporis laborum tempora architecto itaque totam beatae atque. Facilis at a delectus omnis molestiae aperiam. Odit id architecto unde suscipit. Amet atque aut dolorem autem eos.
- Doloremque repellat vel explicabo voluptatum facilis expedita. Illo voluptate ad maiores totam alias. Expedita tenetur optio quos quae sunt. Totam optio cumque nisi explicabo ipsa praesentium perferendis.
+ Facere delectus praesentium nulla laboriosam. Recusandae dolorum rem veritatis voluptas odit. Sequi non asperiores quia sint veritatis soluta dolorem amet. Fugit modi ratione exercitationem illo magni molestias atque laudantium.
+ Iure libero provident nihil minus doloribus deleniti voluptates. Ad magni explicabo nobis minus. Odit provident odio aliquid reprehenderit repellat asperiores quidem.
+ Voluptatum unde exercitationem recusandae tempore et quae. Magni perspiciatis sed reiciendis repudiandae culpa voluptate in quasi. Sunt nemo rem aspernatur cupiditate. Aliquam corporis architecto alias aspernatur tenetur quibusdam fugiat quam.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -11977,14 +11970,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:05.542Z'
- updated_at: '2026-06-14T21:18:05.542Z'
+ created_at: '2026-06-15T11:58:14.944Z'
+ updated_at: '2026-06-15T11:58:14.944Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-14T21:18:05.531Z'
- updated_at: '2026-06-14T21:18:05.549Z'
+ created_at: '2026-06-15T11:58:14.935Z'
+ updated_at: '2026-06-15T11:58:14.949Z'
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
@@ -12054,7 +12047,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-634132
+ slug: product-635236
meta_title:
meta_description:
meta_keywords:
@@ -12064,22 +12057,22 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Minima fugiat sed quibusdam facere tenetur vero autem.
- Nihil expedita unde sed error. Atque neque odit magnam ex molestiae.
- Porro dolor dolore officia consequuntur tempora dolorem quod eum.
- Iste possimus pariatur excepturi impedit facere. Impedit ut tempore
- eligendi perferendis repellat sapiente. Adipisci eum dolorem mollitia
- officiis quasi. Nemo necessitatibus vero iste dolorum nobis. Amet
- laudantium perspiciatis ullam quam tempore libero. Enim quam vitae
- id itaque voluptatibus. Natus dolores aliquid debitis dolore reprehenderit.
- Odit odio nulla molestias facere unde voluptates aliquam quaerat.
- Doloremque minus molestias atque non ad. Repellendus quisquam commodi
- dignissimos dolorem mollitia eaque laudantium. In iste perspiciatis
- sed tenetur ipsum eos.
+ description: Corporis nulla beatae sed deleniti. Asperiores impedit
+ eum ducimus earum aut. Aperiam natus magnam consequuntur fugit facere
+ nemo. Veniam molestias incidunt autem dolores asperiores officia.
+ Ab soluta optio inventore doloremque. Aperiam perspiciatis molestias
+ incidunt sequi. Corporis aspernatur quia recusandae deserunt impedit
+ facere. Incidunt maiores reprehenderit a ipsa id illum. Nobis delectus
+ consectetur iure sit quaerat officiis. Ut minima eos labore possimus
+ non deserunt. Tempora dolorum neque aut blanditiis occaecati eum.
+ Quia autem veniam quaerat eaque provident repudiandae. Quod illo
+ est non quis. Aperiam fugit repellendus quae amet hic similique.
+ Praesentium deleniti soluta amet iure distinctio optio magni.
description_html: |-
- Minima fugiat sed quibusdam facere tenetur vero autem. Nihil expedita unde sed error. Atque neque odit magnam ex molestiae. Porro dolor dolore officia consequuntur tempora dolorem quod eum. Iste possimus pariatur excepturi impedit facere.
- Impedit ut tempore eligendi perferendis repellat sapiente. Adipisci eum dolorem mollitia officiis quasi. Nemo necessitatibus vero iste dolorum nobis. Amet laudantium perspiciatis ullam quam tempore libero. Enim quam vitae id itaque voluptatibus.
- Natus dolores aliquid debitis dolore reprehenderit. Odit odio nulla molestias facere unde voluptates aliquam quaerat. Doloremque minus molestias atque non ad. Repellendus quisquam commodi dignissimos dolorem mollitia eaque laudantium. In iste perspiciatis sed tenetur ipsum eos.
+ Corporis nulla beatae sed deleniti. Asperiores impedit eum ducimus earum aut. Aperiam natus magnam consequuntur fugit facere nemo. Veniam molestias incidunt autem dolores asperiores officia.
+ Ab soluta optio inventore doloremque. Aperiam perspiciatis molestias incidunt sequi. Corporis aspernatur quia recusandae deserunt impedit facere.
+ Incidunt maiores reprehenderit a ipsa id illum. Nobis delectus consectetur iure sit quaerat officiis. Ut minima eos labore possimus non deserunt.
+ Tempora dolorum neque aut blanditiis occaecati eum. Quia autem veniam quaerat eaque provident repudiandae. Quod illo est non quis. Aperiam fugit repellendus quae amet hic similique. Praesentium deleniti soluta amet iure distinctio optio magni.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -12094,14 +12087,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:06.211Z'
- updated_at: '2026-06-14T21:18:06.211Z'
+ created_at: '2026-06-15T11:58:15.573Z'
+ updated_at: '2026-06-15T11:58:15.573Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-14T21:18:06.199Z'
- updated_at: '2026-06-14T21:18:06.531Z'
+ created_at: '2026-06-15T11:58:15.565Z'
+ updated_at: '2026-06-15T11:58:15.857Z'
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
@@ -12904,15 +12897,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-06-14T21:16:56.861Z'
- updated_at: '2026-06-14T21:16:56.861Z'
+ created_at: '2026-06-15T11:57:07.386Z'
+ updated_at: '2026-06-15T11:57:07.386Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-06-14T21:16:56.862Z'
- updated_at: '2026-06-14T21:16:56.862Z'
+ created_at: '2026-06-15T11:57:07.387Z'
+ updated_at: '2026-06-15T11:57:07.387Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -12974,8 +12967,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:10.723Z'
- updated_at: '2026-06-14T21:18:10.723Z'
+ created_at: '2026-06-15T11:58:19.826Z'
+ updated_at: '2026-06-15T11:58:19.826Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -13039,8 +13032,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:11.337Z'
- updated_at: '2026-06-14T21:18:11.337Z'
+ created_at: '2026-06-15T11:58:20.387Z'
+ updated_at: '2026-06-15T11:58:20.387Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -13168,8 +13161,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:11.933Z'
- updated_at: '2026-06-14T21:18:11.933Z'
+ created_at: '2026-06-15T11:58:20.972Z'
+ updated_at: '2026-06-15T11:58:20.972Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -13239,8 +13232,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:12.499Z'
- updated_at: '2026-06-14T21:18:12.499Z'
+ created_at: '2026-06-15T11:58:21.534Z'
+ updated_at: '2026-06-15T11:58:21.534Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -13331,8 +13324,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-06-14T21:18:12.797Z'
- updated_at: '2026-06-14T21:18:13.075Z'
+ created_at: '2026-06-15T11:58:21.846Z'
+ updated_at: '2026-06-15T11:58:22.127Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -13440,7 +13433,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-14T21:18:13.374Z'
+ starts_at: '2026-06-15T11:58:22.424Z'
expires_at:
usage_limit:
match_policy: all
@@ -13451,8 +13444,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-14T21:18:13.376Z'
- updated_at: '2026-06-14T21:18:13.377Z'
+ created_at: '2026-06-15T11:58:22.425Z'
+ updated_at: '2026-06-15T11:58:22.426Z'
action_ids: []
rule_ids: []
meta:
@@ -13559,7 +13552,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-06-14T21:18:14.300Z'
+ starts_at: '2026-06-15T11:58:23.328Z'
expires_at:
usage_limit:
match_policy: all
@@ -13570,8 +13563,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-14T21:18:14.301Z'
- updated_at: '2026-06-14T21:18:14.323Z'
+ created_at: '2026-06-15T11:58:23.329Z'
+ updated_at: '2026-06-15T11:58:23.346Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -13737,7 +13730,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-14T21:18:14.630Z'
+ starts_at: '2026-06-15T11:58:23.643Z'
expires_at:
usage_limit:
match_policy: all
@@ -13748,8 +13741,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-14T21:18:14.631Z'
- updated_at: '2026-06-14T21:18:14.632Z'
+ created_at: '2026-06-15T11:58:23.644Z'
+ updated_at: '2026-06-15T11:58:23.646Z'
action_ids: []
rule_ids: []
patch:
@@ -13846,7 +13839,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-14T21:18:15.518Z'
+ starts_at: '2026-06-15T11:58:24.541Z'
expires_at:
usage_limit:
match_policy: all
@@ -13857,8 +13850,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-14T21:18:15.519Z'
- updated_at: '2026-06-14T21:18:15.806Z'
+ created_at: '2026-06-15T11:58:24.542Z'
+ updated_at: '2026-06-15T11:58:24.821Z'
action_ids: []
rule_ids: []
requestBody:
@@ -14113,15 +14106,15 @@ paths:
label: Country
description:
preference_schema:
+ - key: country_iso
+ type: string
+ default:
- key: country_isos
type: array
default: []
- key: country_id
type: integer
default:
- - key: country_iso
- type: string
- default:
- type: currency
label: Currency
description:
@@ -14316,14 +14309,14 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-52cb3bbe6bbf
+ transaction_id: BGS-4eeb7aab87a3
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
metadata: {}
- created_at: '2026-06-14T21:17:44.198Z'
- updated_at: '2026-06-14T21:17:44.198Z'
+ created_at: '2026-06-15T11:57:54.078Z'
+ updated_at: '2026-06-15T11:57:54.078Z'
requestBody:
content:
application/json:
@@ -14425,8 +14418,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-06-14T21:18:19.323Z'
- updated_at: '2026-06-14T21:18:19.323Z'
+ created_at: '2026-06-15T11:58:28.279Z'
+ updated_at: '2026-06-15T11:58:28.279Z'
non_expiring: false
meta:
page: 1
@@ -14520,8 +14513,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-06-14T21:18:19.640Z'
- updated_at: '2026-06-14T21:18:19.640Z'
+ created_at: '2026-06-15T11:58:28.580Z'
+ updated_at: '2026-06-15T11:58:28.580Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -14593,8 +14586,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-06-14T21:16:47.335Z'
- updated_at: '2026-06-14T21:18:20.227Z'
+ created_at: '2026-06-15T11:56:57.658Z'
+ updated_at: '2026-06-15T11:58:29.200Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -14673,8 +14666,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-06-14T21:16:47.335Z'
- updated_at: '2026-06-14T21:18:20.842Z'
+ created_at: '2026-06-15T11:56:57.658Z'
+ updated_at: '2026-06-15T11:58:29.812Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -14833,12 +14826,12 @@ paths:
example:
data:
- id: admin_UkLWZg9DAJ
- first_name: Porfirio
- last_name: Hauck
- full_name: Porfirio Hauck
- created_at: '2026-06-14T21:16:47.670Z'
- updated_at: '2026-06-14T21:16:47.670Z'
+ first_name: Louann
+ last_name: Windler
+ full_name: Louann Windler
+ created_at: '2026-06-15T11:56:58.013Z'
+ updated_at: '2026-06-15T11:56:58.013Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -14899,12 +14892,12 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
- first_name: Angila
- last_name: Fritsch
- full_name: Angila Fritsch
- created_at: '2026-06-14T21:16:48.011Z'
- updated_at: '2026-06-14T21:16:48.011Z'
+ first_name: Lydia
+ last_name: Mosciski
+ full_name: Lydia Mosciski
+ created_at: '2026-06-15T11:56:58.374Z'
+ updated_at: '2026-06-15T11:56:58.374Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -14960,12 +14953,12 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
first_name: Renamed
- last_name: Zieme
- full_name: Renamed Zieme
- created_at: '2026-06-14T21:16:48.295Z'
- updated_at: '2026-06-14T21:16:48.312Z'
+ last_name: Jones
+ full_name: Renamed Jones
+ created_at: '2026-06-15T11:56:58.664Z'
+ updated_at: '2026-06-15T11:56:58.684Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -15076,15 +15069,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-06-14T21:17:22.461Z'
- updated_at: '2026-06-14T21:17:22.461Z'
- expires_at: '2026-06-28T21:17:22.458Z'
+ created_at: '2026-06-15T11:57:32.118Z'
+ updated_at: '2026-06-15T11:57:32.118Z'
+ expires_at: '2026-06-29T11:57:32.115Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=wriikhduGrNTiNbQWMSZ2c3f"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=e1KuTdWTDqbGoVNi8KmUKrZE"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -15148,13 +15141,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-06-14T21:17:22.763Z'
- updated_at: '2026-06-14T21:17:22.763Z'
- expires_at: '2026-06-28T21:17:22.761Z'
+ created_at: '2026-06-15T11:57:32.415Z'
+ updated_at: '2026-06-15T11:57:32.415Z'
+ expires_at: '2026-06-29T11:57:32.413Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=uAU8aN9z8QfeAVEBCm1gKLfY"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=GfvuQ6TNmEiJRGKj43o84dH9"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -15267,15 +15260,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-06-14T21:17:23.318Z'
- updated_at: '2026-06-14T21:17:23.318Z'
- expires_at: '2026-06-28T21:17:23.316Z'
+ created_at: '2026-06-15T11:57:32.962Z'
+ updated_at: '2026-06-15T11:57:32.962Z'
+ expires_at: '2026-06-29T11:57:32.961Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=SoZc6Sk8MZ2ecwJQKtk3xM88"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=SnZNPX6pKKwfKSBgE5ib7zZt"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -15327,8 +15320,8 @@ paths:
data:
- id: role_UkLWZg9DAJ
name: admin
- created_at: '2026-06-14T21:18:16.716Z'
- updated_at: '2026-06-14T21:18:16.716Z'
+ created_at: '2026-06-15T11:58:25.697Z'
+ updated_at: '2026-06-15T11:58:25.697Z'
meta:
page: 1
limit: 25
@@ -15466,8 +15459,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-06-14T21:18:17.018Z'
- updated_at: '2026-06-14T21:18:17.018Z'
+ created_at: '2026-06-15T11:58:25.978Z'
+ updated_at: '2026-06-15T11:58:25.978Z'
meta:
page: 1
limit: 25
@@ -15581,8 +15574,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 30
pickup_instructions:
- created_at: '2026-06-14T21:18:17.609Z'
- updated_at: '2026-06-14T21:18:17.609Z'
+ created_at: '2026-06-15T11:58:26.559Z'
+ updated_at: '2026-06-15T11:58:26.559Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -15759,8 +15752,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-06-14T21:18:17.902Z'
- updated_at: '2026-06-14T21:18:17.902Z'
+ created_at: '2026-06-15T11:58:26.855Z'
+ updated_at: '2026-06-15T11:58:26.855Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -15849,8 +15842,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 45
pickup_instructions:
- created_at: '2026-06-14T21:18:18.471Z'
- updated_at: '2026-06-14T21:18:18.752Z'
+ created_at: '2026-06-15T11:58:27.431Z'
+ updated_at: '2026-06-15T11:58:27.706Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -16090,13 +16083,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-14T21:18:22.261Z'
- updated_at: '2026-06-14T21:18:22.270Z'
+ created_at: '2026-06-15T11:58:31.226Z'
+ updated_at: '2026-06-15T11:58:31.235Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 792638
+ product_name: Product 79888
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
sku: SKU-98
@@ -16107,10 +16100,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 139.95
- height: 187.75
- width: 108.84
- depth: 91.66
+ weight: 132.11
+ height: 172.17
+ width: 121.88
+ depth: 20.86
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -16133,8 +16126,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:18:22.283Z'
- updated_at: '2026-06-14T21:18:22.283Z'
+ created_at: '2026-06-15T11:58:31.247Z'
+ updated_at: '2026-06-15T11:58:31.247Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -16143,13 +16136,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-14T21:18:22.281Z'
- updated_at: '2026-06-14T21:18:22.291Z'
+ created_at: '2026-06-15T11:58:31.245Z'
+ updated_at: '2026-06-15T11:58:31.254Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 792638
+ product_name: Product 79888
meta:
page: 1
limit: 25
@@ -16263,8 +16256,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:18:22.936Z'
- updated_at: '2026-06-14T21:18:22.936Z'
+ created_at: '2026-06-15T11:58:31.885Z'
+ updated_at: '2026-06-15T11:58:31.885Z'
metadata: {}
position: 3
cost_price:
@@ -16273,13 +16266,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-14T21:18:22.939Z'
- updated_at: '2026-06-14T21:18:22.941Z'
+ created_at: '2026-06-15T11:58:31.889Z'
+ updated_at: '2026-06-15T11:58:31.890Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 804533
+ product_name: Product 804818
'422':
description: validation error
content:
@@ -16469,10 +16462,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 173.37
- height: 146.58
- width: 65.11
- depth: 6.28
+ weight: 180.5
+ height: 74.25
+ width: 166.8
+ depth: 116.1
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -16495,8 +16488,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:18:23.352Z'
- updated_at: '2026-06-14T21:18:23.352Z'
+ created_at: '2026-06-15T11:58:32.296Z'
+ updated_at: '2026-06-15T11:58:32.296Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -16505,13 +16498,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-14T21:18:23.350Z'
- updated_at: '2026-06-14T21:18:23.360Z'
+ created_at: '2026-06-15T11:58:32.294Z'
+ updated_at: '2026-06-15T11:58:32.304Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 828811
+ product_name: Product 828706
'404':
description: variant not found
content:
@@ -16593,10 +16586,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 13.46
- height: 70.89
- width: 75.53
- depth: 101.55
+ weight: 60.93
+ height: 123.3
+ width: 165.7
+ depth: 169.49
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -16619,8 +16612,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-14T21:18:24.036Z'
- updated_at: '2026-06-14T21:18:24.036Z'
+ created_at: '2026-06-15T11:58:32.963Z'
+ updated_at: '2026-06-15T11:58:32.963Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -16629,13 +16622,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-14T21:18:24.034Z'
- updated_at: '2026-06-14T21:18:24.326Z'
+ created_at: '2026-06-15T11:58:32.961Z'
+ updated_at: '2026-06-15T11:58:33.251Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 841627
+ product_name: Product 849203
requestBody:
content:
application/json:
@@ -16879,9 +16872,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-14T21:18:24.750Z'
- updated_at: '2026-06-14T21:18:24.750Z'
- delivered_at: '2026-06-14T21:18:24.750Z'
+ created_at: '2026-06-15T11:58:33.667Z'
+ updated_at: '2026-06-15T11:58:33.667Z'
+ delivered_at: '2026-06-15T11:58:33.667Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
- id: whd_UkLWZg9DAJ
@@ -16897,9 +16890,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-14T21:18:24.749Z'
- updated_at: '2026-06-14T21:18:24.749Z'
- delivered_at: '2026-06-14T21:18:24.749Z'
+ created_at: '2026-06-15T11:58:33.667Z'
+ updated_at: '2026-06-15T11:58:33.667Z'
+ delivered_at: '2026-06-15T11:58:33.666Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
meta:
@@ -17002,9 +16995,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-14T21:18:25.445Z'
- updated_at: '2026-06-14T21:18:25.445Z'
- delivered_at: '2026-06-14T21:18:25.445Z'
+ created_at: '2026-06-15T11:58:34.302Z'
+ updated_at: '2026-06-15T11:58:34.302Z'
+ delivered_at: '2026-06-15T11:58:34.301Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
'404':
@@ -17093,8 +17086,8 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-14T21:18:26.363Z'
- updated_at: '2026-06-14T21:18:26.363Z'
+ created_at: '2026-06-15T11:58:35.207Z'
+ updated_at: '2026-06-15T11:58:35.207Z'
delivered_at:
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
@@ -17193,8 +17186,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-14T21:18:26.403Z'
- updated_at: '2026-06-14T21:18:26.403Z'
+ created_at: '2026-06-15T11:58:35.245Z'
+ updated_at: '2026-06-15T11:58:35.245Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -17289,10 +17282,10 @@ paths:
subscriptions:
- order.completed
disabled_reason:
- created_at: '2026-06-14T21:18:27.139Z'
- updated_at: '2026-06-14T21:18:27.139Z'
+ created_at: '2026-06-15T11:58:35.986Z'
+ updated_at: '2026-06-15T11:58:35.986Z'
disabled_at:
- secret_key: 5d1b84fa7afd75d6660d2870589f7169734dc48e8ebedc5e393c26fb44290fe4
+ secret_key: 138173635fcce3ae5f323b53ca0d9bc5452e639c34d74953de3989a684cfd325
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -17415,8 +17408,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-14T21:18:27.511Z'
- updated_at: '2026-06-14T21:18:27.511Z'
+ created_at: '2026-06-15T11:58:36.345Z'
+ updated_at: '2026-06-15T11:58:36.345Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -17495,8 +17488,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-14T21:18:28.165Z'
- updated_at: '2026-06-14T21:18:28.448Z'
+ created_at: '2026-06-15T11:58:36.997Z'
+ updated_at: '2026-06-15T11:58:37.287Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -17654,15 +17647,15 @@ paths:
response_body:
success:
payload:
- id: 40690989-09c4-4bd1-8c84-7a99190fee75
+ id: 1cf7102e-ed78-449b-9e39-124b13e4d899
name: webhook.test
- created_at: '2026-06-14T21:18:29Z'
+ created_at: '2026-06-15T11:58:38Z'
data:
message: This is a test webhook from Spree.
metadata:
spree_version: 5.5.0.rc1
- created_at: '2026-06-14T21:18:29.403Z'
- updated_at: '2026-06-14T21:18:29.403Z'
+ created_at: '2026-06-15T11:58:38.289Z'
+ updated_at: '2026-06-15T11:58:38.289Z'
delivered_at:
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks/orders
@@ -17728,8 +17721,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-14T21:18:29.451Z'
- updated_at: '2026-06-14T21:18:29.729Z'
+ created_at: '2026-06-15T11:58:38.337Z'
+ updated_at: '2026-06-15T11:58:38.617Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -17806,9 +17799,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-06-14T21:18:29.785Z'
- updated_at: '2026-06-14T21:18:30.064Z'
- disabled_at: '2026-06-14T21:18:30.064Z'
+ created_at: '2026-06-15T11:58:38.658Z'
+ updated_at: '2026-06-15T11:58:38.938Z'
+ disabled_at: '2026-06-15T11:58:38.938Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 32a419c7e5..bd3192cbb7 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -50,16 +50,16 @@ paths:
description: |
Authenticates a customer and returns a JWT access token + refresh token.
- Dispatches by the `provider` field to a strategy registered in
- `Spree.store_authentication_strategies`. When `provider` is omitted it
- defaults to `email`, which uses the built-in email/password strategy.
-
- To plug in a third-party identity provider (Auth0, Okta, Firebase, a
- custom JWT issuer, SAML, etc.), register a `Spree::Authentication::Strategies::BaseStrategy`
- subclass under a provider key, then send `{ "provider": "<your_key>", ... }`
- with the fields your strategy requires. The endpoint returns the same
- Spree-issued JWT + refresh token regardless of which strategy authenticated
- the request.
+ The `provider` field selects the authentication method. When omitted it
+ defaults to `email`, the built-in email/password login.
+
+ To authenticate against a third-party identity provider (Auth0, Okta,
+ Firebase, a custom JWT issuer, SAML, etc.), send
+ `{ "provider": "<your_key>", ... }` with the fields that provider
+ requires. The endpoint returns the same JWT + refresh token regardless of
+ which provider authenticated the request. See
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
+ for the list of configured providers and their required fields.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -87,16 +87,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY0NjcwM2Q0LWY5ZjAtNDlmMi05ZmZkLTA3YTZhY2I5YWZkZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjE1fQ.jlz2KHxYkB1Dd9ucl26zy6E5M7dFB5q9g-Qw0YjsX50
- refresh_token: MQ9QZ1ToR8QocZoDd4ggC8yN
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImIyZmVhMjFlLWJhMTItNGI5MC1hNTQyLTBmOTI4YWZkY2NjNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgxNTI4MzI0fQ.Y82KBbnXemdm8DKbBmvDv849CJ8zi2scmmJOo_iMpr4
+ refresh_token: iUhbdpqrZmFta8Xy9yw6Y3eW
user:
id: cus_UkLWZg9DAJ
- first_name: Colette
- last_name: Hegmann
+ first_name: Kelley
+ last_name: DuBuque
phone:
accepts_email_marketing: false
- full_name: Colette Hegmann
+ full_name: Kelley DuBuque
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -141,10 +141,10 @@ paths:
- password
- title: ProviderLogin
description: |
- Provider-dispatched login. The `provider` key selects a registered
- strategy class; the remaining fields are forwarded to the strategy's
- `authenticate` method. Required fields depend on the registered strategy
- — consult its documentation.
+ Provider-dispatched login. The `provider` key selects a configured
+ authentication provider; the remaining fields are forwarded to it.
+ Required fields depend on the provider — see
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
type: object
properties:
provider:
@@ -192,16 +192,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjNmZjU3NWU0LTVmNmItNDVjOC04MzIzLTIzMDMyMzVjZTkzMiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjE2fQ.OuCk-UNe-asA8DvK2yKMkp94BQz9PN_Z7_SnReeIRYE
- refresh_token: qLuZDRo8LqywXFThqPM5V2Ug
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImQyNjJiNmExLTExMDgtNDVjNi04NzE5LWJmNmNkY2NmYjY0OSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgxNTI4MzI1fQ.P7InEIuJCZwA0-q1SCkzxsanFWINnqEWAt3z-fcelFE
+ refresh_token: ujfKeA3UFnDGM7jetDREeLPT
user:
id: cus_UkLWZg9DAJ
- first_name: Debi
- last_name: Tillman
+ first_name: Teressa
+ last_name: Connelly
phone:
accepts_email_marketing: false
- full_name: Debi Tillman
+ full_name: Teressa Connelly
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -389,16 +389,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjU1YjA5Yzc4LTUzMTYtNDRjYy05ZjJiLThmN2E2MzViMmRlNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjI4fQ.FX2Te4WfdAu3kN_fvvfHsH92_axvIZTI1d8Zmw8R1mE
- refresh_token: Be2HUCjiJVRjgidFuYU7GRRh
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjgzOWEyZjA2LWRlNjgtNGJjYS04MmYzLTdlOGEwYjI0Mjk1NCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgxNTI4MzM3fQ.Z5TS6pKz61trZqVkO4clef6rU07NEc2UoKAfiZZnFnE
+ refresh_token: mGvQV5J2GRFAwywvMqD6s7B3
user:
id: cus_UkLWZg9DAJ
- first_name: Randa
- last_name: O'Hara
+ first_name: Desmond
+ last_name: Thompson
phone:
accepts_email_marketing: false
- full_name: Randa O'Hara
+ full_name: Desmond Thompson
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -798,13 +798,13 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1421251
- slug: product-1421251
+ name: Product 1465396
+ slug: product-1465396
meta_title:
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-05-26T16:14:22.402Z'
+ available_on:
purchasable: true
in_stock: false
backorderable: true
@@ -826,43 +826,25 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 1435220
- slug: product-1435220
+ name: Product 1475959
+ slug: product-1475959
meta_title:
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-26T16:14:22.472Z'
+ available_on:
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Architecto dignissimos nemo inventore incidunt enim.
- Odit accusamus repellat error saepe culpa unde eius. Cupiditate
- officiis voluptatem autem perferendis qui vitae omnis sunt. Debitis
- dolor tempore ad impedit itaque reprehenderit delectus. Doloremque
- laudantium iure recusandae iusto debitis laborum consequuntur.
- Impedit eum optio commodi tempora cum quidem. Facere voluptatum
- nam possimus veritatis nostrum explicabo dolore ex. Adipisci iure
- unde nobis itaque amet nesciunt voluptatibus impedit. Numquam
- in accusantium magni itaque exercitationem. Quas vero maxime voluptatem
- rem impedit inventore. Esse perferendis asperiores ea expedita
- aut tenetur soluta. Enim accusantium dolor adipisci impedit. Error
- maxime neque accusamus facere provident eum. Cum officia velit
- asperiores quod cupiditate fugiat. Possimus tenetur aut consequuntur
- iusto cumque quas. Ab velit ullam qui pariatur veritatis omnis.
- Accusantium vero occaecati explicabo neque animi commodi. Necessitatibus
- perspiciatis iste culpa totam quibusdam voluptate distinctio.
- Quod aliquam ut et autem. Saepe ut asperiores et quisquam perspiciatis
- molestiae. Vel recusandae sunt nemo et accusamus veniam ducimus.
- Laborum modi quasi perferendis culpa laboriosam quaerat magnam.
- Facere at tempora iusto ex magni aliquam modi debitis.
- description_html: |-
- Architecto dignissimos nemo inventore incidunt enim. Odit accusamus repellat error saepe culpa unde eius. Cupiditate officiis voluptatem autem perferendis qui vitae omnis sunt. Debitis dolor tempore ad impedit itaque reprehenderit delectus. Doloremque laudantium iure recusandae iusto debitis laborum consequuntur.
- Impedit eum optio commodi tempora cum quidem. Facere voluptatum nam possimus veritatis nostrum explicabo dolore ex. Adipisci iure unde nobis itaque amet nesciunt voluptatibus impedit. Numquam in accusantium magni itaque exercitationem. Quas vero maxime voluptatem rem impedit inventore.
- Esse perferendis asperiores ea expedita aut tenetur soluta. Enim accusantium dolor adipisci impedit. Error maxime neque accusamus facere provident eum. Cum officia velit asperiores quod cupiditate fugiat. Possimus tenetur aut consequuntur iusto cumque quas.
- Ab velit ullam qui pariatur veritatis omnis. Accusantium vero occaecati explicabo neque animi commodi. Necessitatibus perspiciatis iste culpa totam quibusdam voluptate distinctio. Quod aliquam ut et autem. Saepe ut asperiores et quisquam perspiciatis molestiae.
- Vel recusandae sunt nemo et accusamus veniam ducimus. Laborum modi quasi perferendis culpa laboriosam quaerat magnam. Facere at tempora iusto ex magni aliquam modi debitis.
+ description: Sed omnis rerum consequatur beatae explicabo. Dolorem
+ nesciunt ut consequatur nihil soluta. Occaecati non libero quasi
+ quibusdam est. Ratione eveniet dolore veniam mollitia ut beatae
+ esse quod.
+ description_html: Sed omnis rerum consequatur beatae explicabo.
+ Dolorem nesciunt ut consequatur nihil soluta. Occaecati non libero
+ quasi quibusdam est. Ratione eveniet dolore veniam mollitia ut
+ beatae esse quod.
default_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -964,13 +946,13 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1702106
- slug: product-1702106
+ name: Product 174105
+ slug: product-174105
meta_title:
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-05-26T16:14:24.749Z'
+ available_on:
purchasable: true
in_stock: false
backorderable: true
@@ -997,7 +979,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-05-11T16:14:24Z'
+ recorded_at: '2026-05-31T11:59:33Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -1235,9 +1217,9 @@ paths:
data:
- id: cart_gbHJdmfrXB
market_id:
- number: R537347983
- token: yasKz5u5Uc9LkM8L2qFcbBRhWQzwP1nNUBe
+ number: R391514877
+ token: 91qPEgrUq5tHSzYtRERirrN2JhoZq6qXpds
customer_note:
currency: USD
locale: en
@@ -1279,8 +1261,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 832050
- slug: product-832050
+ name: Product 873143
+ slug: product-873143
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1305,7 +1287,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H02359090617
+ number: H39160650276
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1334,7 +1316,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Blair Moore
+ name: Julianna Kessler
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1404,9 +1386,9 @@ paths:
market:
- id: cart_UkLWZg9DAJ
market_id:
- number: R807784030
- token: nXX7y8d9LZ1UXEmP8CxfE2vvLYZH9s6K9Y3
+ number: R325942958
+ token: B6DRcAGjbQuPPZK1RGyEfHU2hMPTpe6TLeD
customer_note:
currency: USD
locale: en
@@ -1448,8 +1430,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 821901
- slug: product-821901
+ name: Product 868901
+ slug: product-868901
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1474,7 +1456,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H10388427867
+ number: H13773213923
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1503,7 +1485,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Blair Moore
+ name: Julianna Kessler
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1646,8 +1628,8 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R386894669
- token: AFTUr4LVpnRaQVPntcz4FE5S8AuFqksEEGH
+ number: R510073501
+ token: 2tu4Hwc5RLLce6dwVkgkXjAFcbUysDt9NKK
email:
customer_note:
currency: USD
@@ -1802,9 +1784,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R929020865
- token: XrTGYYzWrW8pPm2d5SNuJgjFeHQ8MNN6Ufr
+ number: R620792925
+ token: utYWAb5PQQDTcLWNF5Z16H7cAS4JkvN9yBu
customer_note:
currency: USD
locale: en
@@ -1831,7 +1813,7 @@ paths:
display_delivery_total: "$0.00"
warnings:
- code: line_item_removed
- message: Product 874599 was removed because it was sold out
+ message: Product 911714 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
store_credit_total: '0.0'
@@ -1973,9 +1955,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R179766659
- token: LwvBFt69BRKiAP4yjrdydKDiefspHrgEEWV
+ number: R907955730
+ token: ecfTBKjeGZouycGCvsWFXtPTMF4kWT9hM1V
customer_note: Leave at door
currency: USD
locale: en
@@ -2019,8 +2001,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 888308
- slug: product-888308
+ name: Product 928261
+ slug: product-928261
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2045,7 +2027,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H67729784924
+ number: H47222346339
tracking:
tracking_url:
cost: '10.0'
@@ -2074,7 +2056,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Corazon Luettgen
+ name: Amos Paucek
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2311,9 +2293,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R741424210
- token: BjQx3Mm7YsM51uEQTvTjE4Jkc9QKpdQ57A4
+ number: R471169269
+ token: jxrk6j62tzu6rDG4XKCufjuG1v7oHk6tBjh
customer_note:
currency: USD
locale: en
@@ -2355,8 +2337,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 907994
- slug: product-907994
+ name: Product 942226
+ slug: product-942226
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2381,7 +2363,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H95245243522
+ number: H40223957218
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2410,7 +2392,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Agatha Hoppe
+ name: Lorene Hayes
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2545,8 +2527,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R464982887
+ number: R676900142
customer_note:
currency: USD
locale: en
@@ -2573,7 +2555,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-05-26T16:13:41.957Z'
+ completed_at: '2026-06-15T11:58:50.788Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -2583,8 +2565,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 924411
- slug: product-924411
+ name: Product 961063
+ slug: product-961063
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2609,7 +2591,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H02978405768
+ number: H78869810751
tracking:
tracking_url:
cost: '10.0'
@@ -2638,7 +2620,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Zachery Smith
+ name: Karen Crooks
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2667,8 +2649,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-176dea87fe0d
- number: PYQMKAGA
+ response_code: BGS-289d84a07e39
+ number: PE0ADTGA
amount: '29.99'
display_amount: "$29.99"
status: completed
@@ -2806,9 +2788,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R549797108
- token: dtJjZuWMLKEesDsMRZvLQQgWuYY9MuUwL2U
+ number: R862524013
+ token: mrU35EGJkvBQ6rRau1yGwHHjN9SE6EBfQ4b
customer_note:
currency: USD
locale: en
@@ -2857,8 +2839,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1111931
- slug: product-1111931
+ name: Product 1156655
+ slug: product-1156655
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2883,7 +2865,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H10253682077
+ number: H55247547840
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2912,7 +2894,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Clark Gerlach
+ name: Yvette Bradtke
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3066,9 +3048,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R750836348
- token: uesByPtiBKoM7CoRrEKxrNXDHDLP4WQHVEg
+ number: R959162990
+ token: HQ68bhTBj21RQMsLjfKn3CiBtiWkfTe3GX5
customer_note:
currency: USD
locale: en
@@ -3110,8 +3092,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1136391
- slug: product-1136391
+ name: Product 1178887
+ slug: product-1178887
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3136,7 +3118,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H71965274390
+ number: H41760498328
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3165,7 +3147,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Drusilla Greenfelder
+ name: Wendy Williamson
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3308,9 +3290,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R495333435
- token: vr5NsDydPesecXCDNmvqdhrE1FH96kV3K9s
+ number: R623969485
+ token: RaMmYKe9RJ768iGkrVv9p9USZ1Y3MLGF4Ta
customer_note:
currency: USD
locale: en
@@ -3354,8 +3336,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1159495
- slug: product-1159495
+ name: Product 119616
+ slug: product-119616
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3380,7 +3362,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H32451339376
+ number: H81921670877
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3409,7 +3391,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Danika Wiza
+ name: Karie Reichert
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3566,9 +3548,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R144554045
- token: RuTHka2EQdEPmHa7PXXzb8EAr5c9vSivWun
+ number: R447873832
+ token: kxSSLANWvAuqioECuek6VR1VcHdBRmugzgJ
customer_note:
currency: USD
locale: en
@@ -3607,8 +3589,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1174034
- slug: product-1174034
+ name: Product 1212044
+ slug: product-1212044
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3633,7 +3615,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H20393389861
+ number: H56136636084
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3662,7 +3644,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Gordon Pfeffer
+ name: Thu Schowalter
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3691,8 +3673,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260526161400395109
- number: PGO55NWN
+ response_code: 1-SC-20260615115908721736
+ number: PRC54RCX
amount: '50.0'
display_amount: "$50.00"
status: checkout
@@ -3871,9 +3853,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R375402748
- token: zK6CyYENcBq5VLBnwSXE35w1RrR7o2sTgky
+ number: R963189766
+ token: uzE8akL5NWHQrHavV8QRmaY9Fav6jgm1KYE
customer_note:
currency: USD
locale: en
@@ -3915,8 +3897,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1215119
- slug: product-1215119
+ name: Product 1259143
+ slug: product-1259143
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3941,7 +3923,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H49636801244
+ number: H99592833616
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3970,7 +3952,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Melvina Gottlieb
+ name: Bertie Prosacco
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3999,8 +3981,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260526161402955039
- number: PIQFGKXI
+ response_code: 1-SC-20260615115911281202
+ number: PPRO1ERR
amount: '50.0'
display_amount: "$50.00"
status: invalid
@@ -4130,9 +4112,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R128024977
- token: snfWbJhSsShSGdMgtj6NVNbk7SVZvg984Xb
+ number: R099306977
+ token: kzdRWepL3vurE5HGfMtEoxvz1cbcyp9XqWT
customer_note:
currency: USD
locale: en
@@ -4180,8 +4162,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1244584
- slug: product-1244584
+ name: Product 1282572
+ slug: product-1282572
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4208,8 +4190,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 1253628
- slug: product-1253628
+ name: Product 1297029
+ slug: product-1297029
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4352,9 +4334,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R216067679
- token: HBo9TtU6Kra7Pkqey8Rhw5WW93WSsLFKbcb
+ number: R106878138
+ token: TjBpf9dXVqHBvQ4xf1WqgENPvTvjRXXJYbU
customer_note:
currency: USD
locale: en
@@ -4399,8 +4381,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1289337
- slug: product-1289337
+ name: Product 1324596
+ slug: product-1324596
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4523,9 +4505,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R262930205
- token: 6F91AsEuASghgSqqpwTgtCCF84SEMYm1ozP
+ number: R496063706
+ token: PtHkBjGCGQ9sdca4d6qKRu9BrRGGKtgv16v
customer_note:
currency: USD
locale: en
@@ -4672,9 +4654,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_7d70cfacf0ae7492cf904547
+ external_id: bogus_ea79634e189c639d861a6e00
external_data:
- client_secret: bogus_secret_ede104f24aa5154c
+ client_secret: bogus_secret_f72b8758fe0fa38c
customer_external_id:
expires_at:
amount: '110.0'
@@ -4772,7 +4754,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_4c7d24178351b3d5952b3cf5
+ external_id: bogus_e9d0027df02447865be91d6a
external_data:
client_secret: secret_123
customer_external_id:
@@ -4834,7 +4816,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_331c7200fe221193bf414698
+ external_id: bogus_b380148c4136d56740995e0f
external_data:
client_secret: secret_123
customer_external_id:
@@ -4936,7 +4918,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_2ebf387c2f1e00f23440c181
+ external_id: bogus_3c47854d40a56adacc84cdbf
external_data:
client_secret: secret_123
customer_external_id:
@@ -5034,7 +5016,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: P6M3ZHJE
+ number: P2WGZDND
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -5140,9 +5122,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R903776007
- token: oPFUDLqngFUNHBsLi5NZyBfVqQFVkab5S48
+ number: R484708656
+ token: XDUDPRXDoHDJjZHYUfpm14rz1X4AArXAWPM
customer_note:
currency: USD
locale: en
@@ -5181,8 +5163,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1909153
- slug: product-1909153
+ name: Product 1943425
+ slug: product-1943425
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5207,7 +5189,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H71098380344
+ number: H08418417580
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5236,7 +5218,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Twanna Stamm
+ name: Celina Weissnat
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5265,8 +5247,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260526161430523363
- number: P1X82P2A
+ response_code: 1-SC-20260615115939484249
+ number: P1O1YU0T
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -5409,9 +5391,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R646602683
- token: c5RmvpB42n2ZRwYZ246jBJSFzvFgSLjsY5V
+ number: R637535401
+ token: 6wakQSdjNycZdnPupas4xehF6XMSi5X2UEb
customer_note:
currency: USD
locale: en
@@ -5453,8 +5435,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1922421
- slug: product-1922421
+ name: Product 1961135
+ slug: product-1961135
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5479,7 +5461,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H93482247486
+ number: H66598747714
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5508,7 +5490,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Carolina Kovacek
+ name: Janeen Miller
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5650,7 +5632,7 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R528526445
+ number: R527102095
customer_note:
currency: USD
@@ -5678,7 +5660,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-26T16:14:12.058Z'
+ completed_at: '2026-06-15T11:59:19.991Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5688,8 +5670,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1325879
- slug: product-1325879
+ name: Product 136109
+ slug: product-136109
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5714,7 +5696,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H26728427796
+ number: H14954481381
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5743,7 +5725,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Maida Rogahn
+ name: Demetrius Stark
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6680,8 +6662,8 @@ paths:
- id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R096824993
+ number: R509955302
customer_note:
currency: USD
locale: en
@@ -6708,7 +6690,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-26T16:13:49.079Z'
+ completed_at: '2026-06-15T11:58:58.271Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6718,8 +6700,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1016128
- slug: product-1016128
+ name: Product 1051635
+ slug: product-1051635
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6744,7 +6726,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H70742962050
+ number: H19998423944
tracking: U10000
tracking_url:
cost: '100.0'
@@ -6773,7 +6755,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Britany Halvorson
+ name: Cristy Renner
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6936,8 +6918,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R695830260
+ number: R830154963
customer_note:
currency: USD
locale: en
@@ -6964,7 +6946,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-26T16:13:49.771Z'
+ completed_at: '2026-06-15T11:58:58.969Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -6974,8 +6956,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1033099
- slug: product-1033099
+ name: Product 1071355
+ slug: product-1071355
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7000,7 +6982,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H08221240082
+ number: H49569395112
tracking: U10000
tracking_url:
cost: '100.0'
@@ -7029,7 +7011,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Aleen Reynolds
+ name: Marinda Marvin
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7149,8 +7131,8 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjlmZGNlNTdjLTY2NGQtNGZkNy1hOTU2LWQ1MjEzZjdhMjljYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc5ODE1NjMwfQ.vLRThKiR034rnZQYwpQGrIOeQSdrYNKnFVJZ86pCuUo
- refresh_token: GVssZP2L5Zk7uKQzTmwSQ4i5
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFmMTAzZTQ2LWU5MzItNGU4OS05YzQ4LWY2MDgxNWY5NDRmOCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgxNTI4MzQwfQ.zhZXtO1PovOFcFVQ9xOhUczWsejNzlucRVBy_dRDi1U
+ refresh_token: z3tuY8zVf1p9EtXfUb3S1zmM
user:
id: cus_UkLWZg9DAJ
@@ -7264,12 +7246,12 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Catarina
- last_name: Padberg
+ first_name: Nolan
+ last_name: Howell
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Catarina Padberg
+ full_name: Nolan Howell
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -7403,7 +7385,7 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -7592,7 +7574,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 91F1E57C6C99A62C
+ code: 5A2B2EFD99264F1D
status: active
currency: USD
amount: '10.0'
@@ -7688,7 +7670,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 76D77B6CFFA255C8
+ code: BD19336149B60B30
status: active
currency: USD
amount: '10.0'
@@ -7760,8 +7742,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_e60689fe4c66251e2b4dd2f4
- external_client_secret: bogus_seti_secret_633045dc9ddab700
+ external_id: bogus_seti_00fb19299e49e047f1561071
+ external_client_secret: bogus_seti_secret_058d30bbcb23c9c0
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7860,8 +7842,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_7ac50408dcea6ac09aa04e3d
- external_client_secret: seti_secret_77e80c695165694be5ef56b9
+ external_id: seti_test_f922f30381102eb43c50f4e6
+ external_client_secret: seti_secret_0db79f354247ed660fcc8d0b
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7937,8 +7919,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_6cb96d4ae6cdc1eadf02b1dc
- external_client_secret: seti_secret_bb0a7727be4c699d8584292f
+ external_id: seti_test_94bcc41a6292cfb766ef0815
+ external_client_secret: seti_secret_242e7a02c4a72dcc453b577d
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8875,7 +8857,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: KrDYvpcWeMWWCVsEuRj9V8Xm
+ token: QADrT6PD73cY9Xmroohy14E6
is_default: false
is_private: true
meta:
@@ -8951,7 +8933,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: LoTGXDT4V69PBMZXRWaS9Sjg
+ token: JTFa1Dbs4bgM3KPSB9B1euWF
is_default: false
is_private: true
schema:
@@ -9047,7 +9029,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: K1j4ej8u38Y4P9whWrjPs2R9
+ token: BcmKqrwZdsGpn3SH4bH21wdd
is_default: false
is_private: true
schema:
@@ -9109,7 +9091,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: xVUpUiksViqHLiWcenRTEGZx
+ token: 3djNmvgAgg469jpknzocgP4b
is_default: false
is_private: true
schema:
@@ -9224,7 +9206,7 @@ paths:
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-239
+ sku: SKU-243
options_text: ''
track_inventory: true
media_count: 0
@@ -9388,11 +9370,11 @@ paths:
application/json:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-05-26T16:14:11.183Z'
- updated_at: '2026-05-26T16:14:11.186Z'
+ created_at: '2026-06-15T11:59:19.028Z'
+ updated_at: '2026-06-15T11:59:19.029Z'
verified: true
- verified_at: '2026-05-26T16:14:11Z'
+ verified_at: '2026-06-15T11:59:19Z'
customer_id: cus_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9471,10 +9453,10 @@ paths:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-05-26T16:14:11.236Z'
- updated_at: '2026-05-26T16:14:11.255Z'
+ created_at: '2026-06-15T11:59:19.127Z'
+ updated_at: '2026-06-15T11:59:19.148Z'
verified: true
- verified_at: '2026-05-26T16:14:11Z'
+ verified_at: '2026-06-15T11:59:19Z'
customer_id:
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9549,7 +9531,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-006f63da-6062-4a3f-9fd7-aa690f7b356c
+ slug: privacy-policy-c37e2d35-0a2e-4e4d-a357-a5d82d934f5e
body: We respect your privacy.
body_html: |
<div class="trix-content">
@@ -10400,11 +10382,14 @@ components:
type: string
active:
type: boolean
+ default:
+ type: boolean
required:
- id
- name
- code
- active
+ - default
x-typelizer: true
Country:
type: object
@@ -11629,6 +11614,28 @@ components:
- display_compare_at_amount
- price_list_id
x-typelizer: true
+ ProductPublication:
+ type: object
+ properties:
+ id:
+ type: string
+ published_at:
+ type: string
+ nullable: true
+ unpublished_at:
+ type: string
+ nullable: true
+ product_id:
+ type: string
+ channel_id:
+ type: string
+ required:
+ - id
+ - published_at
+ - unpublished_at
+ - product_id
+ - channel_id
+ x-typelizer: true
Product:
type: object
properties:
@@ -11697,6 +11704,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/OptionType"
+ option_values:
+ type: array
+ items:
+ "$ref": "#/components/schemas/OptionValue"
categories:
type: array
items:
diff --git a/docs/developer/core-concepts/addresses.mdx b/docs/developer/core-concepts/addresses.mdx
index c65268f985..577e60b48f 100644
--- a/docs/developer/core-concepts/addresses.mdx
+++ b/docs/developer/core-concepts/addresses.mdx
@@ -30,7 +30,6 @@ An address represents a shipping or billing location. Every order has a shipping
| `postal_code` | Postal code (not required for all countries) |
| `phone` | Phone number |
| `company` | Company name (optional) |
-| `label` | User-facing label like "Home" or "Office" (optional, unique per customer) |
| `country_iso` | Country (ISO alpha-2 code, e.g., `US`) |
| `state_abbr` | State/province abbreviation (required for some countries, e.g., `CA`) |
@@ -42,7 +41,7 @@ Customers can save multiple addresses and set a default for shipping and billing
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List addresses
const { data: addresses } = await client.customer.addresses.list()
@@ -64,17 +63,20 @@ await client.customer.addresses.update('addr_xxx', { city: 'Brooklyn' })
// Delete an address
await client.customer.addresses.delete('addr_xxx')
-// Set as default shipping or billing address
-await client.customer.addresses.markAsDefault('addr_xxx', 'shipping')
+// Set as default shipping or billing address — pass the boolean flags to create or update
+await client.customer.addresses.update('addr_xxx', { is_default_shipping: true })
+await client.customer.addresses.update('addr_xxx', { is_default_billing: true })
```
```bash cURL
# List addresses
-curl 'https://api.mystore.com/api/v3/store/customer/addresses' \
+curl 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>'
# Create an address
-curl -X POST 'https://api.mystore.com/api/v3/store/customer/addresses' \
+curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/addresses' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>' \
-H 'Content-Type: application/json' \
-d '{
@@ -89,13 +91,15 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customer/addresses' \
}'
# Update an address
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me/addresses/addr_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>' \
-H 'Content-Type: application/json' \
-d '{ "city": "Brooklyn" }'
# Delete an address
-curl -X DELETE 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx' \
+curl -X DELETE 'https://api.mystore.com/api/v3/store/customers/me/addresses/addr_xxx' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>'
```
@@ -103,11 +107,11 @@ curl -X DELETE 'https://api.mystore.com/api/v3/store/customer/addresses/addr_xxx
### Checkout Addresses
-During checkout, you can either reference a saved address by ID or pass a new address inline:
+During checkout, you can either reference a saved address by ID or pass a new address inline. See the [cart and checkout SDK guide](/developer/sdk/store/cart-checkout) for the full flow of passing addresses during checkout:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Use saved addresses
await client.carts.update(cartId, {
shipping_address_id: 'addr_xxx',
@@ -178,19 +182,25 @@ Only countries assigned to a [Market](/developer/core-concepts/markets) are avai
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List all countries available in this store
const { data: countries } = await client.countries.list()
// Get a country with its states (for address form dropdowns)
-const usa = await client.countries.get('US', { include: 'states' })
+const usa = await client.countries.get('US', { expand: ['states'] })
// usa.states => [{ name: "Alabama", abbr: "AL" }, { name: "Alaska", abbr: "AK" }, ...]
// Get a country with its market (for currency/locale resolution)
-const germany = await client.countries.get('DE', { include: 'market' })
+const germany = await client.countries.get('DE', { expand: ['market'] })
// germany.market => { currency: "EUR", default_locale: "de", tax_inclusive: true }
```
+```typescript Admin SDK
+const { data: countries } = await adminClient.countries.list()
+
+const usa = await adminClient.countries.get('US')
+```
+
```bash cURL
# List all countries
curl 'https://api.mystore.com/api/v3/store/countries' \
@@ -213,12 +223,12 @@ Use the `states_required` and `zipcode_required` fields to build adaptive addres
States (provinces, regions) belong to a country and are used for address validation and zone matching. Countries like the US, Canada, Australia, and India have predefined states — for these countries, customers must select a state from the list rather than typing a name.
-States are fetched via the country endpoint using `?expand=states`:
+States are fetched via the country endpoint using [`?expand=states`](/api-reference/store-api/relations):
<CodeGroup>
-```typescript SDK
-const usa = await client.countries.get('US', { include: 'states' })
+```typescript Store SDK
+const usa = await client.countries.get('US', { expand: ['states'] })
// Build a state picker from the response
usa.states.forEach(state => {
@@ -226,6 +236,10 @@ usa.states.forEach(state => {
})
```
+```typescript Admin SDK
+const usa = await adminClient.countries.get('US', { expand: ['states'] })
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -271,3 +285,5 @@ Here's how geography flows through a typical checkout:
- [Taxes](/developer/core-concepts/taxes) — How zones and addresses affect taxation
- [Shipments](/developer/core-concepts/shipments) — How zones and addresses affect shipping availability
- [Orders](/developer/core-concepts/orders) — Order billing and shipping addresses
+- [Account SDK guide](/developer/sdk/store/account) — Managing the logged-in customer's address book with `client.customer.addresses`
+- [Store API authentication](/api-reference/store-api/authentication) — How to obtain and send the customer JWT (`Authorization: Bearer` header)
diff --git a/docs/developer/core-concepts/adjustments.mdx b/docs/developer/core-concepts/adjustments.mdx
index 851e8775bf..3abfcfe726 100644
--- a/docs/developer/core-concepts/adjustments.mdx
+++ b/docs/developer/core-concepts/adjustments.mdx
@@ -70,12 +70,12 @@ Adjustments are created by two sources:
## Store API
-Adjustments appear in order responses when you expand line items or fulfillments:
+Adjustments appear in order responses when you [`?expand=items,fulfillments`](/api-reference/store-api/relations) on the order. The response exposes the [`amount`, `adjustment_total`, and the tax totals](/api-reference/store-api/monetary-amounts) as money fields:
<CodeGroup>
-```typescript SDK
-const order = await client.orders.get('or_abc123', {
+```typescript Store SDK
+const order = await client.orders.get('or_abc123', { expand: ['items', 'fulfillments'] }, {
spreeToken: '<token>',
})
@@ -87,12 +87,17 @@ order.items?.forEach(item => {
})
// Order-level totals
-order.adjustment_total // total of all adjustments
-order.promo_total // total promotional discounts
+order.adjustment_total // total of all adjustments
+order.discount_total // total promotional discounts
+order.display_discount_total // formatted promotional discounts
order.additional_tax_total
order.included_tax_total
```
+```typescript Admin SDK
+const order = await adminClient.orders.get('or_abc123')
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
-H 'X-Spree-API-Key: pk_xxx' \
@@ -107,3 +112,4 @@ curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfill
- [Taxes](/developer/core-concepts/taxes) — Tax adjustments
- [Shipments](/developer/core-concepts/shipments) — Shipping adjustments
- [Orders](/developer/core-concepts/orders) — How adjustments affect order totals
+- [Calculators](/developer/core-concepts/calculators) — How tax rate and promotion action amounts are computed
diff --git a/docs/developer/core-concepts/architecture.mdx b/docs/developer/core-concepts/architecture.mdx
index 62d5f784ea..c09398f0bb 100644
--- a/docs/developer/core-concepts/architecture.mdx
+++ b/docs/developer/core-concepts/architecture.mdx
@@ -108,14 +108,14 @@ erDiagram
## APIs
-Spree exposes two REST APIs, both under API v3:
+Spree exposes two REST APIs:
| API | Purpose | Authentication |
|-----|---------|----------------|
-| [**Store API**](/api-reference/introduction) | Customer-facing — cart, checkout, products, account | Publishable API key + JWT |
-| **Admin API** | Operational — manage products, orders, customers, settings | Secret API key |
+| [**Store API**](/api-reference/store-api/introduction) | Customer-facing — cart, checkout, products, account | [Publishable API key + JWT](/api-reference/store-api/authentication) |
+| [**Admin API**](/api-reference/admin-api/introduction) | Operational — manage products, orders, customers, settings | [Secret API key](/api-reference/admin-api/authentication) + JWT |
-Both APIs use [prefixed IDs](/api-reference/introduction) (e.g., `prod_86Rf07xd4z`, `or_m3Rp9wXz`), flat JSON request/response structures, and full TypeScript types via the [@spree/sdk](/developer/sdk/quickstart).
+Both APIs share the same list shapes, filtering, querying, and pagination, and offer fully typed TypeScript clients — [@spree/sdk](/developer/sdk/quickstart) for the Store API and [@spree/admin-sdk](/developer/sdk/admin/quickstart) for the Admin API.
Events from both APIs can trigger [Webhooks](/developer/core-concepts/webhooks) to notify external systems in real time.
@@ -140,7 +140,7 @@ Spree is designed to be customized without modifying core code. The main extensi
| **Events & Subscribers** | React to order completion, payment, shipment events | [Events Guide](/developer/core-concepts/events) |
| **Webhooks** | Notify external systems of changes | [Webhooks Guide](/developer/core-concepts/webhooks) |
| **Dependencies** | Swap out services (tax calculation, shipping estimation) | [Dependencies Guide](/developer/customization/dependencies) |
-| **Decorators** | Modify existing model/controller behavior (use sparingly) | [Decorators Guide](/developer/customization/decorators) |
+| **Decorators** | Modify existing core models & classes behavior (use sparingly) | [Decorators Guide](/developer/customization/decorators) |
<Info>
For most customizations, prefer **Events** and **Dependencies** over Decorators. They're easier to maintain and won't break during upgrades.
@@ -167,11 +167,9 @@ Spree is distributed as a set of packages:
| Package | Purpose |
|---------|---------|
-| [`@spree/sdk`](/developer/sdk/quickstart) | TypeScript SDK for Store API and Admin API |
-
-<Info>
-For headless commerce, you only need the `spree` package. Build your customer-facing frontend with any technology (Next.js, Nuxt, mobile apps) using the Store API and SDK.
-</Info>
+| [`@spree/sdk`](/developer/sdk/quickstart) | TypeScript SDK for the Store API |
+| [`@spree/admin-sdk`](/developer/sdk/admin/quickstart) | TypeScript SDK for the Admin API |
+| [`@spree/cli`](/developer/cli/quickstart) | Command line interface for managing local environment and using the Admin API from the terminal |
## Related Documentation
diff --git a/docs/developer/core-concepts/calculators.mdx b/docs/developer/core-concepts/calculators.mdx
index 19d9359d4a..0ad47db44f 100644
--- a/docs/developer/core-concepts/calculators.mdx
+++ b/docs/developer/core-concepts/calculators.mdx
@@ -47,7 +47,7 @@ erDiagram
- Used by **[Tax Rates](/developer/core-concepts/taxes)** to calculate tax amounts
- Used by **[Shipping Methods](/developer/core-concepts/shipments)** to calculate shipping costs
- Used by **[Promotion Actions](/developer/core-concepts/promotions)** to calculate discounts
-- Calculators store preferences (rates, percentages, etc.) for their calculations
+- Calculators store [preferences (rates, percentages, etc.)](/developer/customization/model-preferences) for their calculations
Spree makes extensive use of the `Spree::Calculator` model and there are several subclasses provided to deal with various types of calculations flat rate, percentage discount, sales tax, VAT, etc. All calculators extend the `Spree::Calculator` class and must provide the following methods:
@@ -61,7 +61,7 @@ def compute(object=nil)
end
```
-Calculators link to a `calculable` object, which are typically one of `Spree::ShippingMethod`, `Spree::TaxRate`, or `Spree::Promotion::Actions::CreateAdjustment`. These three classes use the `Spree::Core::CalculatedAdjustment` module described below to provide an easy way to calculate adjustments for their objects.
+Calculators link to a `calculable` object, which are typically one of `Spree::ShippingMethod`, `Spree::TaxRate`, or `Spree::Promotion::Actions::CreateAdjustment`. These three classes use the `Spree::CalculatedAdjustments` module described below to provide an easy way to calculate adjustments for their objects.
## Available Calculators
@@ -95,7 +95,7 @@ This calculator has two preferences: `amount` and `currency`. These can be set l
```ruby
calculator.preferred_amount = 10
-calculator.currency = "USD"
+calculator.preferred_currency = "USD"
```
The currency for this calculator is used to check to see if a shipping method is available for an order. If an order's currency does not match the shipping method's currency, then that shipping method will not be displayed on the frontend.
@@ -128,53 +128,31 @@ Thus, if you have ten items in your shopping cart, your `first_item` preference
### Per Item
-The Per Item calculator computes a value for every item within an order. This is useful for providing a discount for a specific product, without it affecting others.
+The Per Item calculator (`Spree::Calculator::Shipping::PerItem`) is a shipping calculator that charges a flat amount for every item in a shipment.
This calculator takes two preferences:
-* `amount`: The amount per item to calculate.
+* `amount`: The flat amount charged per item.
* `currency`: The currency for this calculator.
-This calculator depends on its `calculable` responding to a `promotion` method, which should return a `Spree::Promotion` or similar object. This object should then return a list of rules, which should respond to a `products` method. This is used to return a result of matching products.
-
-The list of matching products is compared against the line items for the order being calculated. If any of the matching products are included in the order, they are eligible for this calculator. The calculation is this:
-
-\[matching product quantity\] x \[amount\]
-
-Every matching product within an order will add to the calculator's total. For example, assuming the calculator has an `amount` of 5 and there's an order with the following line items:
-
-* Product A: `$15.00` x `2` within matching products
-* Product B: `$10.00` x `1` within matching products
-* Product C: `$20.00` x `4` excluded from matching products
-
-The calculation would be:
+It computes a flat rate per item by multiplying the `amount` preference by the total item quantity in the shipment package:
```text
-= (2 x 5) + (1 x 5)
-= 10 + 5
+[amount] x [total item quantity in package]
```
-meaning the calculator will compute an amount of 15.
+For example, with an `amount` of `5` and a package containing `3` items in total, the calculator computes an amount of `15` (`5 x 3`).
### Percent Per Item
-The Percent Per Item calculator works in a near-identical fashion to the [Per Item Calculator](#per-item), with the exception that rather than providing a flat-rate per item, it is a percentage.
+The Percent Per Item calculator (`Spree::Calculator::PercentOnLineItem`) applies a percentage discount to a single line item. It takes two preferences:
-Assuming a calculator amount of 10% and an order such as this:
+* `percent`: The percentage to apply to the line item's amount.
+* `apply_only_on_full_priced_items`: When enabled, skips line items that are already on sale.
-* Product A: $15.00 x 2 within matching products
-* Product B: $10.00 x 1 within matching products
-* Product C: $20.00 x 4 excluded from matching products
-
-The calculation would be:
-
-```text
-= ($15 x 2 x 10%) + ($10 x 10%)
-= ($30 x 10%) + ($10 x 10%)
-= $3 + $1
-```
+For each line item, the calculator computes `line item amount` x `percent` / `100`, capped at the line item's amount so a promotion adjustment never pushes the total negative.
-The calculator will calculate a discount of $4.
+For example, a `$30` line item at `10%` yields a `$3` discount (`$30 x 10% = $3`).
### Price Sack
@@ -269,15 +247,24 @@ end
## Calculated Adjustments
-If you wish to use Spree's calculator functionality for your own application, you can include the `Spree::Core::CalculatedAdjustments` module into a model of your choosing.
+If you wish to use Spree's calculator functionality for your own application, you can include the `Spree::CalculatedAdjustments` module into a model of your choosing.
```ruby app/models/plan.rb
class Plan < ActiveRecord::Base
- include Spree::Core::CalculatedAdjustments
+ include Spree::CalculatedAdjustments
end
```
-To have calculators available for this class, you will need to register them:
+To have calculators available for this class, you will need to register them. `Spree.calculators` is a fixed-member struct (`SpreeCalculators`, defined in `spree/core/lib/spree/core/engine.rb`) that exposes only the four built-in buckets:
+
+* `shipping_methods`
+* `tax_rates`
+* `promotion_actions_create_adjustments`
+* `promotion_actions_create_item_adjustments`
+
+`Plan.calculators` internally calls `Spree.calculators.send(:plans)` (the tableized model name), so both registration and lookup raise `NoMethodError` until you extend the struct to add a matching `plans` member. Ruby structs cannot gain members at runtime, so this means redefining the `SpreeCalculators` struct (or reassigning `Spree.calculators` to an object that responds to `plans`) before you register anything onto it.
+
+Once the struct exposes a `plans` member you can register calculators:
<Tabs>
<Tab title="Spree 5.2+">
@@ -302,23 +289,16 @@ Plan.calculators
Using this method, you can then display the calculators as you please. Each object for this new class will need to have a calculator associated so that adjustments can be calculated on them.
-This module provides a `has_one` association to a `calculator` object, as well as some convenience helpers for creating and updating adjustments for objects. Assuming that an object has a calculator associated with it first, creating an adjustment is simple:
+`Spree::CalculatedAdjustments` provides a `has_one :calculator` association (with `accepts_nested_attributes_for` and a presence validation), delegates `compute` to that calculator, exposes a `with_calculator` scope, `calculator_type` / `calculator_type=` accessors, and the `Plan.calculators` registry shown above. To work out what the calculator would compute an amount to be, call `compute` on an instance:
```ruby
-plan.create_adjustment("#{plan.name}", <target object>, <calculable object>)
+plan.compute(<calculable object>)
```
-To update this adjustment:
+The module does not define `create_adjustment`, `update_adjustment`, or `compute_amount`. If you also need to build adjustments, include `Spree::AdjustmentSource`, which adds `create_adjustment(order, adjustable, included = false)`. That method calls a `compute_amount` you define on the including model (as `Spree::TaxRate` and the `Spree::Promotion::Actions` classes do). There is no `update_adjustment` method in core.
-```ruby
-plan.update_adjustment(<adjustment object>, <calculable object>)
-```
-
-To work out what the calculator would compute an amount to be:
-
-```ruby
-plan.compute_amount(<calculable object>)
-```
+## Related Documentation
-`create_adjustment`, `update_adjustment` and `compute_amount` will call `compute` on the `Calculator` object. This `calculable` amount is whatever object your `CustomCalculator` class supports.
+- [Adjustments](/developer/core-concepts/adjustments) — the records calculators compute amounts for.
+- [Dependencies](/developer/customization/dependencies) — swap out calculators via the Dependencies system.
diff --git a/docs/developer/core-concepts/channels.mdx b/docs/developer/core-concepts/channels.mdx
index c0eb3af06b..5f2f4d1837 100644
--- a/docs/developer/core-concepts/channels.mdx
+++ b/docs/developer/core-concepts/channels.mdx
@@ -21,7 +21,7 @@ Every store ships with one default channel named *Online Store*. You can add mor
| `code` | URL-safe slug, stable identifier sent via the `X-Spree-Channel` header | `pos` |
| `active` | When `false`, the channel stops accepting orders | `true` |
| `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` |
-| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](/developer/core-concepts/shipments#order-routing) strategy | `Rules` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](/developer/core-concepts/shipments#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`.
@@ -38,11 +38,11 @@ The resolved channel is then available to controllers, models, and serializers t
### Selecting a channel from the Store SDK
-The Store SDK sends `X-Spree-Channel` on every request when configured. The value can be either the channel `code` (merchant-meaningful, recommended) or the prefixed ID (`ch_…`).
+The Store SDK sends `X-Spree-Channel` on every request when configured. The value can be either the channel `code` (merchant-meaningful, recommended) or the prefixed ID (`ch_…`). `setChannel` is a sticky setter that [mirrors `setLocale` / `setCurrency` / `setCountry`](/developer/sdk/configuration).
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Client-level default
const client = createClient({
baseUrl: 'https://api.mystore.com',
@@ -57,6 +57,11 @@ client.setChannel('wholesale')
const products = await client.products.list({}, { channel: 'pos' })
```
+```typescript Admin SDK
+// admin filters by the channel's code via Ransack (q[channels_code_eq])
+const { data: products } = await adminClient.products.list({ channels_code_eq: 'pos' })
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products' \
-H 'X-Spree-API-Key: pk_xxx' \
@@ -65,7 +70,7 @@ curl 'https://api.mystore.com/api/v3/store/products' \
</CodeGroup>
-The Admin API does not consume `X-Spree-Channel` — admin endpoints return data across all channels for the current store. Filter by channel on the admin side via Ransack (`q[channel_id_eq]=ch_xxx` for orders, `q[channels_id_in][]=ch_xxx` for products).
+The Admin API does not consume `X-Spree-Channel` — admin endpoints return data across all channels for the current store. [Filter by channel on the admin side via Ransack](/api-reference/admin-api/querying) (`q[channel_id_eq]=ch_xxx` for orders, `q[channels_id_in][]=ch_xxx` for products).
### Product visibility
@@ -107,7 +112,7 @@ Three endpoints cover the publishing surface:
<CodeGroup>
-```typescript SDK
+```typescript Admin SDK
await adminClient.channels.addProducts('ch_xxx', {
product_ids: ['prod_aaa', 'prod_bbb'],
// Optional window — when omitted, existing schedules are preserved
@@ -135,7 +140,7 @@ For per-product updates, use `PATCH /api/v3/admin/products/:id` with a `product_
<CodeGroup>
-```typescript SDK
+```typescript Admin SDK
await adminClient.products.update('prod_xxx', {
product_publications: [
{ channel_id: 'ch_online' },
@@ -172,3 +177,5 @@ The write contract is **full-set**: the array represents the complete desired st
- [Markets](/developer/core-concepts/markets) — Different from channels: markets segment geography/currency, channels segment selling surfaces
- [Products](/developer/core-concepts/products) — Product catalog and publication
- [Order Routing](/developer/core-concepts/shipments#order-routing) — Channels can override the store's routing strategy
+- [Store SDK: Products](/developer/sdk/store/products) — Channel-scoped product listing and filtering
+- [Admin SDK: Resources](/developer/sdk/admin/resources) — How `adminClient.channels.addProducts` and other resource methods are structured
diff --git a/docs/developer/core-concepts/customers.mdx b/docs/developer/core-concepts/customers.mdx
index dd32c7691e..5a546f419a 100644
--- a/docs/developer/core-concepts/customers.mdx
+++ b/docs/developer/core-concepts/customers.mdx
@@ -46,7 +46,7 @@ erDiagram
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { token, user } = await client.customers.create({
password: 'password123',
@@ -55,7 +55,7 @@ const { token, user } = await client.customers.create({
last_name: 'Doe',
})
// token => JWT token for subsequent authenticated requests
-// user => { id: "usr_xxx", email: "[email protected]", first_name: "John", ... }
+// user => { id: "cus_abc123", email: "[email protected]", first_name: "John", ... }
```
```bash cURL
@@ -73,11 +73,31 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
</CodeGroup>
+<Note>
+The Store API flow above is **customer self-registration** — the customer sets a password and gets a JWT back. To [create a customer record from the back office](/developer/sdk/admin/resources) (importers, CRM sync, phone orders), use the [Admin SDK](/developer/sdk/admin/quickstart) instead. No password is set, so it's a managed record rather than a sign-up:
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const customer = await client.customers.create({
+ email: '[email protected]',
+ first_name: 'John',
+ last_name: 'Doe',
+ tags: ['wholesale'],
+})
+```
+</Note>
+
## Login
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { token, user } = await client.auth.login({
password: 'password123',
@@ -97,23 +117,26 @@ curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
</CodeGroup>
-The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header.
+The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the [`Authorization: Bearer <token>`](/api-reference/store-api/authentication) header.
## Token Refresh
-Refresh an expiring token to keep the session alive:
+Refresh an expiring token to keep the session alive. For how `client.auth.login` and `client.auth.refresh` fit into configuring the SDK for guest vs customer (JWT) auth, see the [SDK authentication guide](/developer/sdk/authentication):
<CodeGroup>
-```typescript SDK
-const { token } = await client.auth.refresh({
- token: existingToken,
+```typescript Store SDK
+const { token, refresh_token } = await client.auth.refresh({
+ refresh_token: existingRefreshToken,
})
+// Persist the rotated refresh_token for the next refresh
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
- -H 'Authorization: Bearer <jwt_token>'
+ -H 'X-Spree-Api-Key: pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "refresh_token": "rt_xxx" }'
```
</CodeGroup>
@@ -126,8 +149,8 @@ Password reset is a two-step flow. First, request a reset email. Then, use the t
<CodeGroup>
-```typescript SDK
-await client.customer.passwordResets.create({
+```typescript Store SDK
+await client.passwordResets.create({
redirect_url: 'https://myshop.com/reset-password',
})
@@ -136,7 +159,7 @@ await client.customer.passwordResets.create({
```
```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/customer/password_resets' \
+curl -X POST 'https://api.mystore.com/api/v3/store/password_resets' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
@@ -147,7 +170,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customer/password_resets' \
</CodeGroup>
-The optional `redirect_url` parameter specifies where the password reset link in the email should point to. The token will be appended as a query parameter (e.g., `https://myshop.com/reset-password?token=...`). If the store has [Allowed Origins](/developer/core-concepts/allowed-origins) configured, the `redirect_url` must match one of them.
+The optional `redirect_url` parameter specifies where the password reset link in the email should point to. The token will be appended as a query parameter (e.g., `https://myshop.com/reset-password?token=...`). If the store has Allowed Origins configured, the `redirect_url` must match one of them.
This fires a `customer.password_reset_requested` event with the reset token in the payload. If you're using the `spree_emails` package, the email is sent automatically. Otherwise, subscribe to this event to send the reset email yourself (see [Events](/developer/core-concepts/events)).
@@ -155,8 +178,8 @@ This fires a `customer.password_reset_requested` event with the reset token in t
<CodeGroup>
-```typescript SDK
-const { token, user } = await client.customer.passwordResets.update(
+```typescript Store SDK
+const { token, user } = await client.passwordResets.update(
'reset-token-from-email',
{
password: 'newsecurepassword',
@@ -167,7 +190,7 @@ const { token, user } = await client.customer.passwordResets.update(
```
```bash cURL
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer/password_resets/RESET_TOKEN' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/password_resets/RESET_TOKEN' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
@@ -190,7 +213,7 @@ Headless storefronts often need to collect newsletter signups before account cre
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
await client.newsletterSubscribers.create({
redirect_url: 'https://myshop.com/newsletter/confirm',
@@ -210,7 +233,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/newsletter_subscribers' \
</CodeGroup>
-The optional `redirect_url` points at the storefront page that will receive the verification token. It is validated against the store's [Allowed Origins](/developer/core-concepts/allowed-origins) — URLs that do not match are silently dropped from the webhook payload (secure-by-default).
+The optional `redirect_url` points at the storefront page that will receive the verification token. It is validated against the store's Allowed Origins — URLs that do not match are silently dropped from the webhook payload (secure-by-default).
This fires a `newsletter_subscriber.subscription_requested` event whose payload includes `email`, `verification_token`, and the validated `redirect_url`. Subscribe to this event from your storefront's webhook handler to send the confirmation email — the link in the email should point to `<redirect_url>?token=<verification_token>`. The bundled `spree_emails` package also listens to this event and sends a default confirmation email if you're not running a headless storefront.
@@ -220,7 +243,7 @@ If the request is authenticated via a customer JWT and the JWT's email matches t
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
await client.newsletterSubscribers.verify({
token: 'token-from-email',
})
@@ -242,11 +265,11 @@ On success, the subscriber is marked verified. If the subscription is linked to
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Get current customer
const customer = await client.customer.get()
// {
-// id: "usr_xxx",
+// id: "cus_xxx",
// email: "[email protected]",
// first_name: "John",
// last_name: "Doe",
@@ -264,11 +287,13 @@ const updated = await client.customer.update({
```bash cURL
# Get current customer
-curl 'https://api.mystore.com/api/v3/store/customer' \
+curl 'https://api.mystore.com/api/v3/store/customers/me' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>'
# Update profile
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me' \
+ -H 'X-Spree-API-Key: pk_xxx' \
-H 'Authorization: Bearer <jwt_token>' \
-H 'Content-Type: application/json' \
-d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
@@ -296,6 +321,7 @@ Customers don't need to register to purchase. Guest checkout uses an order token
## Related Documentation
+- [Account (Store SDK)](/developer/sdk/store/account) — Task-oriented walkthrough of registration, login, profile, addresses, and order history
- [Addresses](/developer/core-concepts/addresses) — Customer address management
- [Orders](/developer/core-concepts/orders) — Order history and checkout
- [Authentication](/developer/customization/authentication) — Custom authentication setup
diff --git a/docs/developer/core-concepts/events.mdx b/docs/developer/core-concepts/events.mdx
index 3f9cec3d09..cb06b4b4d3 100644
--- a/docs/developer/core-concepts/events.mdx
+++ b/docs/developer/core-concepts/events.mdx
@@ -166,7 +166,7 @@ def handle(event)
event.name # => "order.completed"
event.store_id # => 1 (ID of the store where the event originated)
event.payload # => { "id" => 1, "number" => "R123456", ... }
- event.metadata # => { "spree_version" => "5.1.0" }
+ event.metadata # => { "spree_version" => "<spree_version>" }
event.created_at # => Time when event was published
# Helper methods
@@ -248,13 +248,15 @@ Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Ship
| `price.updated` | Price was updated |
| `price.deleted` | Price was deleted |
-### Customer Events
+### User Events
| Event | Description |
|-------|-------------|
-| `customer.created` | Customer was created |
-| `customer.updated` | Customer was updated |
-| `customer.deleted` | Customer was deleted |
+| `user.created` | User was created |
+| `user.updated` | User was updated |
+| `user.deleted` | User was deleted |
+
+When `Spree.admin_user_class` differs from `Spree.user_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).
### Admin Events
@@ -268,8 +270,8 @@ Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Ship
| Event | Description |
|-------|-------------|
-| `product.activate` | Product status changed to active |
-| `product.archive` | Product status changed to archived |
+| `product.activated` | Product status changed to active |
+| `product.archived` | Product status changed to archived |
| `product.out_of_stock` | Product has no stock left for any variant |
| `product.back_in_stock` | Product was out of stock and now has stock again |
@@ -303,7 +305,7 @@ Spree::Events.publish(
## Event Serializers
-Event payloads are generated using the same [Store API V3 serializers](/api-reference/introduction) used by the REST API. This means webhook payloads and API responses share the same schema, making it easy to reuse types in your integrations.
+Event payloads are generated using the same [Store API V3 serializers](/api-reference/store-api/introduction) used by the REST API. This means webhook payloads and API responses share the same schema, making it easy to reuse types in your integrations.
### How Serializers Work
@@ -349,7 +351,7 @@ This means event payloads contain the same top-level attributes and unconditiona
### Overriding Event Serializers
-To customize the payload for existing events, create a custom V3 serializer and configure it via dependencies:
+To customize the payload for existing events, create a custom V3 serializer and configure it via [dependencies](/developer/customization/dependencies):
```ruby app/serializers/my_app/order_serializer.rb
module MyApp
@@ -497,7 +499,7 @@ end
### Testing Event Publishing
-Use the `emit_webhook_event` matcher (if available) or stub the events:
+Stub `Spree::Events.publish` to assert an event is published:
```ruby
it 'publishes order.completed event' do
@@ -510,6 +512,8 @@ it 'publishes order.completed event' do
end
```
+The `lifecycle events` shared examples in `spree/core/lib/spree/testing_support/lifecycle_events.rb` cover the standard `created`/`updated`/`deleted` lifecycle events.
+
## Best Practices
<CardGroup cols={2}>
@@ -543,7 +547,7 @@ class InventoryAlertSubscriber < Spree::Subscriber
def handle(event)
stock_item = find_stock_item(event)
return unless stock_item
- return unless stock_dropped_below_threshold?(event, stock_item)
+ return unless low_stock?(event)
send_low_stock_alert(stock_item)
end
@@ -554,11 +558,8 @@ class InventoryAlertSubscriber < Spree::Subscriber
Spree::StockItem.find_by_prefix_id(event.payload['id'])
end
- def stock_dropped_below_threshold?(event, stock_item)
- previous_count = event.payload['count_on_hand_before_last_save']
- current_count = stock_item.count_on_hand
-
- previous_count >= LOW_STOCK_THRESHOLD && current_count < LOW_STOCK_THRESHOLD
+ def low_stock?(event)
+ event.payload['count_on_hand'].to_i < LOW_STOCK_THRESHOLD
end
def send_low_stock_alert(stock_item)
@@ -571,6 +572,10 @@ class InventoryAlertSubscriber < Spree::Subscriber
end
```
+<Note>
+A lifecycle event payload carries only the resource's current serialized state, not its previous values. If you need a true "just dropped below the threshold" check that compares the count before and after the change, record or cache the prior count separately rather than reading it from the event payload.
+</Note>
+
## Custom Event Adapters
Spree's event system uses an adapter pattern, making it possible to swap the underlying event infrastructure. By default, Spree uses [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html), but you can create custom adapters for other backends like Kafka, RabbitMQ, or Redis Pub/Sub.
@@ -643,7 +648,7 @@ The `Spree::Events::Adapters::Base` class defines the required interface:
The base class also provides helper methods:
- `build_event(name, payload, metadata)` - Creates a `Spree::Event` instance
-- `subscriptions_for(event_name)` - Finds matching subscriptions from the registry
+- `invoke_subscribers(event)` - Finds and invokes matching subscribers (internally calling `registry.subscriptions_for`)
- `registry` - Access to the `Spree::Events::Registry` instance
<Info>
@@ -652,7 +657,9 @@ See `Spree::Events::Adapters::ActiveSupportNotifications` for a complete referen
## Related Documentation
+- [Events Tutorial](/developer/tutorial/events) - Hands-on, step-by-step walkthrough of building an event subscriber
- [Webhooks](/developer/core-concepts/webhooks) - HTTP callbacks for external integrations
+- [Webhooks & Events Reference](/api-reference/webhooks-events) - Catalog of event and webhook payloads
- [Customization Quickstart](/developer/customization/quickstart) - Overview of all customization options
- [Decorators](/developer/customization/decorators) - When to use decorators vs events
- [Checkout Flow](/developer/customization/checkout) - Using events in checkout customization
diff --git a/docs/developer/core-concepts/imports-exports.mdx b/docs/developer/core-concepts/imports-exports.mdx
index ce286c464f..2c9d83454f 100644
--- a/docs/developer/core-concepts/imports-exports.mdx
+++ b/docs/developer/core-concepts/imports-exports.mdx
@@ -42,7 +42,7 @@ erDiagram
Export {
string number
string type
- string format
+ integer format
jsonb search_params
}
@@ -80,10 +80,12 @@ Exports generate CSV files from filtered database records.
| Type | Description | Multi-line |
|------|-------------|------------|
| `Spree::Exports::Products` | Products with all variants | Yes |
+| `Spree::Exports::ProductTranslations` | Product translations for non-default store locales | Yes |
| `Spree::Exports::Orders` | Orders with line items | Yes |
| `Spree::Exports::Customers` | Customer accounts | No |
| `Spree::Exports::GiftCards` | Gift cards | No |
| `Spree::Exports::NewsletterSubscribers` | Newsletter subscribers | No |
+| `Spree::Exports::CouponCodes` | Promotion coupon codes | No |
### Export Model
@@ -219,7 +221,7 @@ end
### Export Filtering
-Exports support Ransack filtering via `search_params`:
+Exports support [Ransack filtering via `search_params`](/api-reference/admin-api/querying):
```ruby
# In admin, users can filter before exporting
@@ -242,6 +244,8 @@ Imports process CSV files to create or update database records.
| Type | Description |
|------|-------------|
| `Spree::Imports::Products` | Products and variants |
+| `Spree::Imports::ProductTranslations` | Product translations (matched by slug) |
+| `Spree::Imports::Customers` | Customers |
### Import Workflow
@@ -538,7 +542,7 @@ The products import handles variants intelligently:
```csv
slug,sku,name,price,option1_name,option1_value,option2_name,option2_value
-my-tshirt,TSHIRT-001,My T-Shirt,29.99,,,
+my-tshirt,TSHIRT-001,My T-Shirt,29.99,,,,
my-tshirt,TSHIRT-S-RED,My T-Shirt,29.99,Size,Small,Color,Red
my-tshirt,TSHIRT-M-RED,My T-Shirt,29.99,Size,Medium,Color,Red
my-tshirt,TSHIRT-L-RED,My T-Shirt,29.99,Size,Large,Color,Red
@@ -560,16 +564,16 @@ Both imports and exports support metafields dynamically:
Parses CSV and creates ImportRow records:
+All import jobs inherit from `Spree::Imports::BaseJob`, which sets `queue_as Spree.queues.imports` once and is shared across the pipeline.
+
```ruby
module Spree
module Imports
- class CreateRowsJob < Spree::BaseJob
- queue_as Spree.queues.imports
-
+ class CreateRowsJob < Spree::Imports::BaseJob
def perform(import_id)
import = Spree::Import.find(import_id)
# Stream CSV, batch insert rows
- # Then enqueue ProcessRowsJob
+ # Then enqueue ProcessRowsJob via import.process_rows_async
end
end
end
@@ -578,20 +582,64 @@ end
### ProcessRowsJob
-Processes pending rows through row processors:
+Fans the pending rows out into groups, each processed by a separate `ProcessGroupJob`:
```ruby
module Spree
module Imports
- class ProcessRowsJob < Spree::BaseJob
- queue_as Spree.queues.imports
+ class ProcessRowsJob < Spree::Imports::BaseJob
+ BATCH_SIZE = 100
def perform(import_id)
import = Spree::Import.find(import_id)
- import.rows.pending_and_failed.find_each do |row|
- row.process!
+ dispatch_groups(import)
+ end
+
+ private
+
+ def dispatch_groups(import)
+ # When the import defines a group_column (e.g. ProductTranslations groups
+ # by slug) and that field is mapped, group rows by the column value.
+ # Otherwise, fall back to slicing pending_and_failed rows into batches of
+ # BATCH_SIZE. Either way: pluck the row IDs, set processing_groups_count /
+ # completed_groups_count up front so workers can't complete prematurely,
+ # then enqueue one ProcessGroupJob per group.
+ import.rows.pending_and_failed.in_batches(of: BATCH_SIZE) do |batch|
+ ProcessGroupJob.perform_later(import.id, batch.ids)
end
- import.complete!
+ end
+ end
+ end
+end
+```
+
+### ProcessGroupJob
+
+Processes one group of rows and reports completion:
+
+```ruby
+module Spree
+ module Imports
+ class ProcessGroupJob < Spree::Imports::BaseJob
+ def perform(import_id, row_ids)
+ import = Spree::Import.find(import_id)
+ rows = import.rows.where(id: row_ids).pending_and_failed
+
+ # Large imports process with events disabled and use bulk_process!;
+ # otherwise each row is processed individually via row.process!.
+ rows.each { |row| row.process! }
+
+ check_import_completion(import)
+ end
+
+ private
+
+ # Increments completed_groups_count, then completes the import only once the
+ # last group has finished and no rows are still in flight.
+ def check_import_completion(import)
+ # completed_groups_count += 1
+ import.complete! if import.completed_groups_count >= import.processing_groups_count &&
+ import.rows.in_flight.none?
end
end
end
@@ -609,7 +657,7 @@ module Spree
queue_as Spree.queues.exports
def perform(export_id)
- export = Spree::Export.find(export_id)
+ export = Spree::Export.find_by_prefix_id!(export_id)
export.generate
end
end
@@ -621,6 +669,8 @@ end
## Events
+Import and export lifecycle events such as [`import.completed` and `export.created`](/api-reference/webhooks-events) can be delivered as webhooks to react when an asynchronous import or export finishes.
+
### Import Events
| Event | Trigger |
@@ -696,3 +746,8 @@ can :manage, Spree::Export
```
Records are filtered by `current_ability` ensuring users only export data they have access to.
+
+## Related Documentation
+
+- [Admin imports/exports endpoints](/api-reference/admin-api/endpoints) — REST routes and required scopes to trigger imports and exports programmatically.
+- [Admin SDK resources](/developer/sdk/admin/resources) — typed TypeScript client for driving these back-office operations.
diff --git a/docs/developer/core-concepts/inventory.mdx b/docs/developer/core-concepts/inventory.mdx
index f496a3f72f..93171db70c 100644
--- a/docs/developer/core-concepts/inventory.mdx
+++ b/docs/developer/core-concepts/inventory.mdx
@@ -115,6 +115,40 @@ Stock Locations can be easily used for tracking warehouses and other physical lo
You can easily use them with your Point of Sale (POS) system to track inventory at different locations.
+Create and manage stock locations via the [Admin API](/api-reference/admin-api/introduction):
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const location = await client.stockLocations.create({
+ name: 'Warehouse 1',
+ admin_name: 'WH1 Domestic',
+ default: true,
+ country_iso: 'US',
+ propagate_all_variants: true,
+})
+
+await client.stockLocations.update('sloc_xxx', { active: false })
+```
+
+```bash CLI
+spree api post /stock_locations -d '{
+ "name": "Warehouse 1",
+ "default": true,
+ "country_iso": "US",
+ "propagate_all_variants": true
+}'
+```
+
+</CodeGroup>
+
### Stock Items
Stock Items represent the inventory at a stock location for a specific variant. Stock item count on hand can be increased or decreased by creating stock movements.
@@ -126,6 +160,27 @@ Stock Items represent the inventory at a stock location for a specific variant.
| `count_on_hand` | The number of items available on hand. | `150` |
| `backorderable` | Indicates whether the stock item can be backordered. | `true` |
+Stock items are created automatically — for all variants when a location has `propagate_all_variants`, or via a variant's `stock_items` on create. To adjust quantity or backorderable status, **update** the existing stock item via the Admin API. The example below uses a Ransack predicate (`stock_location_id_eq`) to [list a location's stock items](/api-reference/admin-api/querying) before updating one:
+
+<CodeGroup>
+
+```typescript Admin SDK
+// List a location's stock items, then adjust one
+const { data: items } = await client.stockItems.list({ stock_location_id_eq: 'sloc_xxx' })
+
+await client.stockItems.update('si_xxx', {
+ count_on_hand: 150,
+ backorderable: true,
+})
+```
+
+```bash CLI
+spree api get /stock_items -q stock_location_id_eq=sloc_xxx
+spree api patch /stock_items/si_xxx -d '{"count_on_hand": 150, "backorderable": true}'
+```
+
+</CodeGroup>
+
### Stock Transfers
Stock transfers allow you to move inventory in bulk from one stock location to another stock location. This is handy when you want to integrate with a POS system or other inventory management system. Or you can just rely on Spree being the source of truth for your inventory.
@@ -143,6 +198,32 @@ Here's the list of attributes for the Stock Transfer model:
| `source_location_id` | The ID of the stock location where the stock is transferred from. | `2` |
| `destination_location_id`| The ID of the stock location where the stock is transferred to. | `3` |
+Create a transfer via the [Admin API](/api-reference/admin-api/introduction), listing the variants and quantities to move. Omit `source_location_id` to record an incoming receipt from a vendor:
+
+<CodeGroup>
+
+```typescript Admin SDK
+const transfer = await client.stockTransfers.create({
+ source_location_id: 'sloc_warehouse',
+ destination_location_id: 'sloc_store',
+ reference: 'Transfer for Event',
+ variants: [
+ { variant_id: 'variant_xxx', quantity: 20 },
+ { variant_id: 'variant_yyy', quantity: 5 },
+ ],
+})
+```
+
+```bash CLI
+spree api post /stock_transfers -d '{
+ "source_location_id": "sloc_warehouse",
+ "destination_location_id": "sloc_store",
+ "variants": [{ "variant_id": "variant_xxx", "quantity": 20 }]
+}'
+```
+
+</CodeGroup>
+
Stock transfers are crucial for managing inventory across multiple locations, ensuring that stock levels are accurate and up-to-date.
Each Stock Transfer will hold a list of Stock Movements.
@@ -193,7 +274,7 @@ Reservations attach to each line item; when a line item or order is removed, the
|---|---|---|
| `Spree::Config[:stock_reservations_enabled]` | `true` | Global kill switch. When `false`, reservations are not created and availability ignores them — behavior matches pre-5.5. |
| `Spree::Config[:default_stock_reservation_ttl_minutes]` | `10` | Fallback hold duration when a Store doesn't override. |
-| `store.preferred_stock_reservation_ttl_minutes` | inherits global | Per-Store override. |
+| `store.preferred_stock_reservation_ttl_minutes` | `10` | Per-Store override. Falls back to the global default only when explicitly unset/blank. |
TTL is a Store-level setting — it's a checkout-experience policy, not a warehouse property. A multi-location cart never has to merge conflicting TTLs from different warehouses.
@@ -232,6 +313,7 @@ Inventory Units states are:
* `on_hand` - the inventory unit is on hand
* `backordered` - the inventory unit is backordered
* `shipped` - the inventory unit is shipped
+* `returned` - the inventory unit has been returned
<Note>
As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Admin API), the first Inventory Units to fulfill are the backordered ones.
@@ -249,3 +331,5 @@ If you don't need to track inventory, you can disable it:
- [Products](/developer/core-concepts/products) - Product and variant management
- [Shipments](/developer/core-concepts/shipments) - How inventory relates to shipments
- [Orders](/developer/core-concepts/orders) - How inventory is allocated to orders
+- [Admin SDK resources](/developer/sdk/admin/resources) - `stockLocations`, `stockItems`, and `stockTransfers` methods used in the examples above
+- [Admin API authentication](/api-reference/admin-api/authentication) - How to obtain and scope the secret key (`sk_xxx`) used by these calls
diff --git a/docs/developer/core-concepts/markets.mdx b/docs/developer/core-concepts/markets.mdx
index ce21e405b9..8771f5e295 100644
--- a/docs/developer/core-concepts/markets.mdx
+++ b/docs/developer/core-concepts/markets.mdx
@@ -76,7 +76,7 @@ Fetch all markets for the current store, including their countries:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: markets } = await client.markets.list()
// [
// {
@@ -96,6 +96,10 @@ const { data: markets } = await client.markets.list()
// ]
```
+```typescript Admin SDK
+const { data: markets } = await adminClient.markets.list()
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/markets' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -109,7 +113,7 @@ When you know a customer's country (e.g., from geolocation or a country picker),
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const market = await client.markets.resolve('DE')
// { id: "mkt_gbHJdmfr", name: "Europe", currency: "EUR", tax_inclusive: true, ... }
```
@@ -131,7 +135,7 @@ List countries belonging to a specific market. Useful for populating address for
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: countries } = await client.markets.countries.list('mkt_k5nR8xLq')
// [
// { iso: "CA", name: "Canada", states_required: true, zipcode_required: true },
@@ -140,7 +144,7 @@ const { data: countries } = await client.markets.countries.list('mkt_k5nR8xLq')
// Get a country with its states (for address form dropdowns)
const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {
- include: 'states',
+ expand: ['states'],
})
```
@@ -160,15 +164,21 @@ You can also fetch countries flat (across all markets) or include the market on
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// All countries across all markets
const { data: countries } = await client.countries.list()
// Get a country with its market details
-const germany = await client.countries.get('DE', { include: 'market' })
+const germany = await client.countries.get('DE', { expand: ['market'] })
// { iso: "DE", name: "Germany", market: { currency: "EUR", default_locale: "de", tax_inclusive: true } }
```
+```typescript Admin SDK
+const { data: countries } = await adminClient.countries.list()
+
+const germany = await adminClient.countries.get('DE')
+```
+
```bash cURL
# All countries across all markets
curl 'https://api.mystore.com/api/v3/store/countries' \
@@ -183,13 +193,13 @@ curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
## Currency and Locale
-Each market defines a currency and set of supported locales. When a market is resolved, its currency and locale become the defaults for the session.
+Each market defines a [currency and set of supported locales](/api-reference/store-api/monetary-amounts). When a market is resolved, its currency and locale become the defaults for the session.
You can discover all available currencies and locales (aggregated from all markets) via dedicated endpoints:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: currencies } = await client.currencies.list()
// [{ iso_code: "USD", name: "US Dollar", symbol: "$" }, { iso_code: "EUR", name: "Euro", symbol: "€" }]
@@ -232,31 +242,69 @@ See [Pricing — Price Rules](/developer/core-concepts/pricing#price-rules) for
Markets are managed in the admin dashboard under **Settings → Markets**. When you run `rails db:seed`, Spree automatically creates a default market for each store.
-To create markets programmatically:
+To create markets programmatically, use the [Admin API](/api-reference/admin-api/introduction). See the [Admin API endpoints](/api-reference/admin-api/endpoints) for the full list of `/markets` routes and required scopes:
+
+<CodeGroup>
-```ruby
-# North America market
-current_store.markets.create!(
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+// North America market (countries by ISO code)
+const northAmerica = await client.markets.create({
name: 'North America',
currency: 'USD',
default_locale: 'en',
- countries: [usa, canada],
- default: true
-)
+ country_isos: ['US', 'CA'],
+ default: true,
+})
-# Europe market with tax-inclusive pricing
-current_store.markets.create!(
+// Europe market with tax-inclusive pricing
+const europe = await client.markets.create({
name: 'Europe',
currency: 'EUR',
default_locale: 'de',
- supported_locales: 'de,en,fr',
+ supported_locales: ['de', 'en', 'fr'],
tax_inclusive: true,
- countries: [germany, france, austria, netherlands]
-)
+ country_isos: ['DE', 'FR', 'AT', 'NL'],
+})
```
+```bash CLI
+spree api post /markets -d '{
+ "name": "North America",
+ "currency": "USD",
+ "default_locale": "en",
+ "country_isos": ["US", "CA"],
+ "default": true
+}'
+```
+
+</CodeGroup>
+
+Update or remove a market the same way:
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.markets.update('market_xxx', { tax_inclusive: true })
+await client.markets.delete('market_xxx')
+```
+
+```bash CLI
+spree api patch /markets/market_xxx -d '{"tax_inclusive": true}'
+spree api delete /markets/market_xxx
+```
+
+</CodeGroup>
+
## Related Documentation
+- [Markets (Store SDK)](/developer/sdk/store/markets) — Listing, resolving, and reading markets from the Store SDK
- [Stores](/developer/core-concepts/stores) — Multi-store setup and configuration
- [Pricing](/developer/core-concepts/pricing) — Price Lists, Price Rules, and the Pricing Context
- [Addresses](/developer/core-concepts/addresses) — Countries, States, and Zones
diff --git a/docs/developer/core-concepts/media.mdx b/docs/developer/core-concepts/media.mdx
index 752db93a01..9380d3f6aa 100644
--- a/docs/developer/core-concepts/media.mdx
+++ b/docs/developer/core-concepts/media.mdx
@@ -56,6 +56,35 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/medi
</CodeGroup>
+#### Creating media from a remote URL
+
+When the image already lives at a public URL, pass `url` instead of a `signed_id` — Spree fetches the remote file and stores it as product media, so you skip the direct-upload step entirely.
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.products.media.create('prod_86Rf07xd4z', {
+ url: 'https://cdn.example.com/images/tote-front.jpg',
+ position: 1,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "url": "https://cdn.example.com/images/tote-front.jpg",
+ "position": 1
+ }'
+```
+
+</CodeGroup>
+
+<Note>
+The fetch runs in the background, so this request returns `202 Accepted` with no body — the media appears in the gallery once the download and processing finish. Re-fetch the product's media to know when it's ready.
+</Note>
+
#### Sharing a single image across variants
Pass a `variant_ids` array on the same media endpoint to link/unlink variants. The server replaces the asset's link set on every call — empty array clears all links, omitting the field leaves them untouched.
@@ -103,11 +132,11 @@ All variants are cropped to fill the exact dimensions and converted to WebP form
### Thumbnails (Always Available)
-Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail` URL and a `media_count` counter.
+Every product response includes a `thumbnail_url` field — ready to use without any expands. Similarly, each variant includes a `thumbnail_url` and a `media_count` counter.
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List products — thumbnail_url is always included
const { data: products } = await client.products.list({ limit: 12 })
@@ -116,6 +145,10 @@ products.forEach(product => {
})
```
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({ limit: 12 })
+```
+
```bash cURL
# thumbnail_url is always in the response — no ?expand needed
curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
@@ -130,11 +163,11 @@ Avoid using `?expand=media` on listing pages. This loads **all** media for every
### Full Media (On Demand)
-On the product detail page, expand `media` and `variants` to get the full set of media with all named variant URLs:
+On the product detail page, [expand media and variants](/api-reference/store-api/relations) to get the full set of media with all named variant URLs:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const product = await client.products.get('spree-tote', {
expand: ['media', 'variants'],
})
@@ -144,12 +177,18 @@ product.media // [{ id, media_type, product_id, variant_ids, original_url, mini_
// Each variant has its own thumbnail and media_count
product.variants?.forEach(variant => {
- variant.thumbnail // "https://cdn.../tote-red.webp" — always available
+ variant.thumbnail_url // "https://cdn.../tote-red.webp" — present in the response, null when the variant has no media
variant.media_count // 3 — quick check without loading media
variant.media // full media array (only with ?expand=media)
})
```
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+ expand: ['media', 'variants'],
+})
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -184,7 +223,7 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
| Field | Available on | Always Returned | Description |
|-------|-------------|:---:|-------------|
| `thumbnail_url` | Product | Yes | URL to the product's first media |
-| `thumbnail` | Variant | Yes | URL to the variant's first media |
+| `thumbnail_url` | Variant | Yes | URL to the variant's first media |
| `media_count` | Variant | Yes | Number of media items (counter cache) |
| `media` | Product, Variant | No | Full media array (requires `?expand=media`) |
@@ -236,4 +275,6 @@ For production deployments, use cloud storage (S3, GCS, Azure) instead of local
## Related Documentation
- [Products](/developer/core-concepts/products) — Product catalog and media
+- [Products & Categories](/developer/sdk/store/products) — Store SDK guide for fetching products, `thumbnail_url`, and expanded media
+- [Admin SDK](/developer/sdk/admin/resources) — Admin SDK resource methods, including the nested `products.media` create/update calls
- [Deployment — Assets](/developer/deployment/assets) — Storage and CDN configuration
diff --git a/docs/developer/core-concepts/metafields.mdx b/docs/developer/core-concepts/metafields.mdx
index 55de8aed5f..273c5592a2 100644
--- a/docs/developer/core-concepts/metafields.mdx
+++ b/docs/developer/core-concepts/metafields.mdx
@@ -3,9 +3,13 @@ title: Metafields
description: Add custom structured data to products, orders, and other resources with type-safe metafields
---
+import { Since } from '/snippets/since.mdx';
+
+<Since version="5.2" />
+
## Overview
-Metafields provide a flexible, type-safe system for adding custom structured data to Spree resources. Unlike [metadata](/developer/customization/metadata) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
+Metafields provide a flexible, type-safe system for adding custom structured attributes to Spree models. Unlike [metadata](/developer/customization/metadata) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
Use metafields for:
@@ -14,10 +18,6 @@ Use metafields for:
- Integration data from external systems
- Order-specific custom attributes
-<Note>
-Metafields are available from Spree 5.2 onwards.
-</Note>
-
## Architecture
```mermaid
@@ -77,12 +77,11 @@ flowchart LR
## Visibility Control
-Metafields support three visibility levels via the `display_on` attribute:
+Metafields support two visibility levels via the `display_on` attribute:
| Visibility | Store API | Admin API | Use Case |
|------------|:---------:|:---------:|----------|
| `both` | Yes | Yes | Public product specifications |
-| `front_end` | Yes | No | Customer-facing data |
| `back_end` | No | Yes | Internal notes, integration IDs |
## Supported Resources
@@ -110,11 +109,15 @@ Namespace and key are automatically normalized to snake_case.
## Store API
-Metafields with `display_on` set to `both` or `front_end` are included in Store API responses when you request the `custom_fields` expand:
+Metafields with `display_on` set to `both` are included in Store API responses when you [request the `custom_fields` expand](/api-reference/store-api/relations):
+
+<Info>
+ Metafields in API are called Custom Fields as we plan to rename Metafields to Custom Fields completely in Spree 6.0.
+</Info>
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const product = await client.products.get('spree-tote', {
expand: ['custom_fields'],
})
@@ -122,8 +125,14 @@ const product = await client.products.get('spree-tote', {
product.custom_fields?.forEach(field => {
console.log(field.key) // "properties.manufacturer"
console.log(field.label) // "Manufacturer"
- console.log(field.value) // "Wilson"
- console.log(field.type) // "short_text"
+ console.log(field.value) // "Wilson"
+ console.log(field.field_type) // "short_text"
+})
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+ expand: ['custom_fields'],
})
```
@@ -145,14 +154,14 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fie
"id": "cf_k5nR8xLq",
"label": "Manufacturer",
"key": "properties.manufacturer",
- "type": "short_text",
+ "field_type": "short_text",
"value": "Wilson"
},
{
"id": "cf_m3Rp9wXz",
"label": "Material",
"key": "properties.material",
- "type": "short_text",
+ "field_type": "short_text",
"value": "100% Cotton"
}
]
@@ -163,16 +172,74 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fie
The `display_on` attribute is intentionally excluded from Store API responses for security.
</Note>
-## Admin Panel Management
+## Admin Management
### Managing Definitions
Navigate to **Settings → Metafield Definitions** in the Admin Panel to create and manage metafield definitions. Select the resource type, enter namespace and key, choose the data type, and set visibility.
+Definitions are also [managed via the Admin API](/api-reference/admin-api/endpoints). `storefront_visible: true` is equivalent to `display_on: both` — it exposes the field to the Store API:
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const definition = await client.customFieldDefinitions.create({
+ resource_type: 'Spree::Product',
+ namespace: 'properties',
+ key: 'manufacturer',
+ label: 'Manufacturer',
+ field_type: 'short_text',
+ storefront_visible: true,
+})
+
+await client.customFieldDefinitions.update(definition.id, { storefront_visible: false })
+await client.customFieldDefinitions.delete(definition.id)
+```
+
+```bash CLI
+spree api post /custom_field_definitions -d '{
+ "resource_type": "Spree::Product",
+ "namespace": "properties",
+ "key": "manufacturer",
+ "label": "Manufacturer",
+ "field_type": "short_text",
+ "storefront_visible": true
+}'
+```
+
+</CodeGroup>
+
### Managing Values
When editing a resource (e.g., a product), metafields appear in a dedicated section. The admin panel automatically builds forms for all defined metafields.
+To set a value programmatically, use the resource's nested `customFields` accessor (parent ID first):
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.products.customFields.create('prod_xxx', {
+ custom_field_definition_id: 'cfdef_xxx',
+ value: 'Wilson',
+})
+```
+
+```bash CLI
+spree api post /products/prod_xxx/custom_fields -d '{
+ "custom_field_definition_id": "cfdef_xxx",
+ "value": "Wilson"
+}'
+```
+
+</CodeGroup>
+
## Metafields vs Metadata
Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**. They serve different purposes and are not interchangeable. Neither is going away.
@@ -193,7 +260,7 @@ Spree has two permanent, complementary systems for custom data — **metadata fo
**Use [Metadata](/developer/customization/metadata)** for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
<Warning>
-Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties).
+Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the [migration guide](/developer/upgrades/5.1-to-5.2#migrate-to-metafields-or-keep-using-product-properties).
</Warning>
## Related Documentation
@@ -201,3 +268,4 @@ Product Properties are deprecated and will be removed in Spree 6.0. For new proj
- [Metadata](/developer/customization/metadata) — Simple key-value metadata
- [Products](/developer/core-concepts/products) — Product catalog
- [Events](/developer/core-concepts/events) — Subscribe to metafield events
+- [Admin SDK](/developer/sdk/admin/resources) — Manage definitions and values from TypeScript
diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdx
index 33a37f302f..e6f17ba9a1 100644
--- a/docs/developer/core-concepts/orders.mdx
+++ b/docs/developer/core-concepts/orders.mdx
@@ -62,29 +62,28 @@ The API returns these key fields on every order:
| Attribute | Description |
|-----------|-------------|
| `number` | Unique order number (e.g., `R123456789`), shown to customers |
-| `state` | Current checkout state (`cart`, `address`, `delivery`, `payment`, `confirm`, `complete`) |
| `email` | Customer's email address |
| `currency` | Order currency (e.g., `USD`) |
-| `item_count` | Total number of items |
+| `total_quantity` | Total number of items |
| `item_total` / `display_item_total` | Sum of line item prices |
| `delivery_total` / `display_delivery_total` | Delivery cost |
| `tax_total` / `display_tax_total` | Total tax |
-| `promo_total` / `display_promo_total` | Total discount from promotions |
+| `discount_total` / `display_discount_total` | Total discount from promotions |
| `adjustment_total` / `display_adjustment_total` | Sum of all adjustments (tax + delivery + promos) |
| `total` / `display_total` | Final order total |
-| `payment_state` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
+| `payment_status` | Payment status (`balance_due`, `paid`, `credit_owed`, `failed`, `void`) |
| `fulfillment_status` | Fulfillment status (`pending`, `ready`, `partial`, `shipped`, `backorder`) |
| `completed_at` | Timestamp when the order was placed |
-The `display_*` fields return formatted strings with currency symbols (e.g., `"$15.99"`).
+The [`display_*` fields return formatted strings with currency symbols](/api-reference/store-api/monetary-amounts) (e.g., `"$15.99"`).
## Cart
-A cart is simply an order in the `cart` state. Guest carts are identified by a cart token; authenticated users' carts are linked to their account.
+A cart is simply an order in the `cart` state. Guest carts are [identified by a cart token; authenticated users' carts are linked to their account](/api-reference/store-api/authentication).
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Create a cart
const cart = await client.carts.create()
// cart.token => "abc123" (save this for guest checkout)
@@ -170,21 +169,21 @@ If the order doesn't meet the requirements for the next state (e.g., missing add
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Set addresses
await client.carts.update(cartId, {
- ship_address: {
- firstname: 'John', lastname: 'Doe',
+ shipping_address: {
+ first_name: 'John', last_name: 'Doe',
address1: '123 Main St', city: 'Los Angeles',
- country_iso: 'US', state_abbr: 'CA', zipcode: '90001',
+ country_iso: 'US', state_abbr: 'CA', postal_code: '90001',
phone: '555-0100',
},
})
// Get fulfillments and select a delivery rate
// (the Store API/SDK exposes shipments as `fulfillments`)
-const cart = await client.carts.get(cartId, { expand: ['fulfillments'] })
+const cart = await client.carts.get(cartId)
await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
selected_delivery_rate_id: 'rate_xxx',
})
@@ -210,10 +209,10 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
- "ship_address": {
- "firstname": "John", "lastname": "Doe",
+ "shipping_address": {
+ "first_name": "John", "last_name": "Doe",
"address1": "123 Main St", "city": "Los Angeles",
- "country_iso": "US", "state_abbr": "CA", "zipcode": "90001",
+ "country_iso": "US", "state_abbr": "CA", "postal_code": "90001",
"phone": "555-0100"
}
}'
@@ -239,7 +238,7 @@ Apply or remove promotional coupon codes during checkout:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Apply a discount code
await client.carts.discountCodes.apply(cartId, 'SAVE20')
@@ -269,7 +268,7 @@ Authenticated customers can view their past orders:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List past orders
const { data: orders } = await client.customer.orders.list()
@@ -279,6 +278,10 @@ const order = await client.orders.get('or_xxx', {
})
```
+```typescript Admin SDK
+const order = await adminClient.orders.get('or_xxx')
+```
+
```bash cURL
# List past orders
curl 'https://api.mystore.com/api/v3/store/customer/orders' \
@@ -291,6 +294,86 @@ curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,fulfillmen
</CodeGroup>
+## Managing Orders
+
+Everything above is the **Store API** — the customer's own cart and orders. Back-office order management (listing every order, creating phone/manual orders, capturing payments, cancelling) uses the [Admin API](/api-reference/admin-api/introduction).
+
+### Listing and creating orders
+
+List orders with [Ransack filters and pagination](/api-reference/admin-api/querying) (`state_eq`, `limit`, sorting). A draft order is created in one call; pass line items as `items` (each `{ variant_id, quantity }`):
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+// List orders (Ransack filters)
+const { data: orders } = await client.orders.list({ state_eq: 'complete', limit: 25 })
+
+// Create a draft order on a customer's behalf
+const order = await client.orders.create({
+ email: '[email protected]',
+ items: [{ variant_id: 'variant_xxx', quantity: 2 }],
+ currency: 'USD',
+})
+```
+
+```bash CLI
+spree api get /orders -q state_eq=complete --limit 25
+spree api post /orders -d '{
+ "email": "[email protected]",
+ "items": [{ "variant_id": "variant_xxx", "quantity": 2 }]
+}'
+```
+
+</CodeGroup>
+
+### Order state actions
+
+Orders move through their [state machine](#checkout-flow) via dedicated actions rather than raw `state` writes:
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.orders.complete('or_xxx') // finalize a draft
+await client.orders.cancel('or_xxx', { reason: 'customer' })
+await client.orders.approve('or_xxx')
+await client.orders.resume('or_xxx')
+await client.orders.resendConfirmation('or_xxx')
+```
+
+```bash CLI
+spree api patch /orders/or_xxx/complete
+spree api patch /orders/or_xxx/cancel -d '{"reason": "customer"}'
+spree api patch /orders/or_xxx/approve
+```
+
+</CodeGroup>
+
+### Payments and refunds
+
+Capture or void an authorized payment, and issue refunds, through the nested order resources:
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.orders.payments.capture('or_xxx', 'pay_xxx')
+await client.orders.payments.void('or_xxx', 'pay_xxx')
+await client.orders.refunds.create('or_xxx', { payment_id: 'pay_xxx', amount: 19.99 })
+```
+
+```bash CLI
+spree api patch /orders/or_xxx/payments/pay_xxx/capture
+spree api post /orders/or_xxx/refunds -d '{"payment_id": "pay_xxx", "amount": 19.99}'
+```
+
+</CodeGroup>
+
## Line Items
Line items represent individual products in an order. Each line item links to a [Variant](/developer/core-concepts/products#variants) and tracks the quantity and price at the time of purchase.
@@ -327,6 +410,7 @@ For more details, see [Shipments](/developer/core-concepts/shipments) and [Payme
## Related Documentation
+- [Cart, Checkout & Orders](/developer/sdk/store/cart-checkout) — Store SDK guide for carts, checkout, coupon codes, and order history
- [Payments](/developer/core-concepts/payments) — Payment processing and payment sessions
- [Shipments](/developer/core-concepts/shipments) — Fulfillment and shipping rates
- [Addresses](/developer/core-concepts/addresses) — Billing and shipping addresses
diff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdx
index a97b251b9f..956404ec7d 100644
--- a/docs/developer/core-concepts/payments.mdx
+++ b/docs/developer/core-concepts/payments.mdx
@@ -77,7 +77,7 @@ erDiagram
Refund {
decimal amount
- string reason
+ integer refund_reason_id
}
LogEntry {
@@ -128,7 +128,7 @@ A `PaymentMethod` can have the following attributes:
| `name` | The visible name for this payment method | `Check` |
| `description`| The description for this payment method | `Pay by check.` |
| `active` | Whether or not this payment method is active. Set it `false` to hide it in the Store API. | `true` |
-| `display_on` | Determines where the payment method can be visible. Values can be `front` for Store API, `back` for admin panel only or `both` for both. | `both` |
+| `display_on` | Determines where the payment method can be visible. Values can be `front_end` (Store API), `back_end` (admin panel only), or `both` (both). | `both` |
| `position` | The position of the payment method in lists. Lower numbers appear first. | `1` |
<Info>
@@ -230,7 +230,7 @@ sequenceDiagram
</Info>
</Step>
<Step title="Customer pays on the frontend">
- The frontend uses the gateway's JavaScript SDK (e.g., Stripe.js, Adyen Drop-in) with the `client_secret` to securely collect payment details. Card data never touches your server — it goes directly to the payment provider, ensuring **PCI compliance**. If the payment requires **3D Secure** authentication or redirects to an offsite gateway (CashApp, Klarna, etc.), the gateway SDK handles it automatically.
+ The frontend uses the gateway's JavaScript SDK (e.g., Stripe.js, Adyen Drop-in) with the `client_secret` to securely collect payment details. Card data never touches your server — it goes directly to the payment provider, ensuring [PCI compliance](/developer/security/pci_compliance). If the payment requires **3D Secure** authentication or redirects to an offsite gateway (CashApp, Klarna, etc.), the gateway SDK handles it automatically.
</Step>
<Step title="Complete Payment Session">
After the customer completes payment, the frontend calls the Complete Payment Session endpoint. Spree verifies the payment status with the gateway, creates a `Payment` record, creates the appropriate payment source (Credit Card, wallet, etc.), and marks the session as completed.
@@ -293,14 +293,14 @@ sequenceDiagram
participant Frontend
participant Spree API
- Frontend->>Spree API: GET /payment_methods
- Spree API-->>Frontend: Payment methods (with session_required flag)
+ Frontend->>Spree API: GET /carts/:id
+ Spree API-->>Frontend: Cart (with embedded payment_methods, each carrying session_required)
Frontend->>Spree API: POST /payments (payment_method_id)
Spree API->>Spree API: Create Payment (checkout state)
Spree API-->>Frontend: Payment created
- Frontend->>Spree API: PATCH /orders/:id/complete
+ Frontend->>Spree API: POST /carts/:id/complete
Spree API->>Spree API: process_payments! (authorize succeeds immediately)
Spree API->>Spree API: Payment → pending/completed
Spree API-->>Frontend: Order completed
@@ -308,7 +308,7 @@ sequenceDiagram
<Steps>
<Step title="List payment methods">
- The frontend calls `GET /payment_methods` and checks the `session_required` flag on each method. Methods with `session_required: false` use this direct flow.
+ The frontend reads the cart's embedded `payment_methods` (returned by `GET /carts/:id`) and checks the `session_required` flag on each method. Methods with `session_required: false` use this direct flow.
</Step>
<Step title="Create payment">
The frontend calls `POST /payments` with the `payment_method_id`. Spree creates a `Payment` record in `checkout` state. No external provider interaction is needed.
@@ -464,7 +464,7 @@ Once a Payment Session is completed, Spree creates a `Payment` record (`Spree::P
| Attribute | Description | Example Value |
|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `number` | A unique identifier for the payment. | `P123456789` |
+| `number` | A unique identifier for the payment. | `PAB12CD34` |
| `source_type` | The type of source used for the payment. | `Spree::CreditCard` |
| `source_id` | The ID of the source used for the payment. | `1` |
| `amount` | The amount of the payment. | `99.99` |
@@ -597,13 +597,13 @@ sequenceDiagram
| `external_id` | The provider-side session ID (e.g., Stripe SetupIntent ID) | `seti_ABC123` |
| `external_client_secret` | Client secret for the frontend SDK | `seti_ABC123_secret_xyz` |
| `external_data` | Provider-specific data | `{}` |
-| `payment_source_id` | The saved payment source created after completion | `ps_xyz789` |
+| `payment_source_id` | The saved payment source created after completion | `card_xyz789` |
| `payment_source_type` | The type of saved payment source | `Spree::CreditCard` |
### Payment Setup Session API
<Note>
-Payment Setup Sessions require customer authentication. The customer must be logged in.
+Payment Setup Sessions require [customer authentication](/api-reference/store-api/authentication). The customer must be logged in.
</Note>
**Create a Payment Setup Session:**
@@ -633,7 +633,7 @@ console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz
"payment_method_id": "pm_xyz789",
"payment_source_id": null,
"payment_source_type": null,
- "customer_id": "usr_def456"
+ "customer_id": "cus_def456"
}
```
@@ -652,7 +652,7 @@ const completed = await client.customer.paymentSetupSessions.complete(
options
)
console.log(completed.status) // 'completed'
-console.log(completed.payment_source_id) // e.g. 'ps_xyz789' - the saved payment method
+console.log(completed.payment_source_id) // e.g. 'card_xyz789' - the saved payment method
```
Spree will verify the result with the provider and create a saved payment source (e.g., `Spree::CreditCard`) that can be used for future payments.
@@ -675,7 +675,7 @@ Spree team maintains several payment gateway integrations. All of these gateways
## Payment Events
-Spree publishes events throughout the payment lifecycle that you can subscribe to:
+Spree publishes events throughout the payment lifecycle that you can subscribe to. For the delivered payload schemas of these events (e.g. `payment.paid`, `payment_session.completed`), see the [Webhooks & Events reference](/api-reference/webhooks-events):
### Payment Events
| Event | Description |
@@ -703,6 +703,7 @@ See [Events](/developer/core-concepts/events) for more details on subscribing to
## Related Documentation
+- [Payments (Store SDK)](/developer/sdk/store/payments) - SDK how-to for payment sessions, payments, and setup sessions
- [Build a Custom Payment Method](/developer/how-to/custom-payment-method) - Step-by-step guide to creating your own payment gateway integration
- [Orders](/developer/core-concepts/orders) - Order management and state machine
- [Checkout Customization](/developer/customization/checkout) - Customizing the checkout flow
diff --git a/docs/developer/core-concepts/pricing.mdx b/docs/developer/core-concepts/pricing.mdx
index 87d7129ba6..54bfe370c1 100644
--- a/docs/developer/core-concepts/pricing.mdx
+++ b/docs/developer/core-concepts/pricing.mdx
@@ -11,7 +11,7 @@ Spree's pricing system supports both simple single-currency pricing and advanced
## Prices
-Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](/developer/core-concepts/markets) context.
+Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](/developer/core-concepts/markets) context. See [monetary amounts](/api-reference/store-api/monetary-amounts) for how money fields (decimal, cents, and display string) are formatted across the API.
| Attribute | Description | Example |
|-----------|-------------|---------|
@@ -29,19 +29,25 @@ The Store API returns the resolved price (including Price List rules) for the cu
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Product price is included by default
const product = await client.products.get('spree-tote')
-console.log(product.price) // "15.99" — resolved for current currency
-console.log(product.original_price) // "19.99" — compare-at price (if set)
+console.log(product.price.amount) // "15.99" — resolved for current currency
+console.log(product.price.compare_at_amount) // "19.99" — compare-at/strikethrough price (if set)
// Each variant has its own price
const detailed = await client.products.get('spree-tote', {
expand: ['variants'],
})
detailed.variants?.forEach(variant => {
- console.log(variant.price) // "15.99"
- console.log(variant.original_price) // "19.99"
+ console.log(variant.price.amount) // "15.99"
+ console.log(variant.price.compare_at_amount) // "19.99"
+})
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+ expand: ['variants'],
})
```
@@ -57,6 +63,43 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants'
</CodeGroup>
+### Setting Prices via the Admin API
+
+Base prices are set per variant per currency. Use the [Admin API](/api-reference/admin-api/introduction) — via the [Admin SDK](/developer/sdk/admin/quickstart) — to set them individually or in bulk (`bulk_upsert` matches on variant + currency):
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+// Set / change one variant's price in a currency
+await client.prices.create({ variant_id: 'variant_xxx', currency: 'USD', amount: 15.99 })
+
+// Upsert many at once
+await client.prices.bulkUpsert({
+ prices: [
+ { variant_id: 'variant_xxx', currency: 'USD', amount: 15.99 },
+ { variant_id: 'variant_xxx', currency: 'EUR', amount: 14.99 },
+ ],
+})
+```
+
+```bash CLI
+spree api post /prices/bulk_upsert -d '{
+ "prices": [
+ { "variant_id": "variant_xxx", "currency": "USD", "amount": 15.99 },
+ { "variant_id": "variant_xxx", "currency": "EUR", "amount": 14.99 }
+ ]
+}'
+```
+
+</CodeGroup>
+
## Price Lists <Since version="5.3" />
Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
@@ -90,6 +133,46 @@ If no applicable Price List is found, the base price is used.
| `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one) |
| `position` | Priority order (lower numbers = higher priority) |
+### Creating a Price List via the Admin API
+
+Rules and per-variant price overrides ride on the create/update payload. Each rule is a `{ type, preferences }` draft (see [Price Rules](#price-rules) below):
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const priceList = await client.priceLists.create({
+ name: 'EU wholesale',
+ match_policy: 'all',
+ rules: [
+ { type: 'customer_group_rule', preferences: { customer_group_ids: ['cg_xxx'] } },
+ ],
+ prices: [
+ { variant_id: 'variant_xxx', currency: 'EUR', amount: '19.99' },
+ ],
+})
+
+// Price Lists are draft until activated
+await client.priceLists.activate(priceList.id)
+```
+
+```bash CLI
+spree api post /price_lists -d '{
+ "name": "EU wholesale",
+ "match_policy": "all",
+ "prices": [{ "variant_id": "variant_xxx", "currency": "EUR", "amount": "19.99" }]
+}'
+spree api patch /price_lists/pl_xxx/activate
+```
+
+</CodeGroup>
+
## Price Rules <Since version="5.3" />
Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
@@ -147,10 +230,10 @@ When resolving prices, Spree considers the full context of the request:
| Quantity | Cart line item | The quantity for volume-based rules |
| Date | Current time | For time-based Price List scheduling |
-The Store API automatically builds this context from the request headers (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
+The Store API automatically builds this context from the [request headers](/api-reference/store-api/localization) (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
<Info>
-Price resolution results are cached for 15 minutes. Different context combinations are cached separately.
+Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on the `X-Spree-Currency` and `X-Spree-Locale` request headers so each currency/locale combination is cached separately at the edge.
</Info>
## Time-Based Pricing
@@ -179,7 +262,7 @@ The prior price is available as an expandable field on product and variant endpo
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const product = await client.products.get('spree-tote', {
expand: ['prior_price'],
})
@@ -192,6 +275,12 @@ if (product.prior_price) {
}
```
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+ expand: ['prior_price'],
+})
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_price' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -261,6 +350,7 @@ bundle exec rake spree:price_history:seed
## Related Documentation
- [Products](/developer/core-concepts/products) — Products, Variants, and base prices
+- [Store SDK: Products](/developer/sdk/store/products) — Fetching product and variant prices with the Store SDK
- [Markets](/developer/core-concepts/markets) — Geographic regions with currency and locale
- [Taxes](/developer/core-concepts/taxes) — Tax categories, tax rates, and zones
- [Promotions](/developer/core-concepts/promotions) — Discount-based pricing via promotion rules
diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdx
index 21f464a8bc..61fdcd7f36 100644
--- a/docs/developer/core-concepts/products.mdx
+++ b/docs/developer/core-concepts/products.mdx
@@ -82,7 +82,7 @@ erDiagram
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List products with pagination
const { data: products, meta } = await client.products.list({
limit: 12,
@@ -103,7 +103,14 @@ const results = await client.products.list({
// Sort products
const sorted = await client.products.list({
- sort: 'price_high_to_low', // or: price_low_to_high, newest, name_a_z, name_z_a
+ sort: '-price', // high to low; also: price, name, -name, available_on, -available_on, best_selling
+})
+```
+
+```typescript Admin SDK
+const { data: products, meta } = await adminClient.products.list({
+ limit: 12,
+ page: 1,
})
```
@@ -129,7 +136,7 @@ See [Querying](/api-reference/store-api/querying) for the full list of filtering
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Get by slug
const product = await client.products.get('spree-tote')
@@ -138,8 +145,13 @@ const detailed = await client.products.get('spree-tote', {
expand: ['variants', 'media', 'option_types', 'categories'],
})
// detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]
-// detailed.media => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]
-// detailed.option_types => [{ name: "size", presentation: "Size", option_values: [...] }]
+// detailed.media => [{ id: "img_xxx", original_url: "https://cdn...", position: 1 }]
+// detailed.option_types => [{ name: "size", label: "Size", position: 1, kind: "..." }]
+// detailed.option_values => [{ name: "small", label: "S", option_type_name: "size", ... }] // separate top-level array when expanded
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z')
```
```bash cURL
@@ -149,18 +161,98 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,m
</CodeGroup>
+Pass `expand` to include related resources in a single response — see [expand relations](/api-reference/store-api/relations) for how relation inclusion works.
+
+## Managing Products
+
+The examples above use the **Store API** (publishable key, read-only, customer-facing). To **create and manage** products, use the [Admin API](/api-reference/admin-api/introduction) — via the [Admin SDK](/developer/sdk/admin/quickstart) or the [Spree CLI](/developer/cli/admin-api).
+
+A product's purchasable attributes (SKU, prices, stock) live on its **variants**, which you can create inline:
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const product = await client.products.create({
+ name: 'Premium T-Shirt',
+ description: 'Soft, organic cotton.',
+ status: 'active',
+ variants: [
+ {
+ sku: 'TSHIRT-S-NAVY',
+ options: [
+ { name: 'size', value: 'Small' },
+ { name: 'color', value: 'navy' },
+ ],
+ prices: [{ currency: 'USD', amount: 29.99 }],
+ stock_items: [{ stock_location_id: 'sloc_xxx', count_on_hand: 50 }],
+ },
+ ],
+})
+```
+
+```bash CLI
+spree api post /products -d '{
+ "name": "Premium T-Shirt",
+ "status": "active",
+ "variants": [{
+ "sku": "TSHIRT-S-NAVY",
+ "options": [{ "name": "size", "value": "Small" }],
+ "prices": [{ "currency": "USD", "amount": 29.99 }]
+ }]
+}'
+```
+
+</CodeGroup>
+
+Update, clone, or archive a product (deleting soft-deletes it):
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.products.update('prod_xxx', { name: 'Premium Tee', status: 'active' })
+await client.products.clone('prod_xxx') // duplicate as a new draft
+await client.products.delete('prod_xxx') // soft-delete
+```
+
+```bash CLI
+spree api patch /products/prod_xxx -d '{"name": "Premium Tee"}'
+spree api post /products/prod_xxx/clone
+spree api delete /products/prod_xxx
+```
+
+</CodeGroup>
+
+<Tip>
+Operating on many products at once? The Admin API has bulk actions — `bulkStatusUpdate`, `bulkAddToCategories`, `bulkAddTags`, `bulkDestroy`, and more. See the [Admin API endpoint index](/api-reference/admin-api/endpoints).
+</Tip>
+
## Product Filters
Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const filters = await client.products.filters()
// {
-// option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
-// price_range: { min: 9.99, max: 199.99 },
-// categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
+// filters: [
+// { id: "price", type: "price_range", min: 9.99, max: 199.99, currency: "USD" },
+// { id: "availability", type: "availability", options: [{ id: "in_stock", count: 42 }] },
+// { id: "opt_xxx", type: "option", name: "size", label: "Size", kind: "...",
+// options: [{ id: "optv_xxx", name: "small", label: "Small", count: 12 }, ...] },
+// { id: "categories", type: "category",
+// options: [{ id: "ctg_xxx", name: "Clothing", permalink: "clothing", count: 45 }] },
+// ],
+// sort_options: [{ id: "price" }, ...],
+// default_sort: "best_selling",
+// total_count: 120,
// }
// Scoped to a specific category
@@ -214,6 +306,32 @@ When a product has option types, each unique combination of option values create
The product's `default_variant_id` points to the first non-master variant (or the master variant if none exist).
+Add a variant to an existing product via the Admin API (SKU, prices, and stock all live on the variant):
+
+<CodeGroup>
+
+```typescript Admin SDK
+const variant = await client.products.variants.create('prod_xxx', {
+ sku: 'TEE-L-R',
+ options: [
+ { name: 'size', value: 'Large' },
+ { name: 'color', value: 'Red' },
+ ],
+ prices: [{ currency: 'USD', amount: 24.99 }],
+ stock_items: [{ stock_location_id: 'sloc_xxx', count_on_hand: 30 }],
+})
+```
+
+```bash CLI
+spree api post /products/prod_xxx/variants -d '{
+ "sku": "TEE-L-R",
+ "options": [{ "name": "size", "value": "Large" }],
+ "prices": [{ "currency": "USD", "amount": 24.99 }]
+}'
+```
+
+</CodeGroup>
+
## Option Types and Option Values
Option types define the axes of variation for a product (e.g., Size, Color, Material). Option values are the specific choices within each type (e.g., Small, Medium, Large).
@@ -222,30 +340,68 @@ A product must have at least one option type to have multiple variants. Option t
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const product = await client.products.get('spree-tee', {
- expand: ['option_types'],
+ expand: ['option_types', 'option_values'],
})
+// Option types describe the axes of variation
product.option_types?.forEach(optionType => {
- console.log(optionType.presentation) // "Size"
- optionType.option_values.forEach(value => {
- console.log(value.presentation) // "Small", "Medium", "Large"
- })
+ console.log(optionType.label) // "Size"
+})
+
+// Option values are a separate flat array; each carries its parent's id/label
+product.option_values?.forEach(value => {
+ console.log(value.option_type_label, value.label) // "Size", "Small"
+})
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_k5nR8xLq', {
+ expand: ['variants'],
})
```
```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \
+curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types,option_values' \
-H 'X-Spree-API-Key: pk_xxx'
```
</CodeGroup>
<Info>
-Option type `name` and `presentation` fields are translatable.
+Option type `name` and `label` fields are translatable.
</Info>
+Create option types (and their values) via the Admin API. Sending `option_values` replaces the full set, so include every value you want to keep:
+
+<CodeGroup>
+
+```typescript Admin SDK
+const optionType = await client.optionTypes.create({
+ name: 'size',
+ label: 'Size',
+ option_values: [
+ { name: 'small', label: 'Small', position: 1 },
+ { name: 'medium', label: 'Medium', position: 2 },
+ { name: 'large', label: 'Large', position: 3 },
+ ],
+})
+```
+
+```bash CLI
+spree api post /option_types -d '{
+ "name": "size",
+ "label": "Size",
+ "option_values": [
+ { "name": "small", "label": "Small" },
+ { "name": "medium", "label": "Medium" }
+ ]
+}'
+```
+
+</CodeGroup>
+
## Media
Media can be attached to the product (via the master variant) or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product-level images.
@@ -258,7 +414,7 @@ Use these fields for product listing pages to avoid loading all images:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List products — thumbnail_url is always included
const { data: products } = await client.products.list({ limit: 12 })
@@ -267,6 +423,10 @@ products.forEach(product => {
})
```
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({ limit: 12 })
+```
+
```bash cURL
# thumbnail_url is always in the response — no ?expand needed
curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
@@ -285,22 +445,28 @@ On the product detail page, expand `media` and `variants` to get the full set of
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const product = await client.products.get('spree-tote', {
expand: ['media', 'variants'],
})
// Product-level images (from master variant)
-product.media // [{ url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
+product.media // [{ original_url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
// Each variant has its own thumbnail and media_count
product.variants?.forEach(variant => {
- variant.thumbnail // "https://cdn.../tote-red.jpg" — always available
+ variant.thumbnail_url // "https://cdn.../tote-red.jpg" — always available
variant.media_count // 3 — quick check without loading media
variant.media // full image array (only when ?expand=media)
})
```
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+ expand: ['media'],
+})
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -341,7 +507,7 @@ Products can belong to multiple categories.
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// List categories
const { data: categories } = await client.categories.list()
@@ -354,6 +520,10 @@ const { data: products } = await client.categories.products.list('clothing/shirt
})
```
+```typescript Admin SDK
+const { data: categories } = await adminClient.categories.list()
+```
+
```bash cURL
# List categories
curl 'https://api.mystore.com/api/v3/store/categories' \
@@ -394,7 +564,7 @@ Publications appear in the API under `product_publications` when expanded; the s
<CodeGroup>
-```typescript SDK
+```typescript Admin SDK
const product = await adminClient.products.get('prod_abc', {
expand: ['product_publications', 'channels'],
})
@@ -435,7 +605,7 @@ Two write surfaces serve different shapes:
<CodeGroup>
- ```typescript SDK
+ ```typescript Admin SDK
await adminClient.products.update('prod_abc', {
product_publications: [
{ channel_id: 'ch_online' },
@@ -462,7 +632,7 @@ Two write surfaces serve different shapes:
<CodeGroup>
- ```typescript SDK
+ ```typescript Admin SDK
await adminClient.channels.addProducts('ch_online', {
product_ids: ['prod_abc', 'prod_def'],
published_at: '2026-07-01T00:00:00Z',
@@ -498,7 +668,7 @@ Storefronts and `client.products.list()` calls return only products published on
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Client-level default
const client = createClient({ baseUrl, publishableKey, channel: 'pos' })
@@ -506,6 +676,11 @@ const client = createClient({ baseUrl, publishableKey, channel: 'pos' })
const posProducts = await client.products.list({}, { channel: 'pos' })
```
+```typescript Admin SDK
+// filter by the channel's code via Ransack (q[channels_code_eq])
+const { data: products } = await adminClient.products.list({ channels_code_eq: 'pos' })
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products' \
-H 'X-Spree-API-Key: pk_xxx' \
@@ -530,4 +705,5 @@ See [Sales Channels](/developer/core-concepts/channels) for the full channel lif
- [Media](/developer/core-concepts/media) — Image management
- [Translations](/developer/core-concepts/translations) — Translating product content
- [Search & Filtering](/developer/core-concepts/search-filtering) — Full-text search and Ransack filtering
+- [Store SDK Products](/developer/sdk/store/products) — Listing, fetching, filtering, and categories via `client.products`
- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination
diff --git a/docs/developer/core-concepts/promotions.mdx b/docs/developer/core-concepts/promotions.mdx
index 389744bc65..9995bea912 100644
--- a/docs/developer/core-concepts/promotions.mdx
+++ b/docs/developer/core-concepts/promotions.mdx
@@ -194,7 +194,7 @@ Limits the promotion to orders in a specific currency.
Requires products with specific option values (e.g., size, color) to be in the order.
**Configuration:**
-- `preferred_eligible_values` - Array of eligible variant IDs
+- `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".
@@ -255,6 +255,65 @@ The action checks stock availability before adding items. Items are not automati
**Use case:** "Free gift with purchase", "Buy 2 get 1 free", "Spend $100 get free sample".
+## Managing Promotions
+
+Create and manage promotions via the [Admin API](/api-reference/admin-api/introduction). Rules and actions can be supplied inline on create — each is a `{ type, preferences }` draft using the rule/action types described above:
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+// "20% off orders over $100 with code SUMMER20"
+const promotion = await client.promotions.create({
+ name: 'Summer Sale',
+ code: 'SUMMER20',
+ kind: 'coupon_code',
+ rules: [{ type: 'item_total', preferences: { amount_min: 100 } }],
+ actions: [
+ {
+ type: 'create_adjustment',
+ calculator: { type: 'flat_percent_item_total', preferences: { flat_percent: 20 } },
+ },
+ ],
+})
+```
+
+```bash CLI
+spree api post /promotions -d '{
+ "name": "Summer Sale",
+ "code": "SUMMER20",
+ "kind": "coupon_code",
+ "rules": [{ "type": "item_total", "preferences": { "amount_min": 100 } }]
+}'
+```
+
+</CodeGroup>
+
+You can also add rules and actions to an existing promotion, or update and remove the promotion itself:
+
+<CodeGroup>
+
+```typescript Admin SDK
+await client.promotions.rules.create('promo_xxx', {
+ type: 'first_order',
+})
+await client.promotions.update('promo_xxx', { expires_at: '2026-09-01T00:00:00Z' })
+await client.promotions.delete('promo_xxx')
+```
+
+```bash CLI
+spree api post /promotions/promo_xxx/promotion_rules -d '{"type": "first_order"}'
+spree api patch /promotions/promo_xxx -d '{"expires_at": "2026-09-01T00:00:00Z"}'
+```
+
+</CodeGroup>
+
## Coupon Codes
Coupon codes track promotion usage and can be single-use or multi-use.
@@ -274,11 +333,11 @@ For bulk-generated codes, each code tracks its usage state:
## Applying Coupon Codes via Store API
-Customers apply coupon codes during checkout via the Store API:
+Customers [apply coupon codes during checkout](/developer/sdk/store/cart-checkout) via the Store API:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Apply a discount code to the cart
const cart = await client.carts.discountCodes.apply('cart_abc123', 'SUMMER20', {
spreeToken: '<token>',
@@ -292,7 +351,7 @@ await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {
```bash cURL
# Apply a coupon code
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/coupon_codes' \
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/discount_codes' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: <token>' \
-H 'Content-Type: application/json' \
@@ -322,3 +381,5 @@ How promotions are evaluated and applied:
- [Calculators](/developer/core-concepts/calculators) - Learn about promotion calculators
- [Orders](/developer/core-concepts/orders) - Understanding order processing
- [Customization Quickstart](/developer/customization/quickstart) - Overview of customization options
+- [Admin SDK Resources](/developer/sdk/admin/resources) - The `client.promotions.*` resource-client pattern used in the examples above
+- [Spree CLI Admin API](/developer/cli/admin-api) - The `spree api` command reference for the CLI examples above
diff --git a/docs/developer/core-concepts/reports.mdx b/docs/developer/core-concepts/reports.mdx
index 2e4bb91fe6..80321f54b5 100644
--- a/docs/developer/core-concepts/reports.mdx
+++ b/docs/developer/core-concepts/reports.mdx
@@ -100,7 +100,7 @@ The Products Performance report aggregates sales metrics by product for the spec
### Generation Flow
1. **User creates report** via admin UI with date range, currency, and optional vendor
-2. **Report is saved** to database with status tracking
+2. **Report is saved** to the database
3. **`report.created` event fires** via `publishes_lifecycle_events` concern
4. **`Spree::ReportSubscriber` catches event** and enqueues `GenerateJob`
5. **Background job runs `report.generate`**:
@@ -184,7 +184,7 @@ Spree::Admin::RuntimeConfig.reports_line_items_limit = 100
### Background Job Queue
-Reports use a dedicated queue. Configure your job processor:
+By default, report jobs run on the `:default` queue. To route them to a dedicated queue, configure your job processor:
```ruby
# Sidekiq example
@@ -204,3 +204,5 @@ can :manage, Spree::Report
- [Build a Custom Report](/developer/how-to/custom-report) - Step-by-step guide to creating custom reports
- [Events](/developer/core-concepts/events) - How report generation uses the events system
+- [Imports & Exports](/developer/core-concepts/imports-exports) - The broader async-export, ActiveStorage-attachment pattern reports share
+- [Admin API Endpoints](/api-reference/admin-api/endpoints) - Endpoints for creating and downloading reports from an integration
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdx
index b0b3330c01..3202289df7 100644
--- a/docs/developer/core-concepts/search-filtering.mdx
+++ b/docs/developer/core-concepts/search-filtering.mdx
@@ -9,7 +9,7 @@ import { Since } from '/snippets/since.mdx';
Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
-- Full-text search across product names, descriptions, and SKUs
+- Full-text search across product names and SKUs
- Attribute-based filtering (price range, availability, stock status)
- Category and taxon filtering
- Faceted search with filter counts
@@ -21,13 +21,20 @@ Use the `search` parameter for full-text search across product fields:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: products } = await client.products.list({
search: 'tote bag',
limit: 12,
})
```
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+ search: 'tote bag',
+ limit: 12,
+})
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -41,13 +48,20 @@ curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12'
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: products } = await client.products.list({
price_gte: 20,
price_lte: 100,
})
```
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+ price_gte: 20,
+ price_lte: 100,
+})
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -59,12 +73,18 @@ curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: products } = await client.products.list({
in_stock: true,
})
```
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+ in_stock: true,
+})
+```
+
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -76,13 +96,8 @@ curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
<CodeGroup>
-```typescript SDK
-// Products in a specific category
-const { data: products } = await client.categories.products.list('clothing/shirts', {
- limit: 12,
-})
-
-// Or filter by category ID (includes descendants)
+```typescript Store SDK
+// Filter by category ID (includes descendants)
const { data: products } = await client.products.list({
in_category: 'ctg_xxx',
})
@@ -93,11 +108,19 @@ const { data: products } = await client.products.list({
})
```
-```bash cURL
-# Products in a category
-curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
- -H 'X-Spree-API-Key: pk_xxx'
+```typescript Admin SDK
+// Filter by category ID (includes descendants)
+const { data: products } = await adminClient.products.list({
+ in_category: 'ctg_xxx',
+})
+// Multiple categories (OR logic)
+const { data: products } = await adminClient.products.list({
+ in_categories: ['ctg_shirts', 'ctg_pants'],
+})
+```
+
+```bash cURL
# Filter by category ID (includes descendants)
curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
-H 'X-Spree-API-Key: pk_xxx'
@@ -113,14 +136,20 @@ curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirt
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: products } = await client.products.list({
- tags_cont: 'sale',
+ tags_name_cont: 'sale',
+})
+```
+
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+ tags_name_cont: 'sale',
})
```
```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
+curl 'https://api.mystore.com/api/v3/store/products?q[tags_name_cont]=sale' \
-H 'X-Spree-API-Key: pk_xxx'
```
@@ -130,18 +159,24 @@ curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Sort by price (low to high)
const sorted = await client.products.list({
- sort: 'price_low_to_high',
+ sort: 'price',
})
-// Available sort options:
-// price_low_to_high, price_high_to_low, newest, name_a_z, name_z_a
+// Available sort options (prefix '-' for descending; use '-available_on' for newest):
+// price, -price, name, -name, available_on, -available_on, best_selling
+```
+
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+ sort: 'price',
+})
```
```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
+curl 'https://api.mystore.com/api/v3/store/products?sort=price' \
-H 'X-Spree-API-Key: pk_xxx'
```
@@ -149,16 +184,22 @@ curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
## Product Filters (Faceted Search)
-Get available filter options for building a faceted search UI. Returns option values, price ranges, and categories with counts:
+Get available filter options for building a faceted search UI. Returns an array of typed filter objects (price range, availability, option types, categories) with counts, plus sort and pagination metadata:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const filters = await client.products.filters()
// {
-// option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
-// price_range: { min: 9.99, max: 199.99 },
-// categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
+// filters: [
+// { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
+// { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, { id: 'out_of_stock', count: 3 }] },
+// { id: 'optt_xxx', type: 'option', name: 'size', label: 'Size', kind: 'dropdown', options: [{ id: 'optval_xxx', name: 'Small', label: 'Small', position: 1, color_code: null, image_url: null, count: 12 }] },
+// { id: 'categories', type: 'category', options: [{ id: 'ctg_xxx', name: 'Clothing', permalink: 'clothing', count: 45 }] },
+// ],
+// sort_options: [{ id: 'manual' }, { id: 'price' }, { id: '-price' }],
+// default_sort: 'manual',
+// total_count: 120,
// }
// Scoped to a specific category
@@ -227,13 +268,20 @@ All list endpoints support pagination:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { data: products, meta } = await client.products.list({
page: 1,
limit: 24,
})
-// meta.total_count => 150
-// meta.total_pages => 7
+// meta.count => 150
+// meta.pages => 7
+```
+
+```typescript Admin SDK
+const { data: products, meta } = await adminClient.products.list({
+ page: 1,
+ limit: 24,
+})
```
```bash cURL
@@ -261,6 +309,8 @@ See [Build a Custom Search Provider](/developer/how-to/custom-search-provider) f
## Related Documentation
- [Products](/developer/core-concepts/products) — Product catalog and listing
-- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination reference
+- [Store SDK Products](/developer/sdk/store/products) — `client.products.list()` options and methods
+- [Querying](/api-reference/store-api/querying) — Store API filtering, sorting, and pagination reference
+- [Admin API querying](/api-reference/admin-api/querying) — Admin API filtering, sorting, and pagination reference
- [Build a Custom Search Provider](/developer/how-to/custom-search-provider) — Step-by-step guide
- [Meilisearch Integration](/integrations/search/meilisearch) — Setup guide
diff --git a/docs/developer/core-concepts/shipments.mdx b/docs/developer/core-concepts/shipments.mdx
index 556bdac74b..5f74041319 100644
--- a/docs/developer/core-concepts/shipments.mdx
+++ b/docs/developer/core-concepts/shipments.mdx
@@ -61,9 +61,9 @@ The Store API/SDK exposes shipments as `fulfillments` with these attributes:
| `fulfillment_type` | `shipping` or `digital` | `shipping` |
| `cost` | Delivery cost | `9.99` |
| `fulfilled_at` | When the fulfillment was shipped | `2025-07-21T14:36:00Z` |
-| `stock_location` | Where items ship from | `Warehouse NYC` |
+| `stock_location` | Where items ship from | `{ id: "sloc_xxx", name: "Warehouse NYC" }` |
| `delivery_method` | The selected delivery method | `{ id: "dm_xxx", name: "UPS Ground" }` |
-| `delivery_rates` | Available rates for the customer to pick from | `[{ id: "rate_xxx", cost: "9.99", selected: true, ... }]` |
+| `delivery_rates` | Available rates for the customer to pick from | `[{ id: "dr_xxx", cost: "9.99", selected: true, ... }]` |
## Shipment States
@@ -84,29 +84,31 @@ The Store API/SDK exposes shipments as `fulfillments` with these attributes:
## Selecting Shipping Rates
-During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding.
+During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding. See the [Cart & Checkout SDK](/developer/sdk/store/cart-checkout) guide for the full storefront cart and fulfillment flow.
<CodeGroup>
-```typescript SDK
-// Get fulfillments with available delivery rates
+```typescript Store SDK
+// Get the cart with its fulfillments and available delivery rates
// (the Store API/SDK exposes shipments as `fulfillments`)
-const order = await client.orders.get(orderId, {
- expand: ['fulfillments'],
-})
+const cart = await client.carts.get(cartId)
// Each fulfillment has available delivery rates
-order.fulfillments?.forEach(fulfillment => {
+cart.fulfillments?.forEach(fulfillment => {
console.log(fulfillment.number) // "H12345678901"
- console.log(fulfillment.delivery_rates) // [{ id: "rate_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
+ console.log(fulfillment.delivery_rates) // [{ id: "dr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
})
// Select a delivery rate
await client.carts.fulfillments.update(cartId, fulfillment.id, {
- selected_delivery_rate_id: 'rate_xxx',
+ selected_delivery_rate_id: 'dr_xxx',
})
```
+```typescript Admin SDK
+const order = await adminClient.orders.get(orderId)
+```
+
```bash cURL
# Get fulfillments
curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
@@ -118,7 +120,7 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/
-H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: abc123' \
-H 'Content-Type: application/json' \
- -d '{ "selected_delivery_rate_id": "rate_xxx" }'
+ -d '{ "selected_delivery_rate_id": "dr_xxx" }'
```
</CodeGroup>
@@ -195,7 +197,7 @@ A channel can also override the routing **strategy** entirely — useful when on
### When it fires
-Routing fires once, when the order transitions from `cart` to `address` (the start of checkout). It produces one or more `Shipment`s, each tied to a chosen stock location. The decision is sticky — once the shipments are created, their locations stay fixed unless the merchant edits them in the admin or the cart is cleared and re-routed.
+Routing fires once, when the order transitions into the `delivery` step of checkout (from `address`). The `cart`→`address` transition only assigns default addresses; routing runs on the next step. It produces one or more `Shipment`s, each tied to a chosen stock location. The decision is sticky — once the shipments are created, their locations stay fixed unless the merchant edits them in the admin or the cart is cleared and re-routed.
Routing happens **after** stock reservations: by the time routing runs, the cart has already reserved the units it needs. Reservations and routing make their decisions at different layers — reservations protect the variant's total inventory across all locations, routing picks which location ships. They coexist correctly today, with a small inefficiency around location-pinning that's planned to be tightened in 6.0.
@@ -302,3 +304,4 @@ A store shipping from 2 locations (New York, Los Angeles) with 3 carriers and 3
- [Addresses](/developer/core-concepts/addresses) — Shipping address and zones
- [Build Custom Order Routing](/developer/how-to/custom-order-routing) — Custom rules and strategies for choosing the fulfillment location
- [Events](/developer/core-concepts/events) — Subscribe to shipment events (e.g., `shipment.shipped`)
+- [Admin API](/api-reference/admin-api/introduction) — Inspect and manage shipments, shipping methods, and categories from the back office
diff --git a/docs/developer/core-concepts/slugs.mdx b/docs/developer/core-concepts/slugs.mdx
index 6ea8e03e38..9deadc85da 100644
--- a/docs/developer/core-concepts/slugs.mdx
+++ b/docs/developer/core-concepts/slugs.mdx
@@ -7,11 +7,11 @@ description: How Spree generates SEO-friendly URL slugs for products, categories
Spree generates SEO-friendly URL slugs for resources like products, categories, and stores. Instead of accessing resources by ID, you can use clean, readable URLs based on resource names.
-Both the Store API and Admin API accept slugs or IDs interchangeably for resource lookups.
+The Store API accepts slugs or prefixed IDs interchangeably for resource lookups. The Admin API resolves resources by prefixed ID only — slugs are not accepted.
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Both work — slug or ID
const product = await client.products.get('spree-tote')
const product = await client.products.get('prod_86Rf07xd4z')
@@ -20,6 +20,11 @@ const product = await client.products.get('prod_86Rf07xd4z')
const category = await client.categories.get('clothing/shirts')
```
+```typescript Admin SDK
+// Admin SDK accepts prefixed IDs only — not slugs
+const product = await adminClient.products.get('prod_86Rf07xd4z')
+```
+
```bash cURL
# By slug
curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
@@ -51,7 +56,6 @@ If a slug already exists, Spree appends the SKU or a unique identifier to ensure
| Product | `slug` | Yes | No |
| Category | `permalink` | Yes | Yes |
| Store | `code` | No | No |
-| Post | `slug` | Yes | No |
### Category Permalinks
@@ -67,28 +71,32 @@ When a parent category is renamed, all child permalinks update automatically.
## Slug History
-When a slug changes (e.g., a product is renamed), Spree preserves the old slug. Requests using old slugs still find the resource, enabling:
+When a slug changes (e.g., a product is renamed), Spree records the old slug in its history table (`friendly_id_slugs`).
-- **SEO continuity** — no broken links when names change
-- **Bookmark compatibility** — saved URLs keep working
-- **Graceful URL migration** — old links resolve automatically
+Note: the Store API product and category endpoints look up the *current* slug only (`find_by!` on the slug/permalink column) and do not automatically resolve retired slugs — a request using an old slug returns `404`. To preserve SEO and avoid broken links, issue HTTP 301 redirects from old slugs to the current one in your storefront or application layer.
## Internationalization
-Products and categories support localized slugs — a different slug per locale:
+Products and categories support localized slugs — a different slug per locale. The locale is resolved from the request's [`X-Spree-Locale` header](/api-reference/store-api/localization):
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// English
const product = await client.products.get('red-shoes')
-// French (with locale header)
-const product = await client.products.get('chaussures-rouges', {
+// French — locale goes in the third (request options) argument,
+// which sends the X-Spree-Locale header
+const product = await client.products.get('chaussures-rouges', undefined, {
locale: 'fr',
})
```
+```typescript Admin SDK
+// Admin SDK accepts prefixed IDs only — not slugs
+const product = await adminClient.products.get('prod_86Rf07xd4z')
+```
+
```bash cURL
# English
curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
@@ -113,3 +121,4 @@ Spree prevents certain words from being used as slugs to avoid route conflicts:
- [Products](/developer/core-concepts/products) — Product catalog
- [Translations](/developer/core-concepts/translations) — Multi-language content
- [Querying](/api-reference/store-api/querying) — API resource lookup
+- [Store SDK Products](/developer/sdk/store/products) — `client.products.get()` slug/ID lookup
diff --git a/docs/developer/core-concepts/staff-roles.mdx b/docs/developer/core-concepts/staff-roles.mdx
index 34ea12d35f..80b086b295 100644
--- a/docs/developer/core-concepts/staff-roles.mdx
+++ b/docs/developer/core-concepts/staff-roles.mdx
@@ -65,6 +65,35 @@ spree user create --email [email protected] --password secret123
The created user gets the `admin` role on the default store.
+## Authentication & identity providers
+
+Staff authenticate against the Admin API, which issues a short-lived JWT used for subsequent requests. How a staff member proves who they are is **pluggable** — Spree ships email/password out of the box, and you can plug in any external identity provider (Okta, Microsoft Entra ID, Google Workspace, a custom JWT issuer, SAML, etc.) without changing the rest of the API.
+
+### How admin login works
+
+A staff member logs in via the `POST /api/v3/admin/auth/login` endpoint (see [Admin API Authentication](/api-reference/admin-api/authentication)). The request's `provider` field selects a registered **authentication strategy**. When `provider` is omitted it defaults to `email`, the built-in email/password strategy (which you can also disable and restrict the admin to your preferred SSO provider).
+
+```mermaid
+flowchart TB
+ A["POST /api/v3/admin/auth/login"] --> B{"provider field"}
+ B -->|"omitted or email"| C["Built-in EmailPasswordStrategy"]
+ B -->|"okta, saml, ..."| D["Your custom strategy"]
+ C --> E["Strategy authenticates, returns the staff user"]
+ D --> E
+ E --> F["Spree issues a JWT (aud=admin_api) + HttpOnly refresh cookie"]
+```
+
+Whichever strategy authenticates the request, Spree issues the **same** credentials in return, so downstream code and the admin SPA never need to know which provider was used:
+
+- a JWT access token (`aud: admin_api`), short-lived by design;
+- a rotating refresh token, set as an `HttpOnly` cookie scoped to `/api/v3/admin/auth` (the admin flow keeps it out of the response body — see [Admin Auth & Cookie Refresh](/api-reference/admin-api/authentication)).
+
+The same strategy registry exists on the customer side, so storefront sign-in is pluggable the same way — the only difference is the user class and that the Store API returns the refresh token in the body rather than a cookie.
+
+### Registering a custom identity provider
+
+Follow the [Custom API Authentication how-to](/developer/how-to/custom-api-authentication) for details how to create a custom authentication strategy and register it with the admin API. Once registered, you can use it from the admin SPA or any API client by passing its name in the `provider` field of the login request.
+
## Inviting Admin Users
You can invite new admins through the Admin Panel or programmatically.
@@ -76,7 +105,25 @@ You can invite new admins through the Admin Panel or programmatically.
3. Enter the email address and select a role
4. Click **Send Invitation**
-The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
+**Programmatically:**
+
+Using the [Admin SDK](/developer/sdk/admin/quickstart), call `client.invitations.create`:
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const invitation = await client.invitations.create({
+ email: '[email protected]',
+ role_id: 'role_xxx',
+})
+```
+
+Creating an invitation publishes `invitation.created`, which sends the email. Either way, the invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
```mermaid
flowchart TB
@@ -119,6 +166,9 @@ See the [Customize Permissions guide](/developer/customization/permissions) for
## Related Documentation
+- [Admin SDK](/developer/sdk/admin/quickstart) — the TypeScript client for back-office automation
+- [Custom API Authentication](/developer/how-to/custom-api-authentication) — implement a custom identity-provider strategy (the full guide)
+- [Admin API Authentication](/api-reference/admin-api/authentication) — keys, JWTs, scopes, and the refresh-cookie flow
- [Customers](/developer/core-concepts/customers) — Customer accounts and authentication
- [Stores](/developer/core-concepts/stores) — Multi-store setup
- [Permissions](/developer/customization/permissions) — Roles and authorization
diff --git a/docs/developer/core-concepts/store-credits-gift-cards.mdx b/docs/developer/core-concepts/store-credits-gift-cards.mdx
index a06b9841ab..6cac92fdbe 100644
--- a/docs/developer/core-concepts/store-credits-gift-cards.mdx
+++ b/docs/developer/core-concepts/store-credits-gift-cards.mdx
@@ -84,11 +84,12 @@ Categories help organize store credits by their purpose:
| Category | Description |
|----------|-------------|
-| Default | General purpose store credit |
-| Gift Card | Store credit created from gift card redemption |
+| Default | General purpose store credit (also the default reimbursement category) |
+| Expiring | Store credit that may expire |
+| Non-expiring | Store credit that does not expire |
<Info>
-Categories can be configured as non-expiring. By default, the "Gift Card" category is non-expiring.
+"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?`.
</Info>
### Store Credit Types
@@ -123,7 +124,36 @@ Store credits are managed in the Admin Panel:
5. Enter the amount, category, and optional memo
6. Click **Create**
-Store credits can also be created via the Admin API.
+Store credits can also be created via the [Admin API](/api-reference/admin-api/introduction), as a nested resource under the customer:
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const credit = await client.customers.storeCredits.create('cus_xxx', {
+ amount: 25.0,
+ currency: 'USD',
+ category_id: 'sccat_xxx',
+ memo: 'Goodwill credit for delayed shipment',
+})
+```
+
+```bash CLI
+spree api post /customers/cus_xxx/store_credits -d '{
+ "amount": 25.0,
+ "currency": "USD",
+ "category_id": "sccat_xxx",
+ "memo": "Goodwill credit"
+}'
+```
+
+</CodeGroup>
### Store Credit Events
@@ -154,7 +184,7 @@ erDiagram
decimal amount_used
decimal amount_authorized
string currency
- datetime expires_at
+ date expires_at
datetime redeemed_at
}
@@ -163,7 +193,7 @@ erDiagram
integer codes_count
decimal amount
string currency
- datetime expires_at
+ date expires_at
}
```
@@ -223,7 +253,36 @@ flowchart TB
4. Click **Create**
5. Share the generated code with the recipient
-Gift cards can also be created via the Admin API.
+Gift cards can also be created via the [Admin API](/api-reference/admin-api/introduction). The code is generated automatically if you don't supply one:
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const giftCard = await client.giftCards.create({
+ amount: 50,
+ currency: 'USD',
+ expires_at: '2026-12-31',
+})
+
+console.log(giftCard.code) // share this with the recipient
+```
+
+```bash CLI
+spree api post /gift_cards -d '{
+ "amount": 50,
+ "currency": "USD",
+ "expires_at": "2026-12-31"
+}'
+```
+
+</CodeGroup>
#### Batch Gift Card Generation
@@ -238,6 +297,32 @@ For promotions or bulk distribution, you can create multiple gift cards at once
- **Expiration** - Optional expiration date
4. Click **Create**
+Batches can also be created via the Admin API:
+
+<CodeGroup>
+
+```typescript Admin SDK
+const batch = await client.giftCardBatches.create({
+ prefix: 'HOLIDAY',
+ codes_count: 1000,
+ amount: 25,
+ currency: 'USD',
+ expires_at: '2026-12-31',
+})
+```
+
+```bash CLI
+spree api post /gift_card_batches -d '{
+ "prefix": "HOLIDAY",
+ "codes_count": 1000,
+ "amount": 25,
+ "currency": "USD",
+ "expires_at": "2026-12-31"
+}'
+```
+
+</CodeGroup>
+
<Info>
Large batches are processed in the background to avoid timeout issues.
</Info>
@@ -255,11 +340,11 @@ When a gift card is applied to an order:
- The gift card is marked as redeemed (or partially redeemed)
- No Store Credit is created for guest checkouts
-Gift cards are applied using the same coupon codes endpoint as promotion codes. The endpoint automatically detects whether the code is a promotion coupon or a gift card.
+Gift cards are applied via a dedicated `POST /api/v3/store/carts/:cart_id/gift_cards` endpoint (separate from the `discount_codes` endpoint used for promotion codes); the discount-codes endpoint does not handle gift cards. See the [cart & checkout SDK guide](/developer/sdk/store/cart-checkout) for the full cart flow these calls belong to.
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Apply gift card code to cart (works for guests and registered customers)
// Gift cards use a dedicated endpoint — they reduce amount_due, not total
const cart = await client.carts.giftCards.apply('cart_abc123', 'abc1234def', {
@@ -335,3 +420,5 @@ When a registered customer has multiple store credits, they are applied in order
- [Orders](/developer/core-concepts/orders) — Order management
- [Customers](/developer/core-concepts/customers) — Customer management
- [Events](/developer/core-concepts/events) — Event system and subscribers
+- [Admin SDK Quickstart](/developer/sdk/admin/quickstart) — Set up and authenticate the Admin SDK
+- [Monetary Amounts](/api-reference/store-api/monetary-amounts) — How the API represents `amount`, `amount_used`, and other money fields
diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdx
index 77a2b4d9cd..e898df153e 100644
--- a/docs/developer/core-concepts/stores.mdx
+++ b/docs/developer/core-concepts/stores.mdx
@@ -1,11 +1,11 @@
---
title: Stores
-description: The Store is Spree's top-level multi-tenant boundary — learn how products, orders, channels, markets, and stock locations are scoped to a store.
+description: The Store is Spree's top-level multi-tenant boundary — learn how products, orders, channels, and markets are scoped to a store.
---
## Overview
-The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies, stock locations — belongs to exactly one store. A store owns its branding (logo, custom domain, mail-from address), its [channels](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its catalog.
+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 branding (logo, custom domain, mail-from address), its [channels](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its catalog.
## Store Attributes
@@ -19,35 +19,36 @@ The Store is the top-level tenant in Spree. Every resource — products, orders,
| `seo_title` | Custom SEO title |
| `customer_support_email` | Email for customer support inquiries |
| `mail_from_address` | Sender address for transactional emails |
-| `logo_image_url` | URL to the store's logo |
+| `logo_url` | URL to the store's logo |
| `facebook`, `twitter`, `instagram` | Social media links |
-| `payment_methods` | Payment methods available in this store |
## Fetching Store Information
-Use the store endpoint to get the current store's configuration — useful for rendering logos, SEO metadata, and footer content:
+Store configuration is exposed through the Admin API. Use the store endpoint to read the current store's settings — name, URL, branding, and email addresses:
<CodeGroup>
-```typescript SDK
-const store = await client.store.get()
+```typescript Admin SDK
+const store = await adminClient.store.get()
// {
// name: "My Store",
// url: "https://mystore.com",
-// logo_image_url: "https://cdn.mystore.com/logo.png",
+// logo_url: "https://cdn.mystore.com/logo.png",
+// mailer_logo_url: "https://cdn.mystore.com/mailer-logo.png",
// customer_support_email: "[email protected]",
-// payment_methods: [{ id: "pm_xxx", name: "Stripe", kind: "card" }],
// ...
// }
```
```bash cURL
-curl 'https://api.mystore.com/api/v3/store/store' \
- -H 'X-Spree-API-Key: pk_xxx'
+curl 'https://api.mystore.com/api/v3/admin/store' \
+ -H 'X-Spree-API-Key: sk_xxx'
```
</CodeGroup>
+This is an admin endpoint, so it requires a secret API key (`sk_xxx`) or a Bearer JWT — a publishable key cannot reach it.
+
## Channels vs. Markets
Two different ways to split a store, often confused:
@@ -67,7 +68,7 @@ Each store owns its own resources. Products, orders, channels, markets, and taxo
| [**Markets**](/developer/core-concepts/markets) | A store has many markets, each defining a geographic region with its own currency and locale |
| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store and one channel |
| [**Products**](/developer/core-concepts/products) | A product belongs to one store. Its visibility across channels is controlled by [publications](/developer/core-concepts/channels#publishing-products-on-channels). |
-| [**Taxonomies**](/developer/core-concepts/products#taxons-and-taxonomies) | A taxonomy belongs to one store |
+| [**Taxonomies**](/developer/core-concepts/products#categories) | A taxonomy belongs to one store |
| [**Payment Methods**](/developer/core-concepts/payments) | A payment method belongs to one store |
| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method belongs to one store |
| [**Promotions**](/developer/core-concepts/promotions) | A promotion belongs to one store |
@@ -77,9 +78,9 @@ Each store owns its own resources. Products, orders, channels, markets, and taxo
If you need one Spree backend to serve **multiple distinct merchant brands** — different domains, different catalogs, different admin teams — there are two patterns:
- **Multiple channels under one store** (recommended for most cases) — model each storefront as a Sales Channel. Products are scoped per-channel via publications, orders carry the channel that originated them, and routing/pricing can differ per channel. This is the supported pattern in core Spree 5.5+.
-- **Multiple stores in one app** — the legacy multi-store pattern, where each store is fully independent (catalog, admin, branding). In Spree 5.5+ this requires the `spree_multi_store` extension. Core Spree treats each product as belonging to a single store.
+- **Multiple stores in one app** — the legacy multi-store pattern, where each store is fully independent (catalog, admin, branding). In Spree 5.5+ this requires the [spree_multi_store](/developer/multi-store/quickstart) extension. Core Spree treats each product as belonging to a single store.
-For most multi-brand operations, the channel pattern is simpler and more flexible. Reach for `spree_multi_store` only when stores need genuinely independent catalogs, branding, and admin teams.
+For most multi-brand operations, the channel pattern is simpler and more flexible. Reach for [spree_multi_store](/developer/multi-store/quickstart) only when stores need genuinely independent catalogs, branding, and admin teams.
## Related Documentation
@@ -87,3 +88,4 @@ For most multi-brand operations, the channel pattern is simpler and more flexibl
- [Markets](/developer/core-concepts/markets) — Multi-region commerce within a store
- [Products](/developer/core-concepts/products) — Product catalog
- [Orders](/developer/core-concepts/orders) — Order management and checkout
+- [Admin SDK](/developer/sdk/admin/quickstart) — TypeScript client for the Admin API used to read and update store configuration
diff --git a/docs/developer/core-concepts/taxes.mdx b/docs/developer/core-concepts/taxes.mdx
index f9be95c397..1cfac2fa64 100644
--- a/docs/developer/core-concepts/taxes.mdx
+++ b/docs/developer/core-concepts/taxes.mdx
@@ -55,6 +55,35 @@ Each product is assigned a tax category. One category can be set as the default
| `is_default` | Whether this is the default category | `true` |
| `tax_code` | Code from your tax provider (e.g., Stripe, Avalara) | `1257L` |
+Manage tax categories via the [Admin API](/api-reference/admin-api/introduction), using the [Admin SDK resource clients](/developer/sdk/admin/resources):
+
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const clothing = await client.taxCategories.create({
+ name: 'Clothing',
+ tax_code: '1257L',
+ is_default: true,
+})
+
+await client.taxCategories.update('taxcat_xxx', { is_default: false })
+await client.taxCategories.delete('taxcat_xxx')
+```
+
+```bash CLI
+spree api post /tax_categories -d '{"name": "Clothing", "tax_code": "1257L", "is_default": true}'
+spree api get /tax_categories
+```
+
+</CodeGroup>
+
## Tax Rates
Tax rates define the percentage charged for a specific tax category within a geographic zone.
@@ -137,3 +166,4 @@ Tax categories and rates are managed in the Admin Panel under **Settings → Tax
- [Addresses](/developer/core-concepts/addresses) — Zones and address-based taxation
- [Adjustments](/developer/core-concepts/adjustments) — Tax adjustments
- [Orders](/developer/core-concepts/orders) — How taxes affect order totals
+- [Avalara integration](/integrations/tax/avalara) — Automated tax calculation for complex jurisdictions
diff --git a/docs/developer/core-concepts/translations.mdx b/docs/developer/core-concepts/translations.mdx
index a500f8574a..aabdc91536 100644
--- a/docs/developer/core-concepts/translations.mdx
+++ b/docs/developer/core-concepts/translations.mdx
@@ -52,24 +52,24 @@ erDiagram
| Resource | Translatable Fields |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Product | `name`, `description`, `slug`, `meta_description`, `meta_keywords`, `meta_title` |
+| Product | `name`, `description`, `slug`, `meta_description`, `meta_title` |
| Taxon | `name`, `description`, `permalink` |
| Taxonomy | `name` |
| Option Type | `presentation` |
| Option Value | `presentation` |
| Property | `presentation` |
| Product Property | `value` |
-| Store | `name`, `meta_description`, `meta_keywords`, `seo_title`, `facebook`, `twitter`, `instagram`, `customer_support_email`, `description`, `address`, `contact_phone` |
+| Store | `name`, `meta_description`, `meta_keywords`, `seo_title`, `customer_support_email`, `address`, `contact_phone` |
### Store API
-To retrieve translated content, pass the locale via the `X-Spree-Locale` header or the SDK `locale` option:
+To retrieve translated content, pass the locale via the [`X-Spree-Locale` header](/api-reference/store-api/localization) or the SDK `locale` option:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Fetch product in French
-const product = await client.products.get('spree-tote', {
+const product = await client.products.get('spree-tote', {}, {
locale: 'fr',
})
@@ -83,6 +83,14 @@ const { data: categories } = await client.categories.list({}, {
})
```
+```typescript Admin SDK
+// Pass the locale as a request option to get translated content.
+// The Admin API resolves by prefixed ID only — slugs are not accepted.
+const product = await adminClient.products.get('prod_86Rf07xd4z', {}, { locale: 'fr' })
+
+const { data: categories } = await adminClient.categories.list({}, { locale: 'de' })
+```
+
```bash cURL
# Fetch product in French
curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
@@ -98,11 +106,11 @@ Slugs are also localized — a product can have different slugs per locale. See
Translations are managed in the Admin Panel. When editing a product, taxon, or other translatable resource, switch the locale selector to enter content in each language.
-Translations can also be managed via the Admin API.
+Translations can also be [managed via the Admin API](/developer/sdk/admin/quickstart).
## UI Translations
-Spree stores UI translation strings in a separate project: [Spree I18n](https://github.com/spree/spree_i18n). This is a community-maintained project with locale files for 43+ languages.
+Spree stores UI translation strings in a separate project: [Spree I18n](https://github.com/spree-contrib/spree_i18n). This is a community-maintained project with locale files for 43+ languages.
To install UI translations:
@@ -127,6 +135,7 @@ The full list of supported locales is available in the [Spree I18n GitHub reposi
## Related Documentation
- [Markets](/developer/core-concepts/markets) — Locale and currency configuration per geographic region
+- [Localization](/api-reference/store-api/localization) — Locale, currency, and country headers in API requests
- [Slugs](/developer/core-concepts/slugs) — Localized slugs and URL identifiers
- [Stores](/developer/core-concepts/stores) — Multi-store setup
- [Products](/developer/core-concepts/products) — Product translations
diff --git a/docs/developer/core-concepts/users.mdx b/docs/developer/core-concepts/users.mdx
index 8be7a9544e..05a6ec8d24 100644
--- a/docs/developer/core-concepts/users.mdx
+++ b/docs/developer/core-concepts/users.mdx
@@ -60,7 +60,7 @@ erDiagram
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { token, user } = await client.customers.create({
password: 'password123',
@@ -91,7 +91,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { token, user } = await client.auth.login({
password: 'password123',
@@ -111,7 +111,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
</CodeGroup>
-The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header.
+The response includes a [JWT token](/api-reference/store-api/authentication) and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header. See the [account SDK guide](/developer/sdk/store/account) for the full `auth.login`, refresh, and profile flows.
### Token Refresh
@@ -119,15 +119,17 @@ Refresh an expiring token to keep the session alive:
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
const { token } = await client.auth.refresh({
- token: existingToken,
+ refresh_token: existingRefreshToken,
})
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
- -H 'Authorization: Bearer <jwt_token>'
+ -H 'X-Spree-API-Key: pk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "refresh_token": "rt_xxx" }'
```
</CodeGroup>
@@ -136,7 +138,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
<CodeGroup>
-```typescript SDK
+```typescript Store SDK
// Get current customer
const customer = await client.customer.get()
// {
@@ -158,11 +160,11 @@ const updated = await client.customer.update({
```bash cURL
# Get current customer
-curl 'https://api.mystore.com/api/v3/store/customer' \
+curl 'https://api.mystore.com/api/v3/store/customers/me' \
-H 'Authorization: Bearer <jwt_token>'
# Update profile
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me' \
-H 'Authorization: Bearer <jwt_token>' \
-H 'Content-Type: application/json' \
-d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
@@ -309,3 +311,5 @@ See the [Customize Permissions guide](/developer/customization/permissions) for
- [Authentication](/developer/customization/authentication) — Custom authentication setup
- [Permissions](/developer/customization/permissions) — Roles and authorization
- [Events](/developer/core-concepts/events) — Subscribe to user and invitation events
+- [Store API Authentication](/api-reference/store-api/authentication) — Customer JWT auth flow
+- [Admin API Authentication](/api-reference/admin-api/authentication) — Staff JWT + scopes auth flow
diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdx
index 068b682259..e3302c65b1 100644
--- a/docs/developer/core-concepts/webhooks.mdx
+++ b/docs/developer/core-concepts/webhooks.mdx
@@ -57,20 +57,43 @@ flowchart LR
Navigate to **Settings → Developers → Webhooks** in the admin panel to create and manage webhook endpoints.
-### Via Code
+### Via the Admin API
-```ruby
-endpoint = Spree::WebhookEndpoint.create!(
- store: Spree::Store.default,
+<CodeGroup>
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+const endpoint = await client.webhookEndpoints.create({
url: 'https://example.com/webhooks/spree',
subscriptions: ['order.*', 'product.created'],
- active: true
-)
+ active: true,
+})
+
+// secret_key is auto-generated and returned ONLY on create —
+// store it now for HMAC signature verification.
+endpoint.secret_key // => "a1b2c3d4e5f6..." (64-character hex string)
+```
-# The secret_key is auto-generated
-endpoint.secret_key # => "a1b2c3d4e5f6..." (64-character hex string)
+```bash CLI
+spree api post /webhook_endpoints -d '{
+ "url": "https://example.com/webhooks/spree",
+ "subscriptions": ["order.*", "product.created"],
+ "active": true
+}'
```
+</CodeGroup>
+
+<Warning>
+The `secret_key` is returned **only once**, in the create response. Save it immediately — it can't be retrieved later and is required to verify webhook signatures.
+</Warning>
+
### Endpoint Attributes
| Attribute | Type | Description |
@@ -79,41 +102,37 @@ endpoint.secret_key # => "a1b2c3d4e5f6..." (64-character hex string)
| `active` | Boolean | Enable/disable delivery to this endpoint |
| `subscriptions` | Array | Event patterns to subscribe to |
| `secret_key` | String | Auto-generated key for HMAC signature verification |
-| `store_id` | Integer | The store this endpoint belongs to |
+
+Endpoints always belong to the current store — the association is set automatically from the request scope, so you never pass it when creating or updating an endpoint.
## Event Subscriptions
-The `subscriptions` attribute controls which events trigger webhooks to this endpoint.
+The `subscriptions` attribute controls which events trigger webhooks to this endpoint. Set it when creating the endpoint, or change it later:
-### Subscribe to Specific Events
+<CodeGroup>
-```ruby
-endpoint.subscriptions = ['order.completed', 'order.canceled']
+```typescript Admin SDK
+await client.webhookEndpoints.update('whe_xxx', {
+ subscriptions: ['order.completed', 'order.canceled'],
+})
```
-### Subscribe to Event Patterns
-
-Use wildcards to subscribe to multiple related events:
-
-```ruby
-# All order events
-endpoint.subscriptions = ['order.*']
-
-# All creation events
-endpoint.subscriptions = ['*.created']
-
-# Multiple patterns
-endpoint.subscriptions = ['order.*', 'payment.*', 'shipment.shipped']
+```bash CLI
+spree api patch /webhook_endpoints/whe_xxx \
+ -d '{"subscriptions": ["order.completed", "order.canceled"]}'
```
-### Subscribe to All Events
+</CodeGroup>
-Leave subscriptions empty or use `*` to receive all events:
+The `subscriptions` array accepts exact event names and wildcard patterns:
-```ruby
-endpoint.subscriptions = [] # All events
-endpoint.subscriptions = ['*'] # All events (explicit)
-```
+| `subscriptions` value | Receives |
+|---|---|
+| `['order.completed', 'order.canceled']` | Only those two events |
+| `['order.*']` | All order events |
+| `['*.created']` | All creation events |
+| `['order.*', 'payment.*', 'shipment.shipped']` | Multiple patterns |
+| `[]` or `['*']` | All events |
## Webhook Payload
@@ -127,10 +146,11 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
"data": {
"id": "or_m3Rp9wXz",
"number": "R123456789",
- "state": "complete",
+ "fulfillment_status": "shipped",
+ "payment_status": "paid",
"total": "99.99",
"display_total": "$99.99",
- "item_count": 3,
+ "total_quantity": 3,
"currency": "USD",
"items": [ ... ],
"fulfillments": [ ... ],
@@ -164,6 +184,7 @@ Each webhook request includes these headers:
| `User-Agent` | `Spree-Webhooks/1.0` |
| `X-Spree-Webhook-Event` | Event name (e.g., `order.completed`) |
| `X-Spree-Webhook-Signature` | HMAC-SHA256 signature for verification |
+| `X-Spree-Webhook-Timestamp` | Unix timestamp (seconds) generated at send time; included in the HMAC-SHA256 signed string as `{timestamp}.{payload}` and required to verify `X-Spree-Webhook-Signature` |
### Verifying Webhook Signatures
@@ -245,21 +266,25 @@ Failed webhook deliveries automatically retry up to 5 times with exponential bac
### Checking Delivery Status
-```ruby
-endpoint = Spree::WebhookEndpoint.find(id)
+Inspect an endpoint's delivery log, and re-send a failed delivery, via the Admin API:
-# Recent deliveries
-endpoint.webhook_deliveries.recent
+<CodeGroup>
-# Filter by status
-endpoint.webhook_deliveries.successful
-endpoint.webhook_deliveries.failed
-endpoint.webhook_deliveries.pending
+```typescript Admin SDK
+// Recent deliveries for an endpoint
+const { data: deliveries } = await client.webhookEndpoints.deliveries.list('whe_xxx')
+
+// Re-send a specific delivery
+await client.webhookEndpoints.deliveries.redeliver('whe_xxx', 'whd_xxx')
+```
-# Filter by event
-endpoint.webhook_deliveries.for_event('order.completed')
+```bash CLI
+spree api get /webhook_endpoints/whe_xxx/deliveries -q event_name_eq=order.completed
+spree api post /webhook_endpoints/whe_xxx/deliveries/whd_xxx/redeliver
```
+</CodeGroup>
+
### Delivery Attributes
| Attribute | Description |
@@ -310,31 +335,40 @@ Common webhook events include:
| `payment.paid` | Payment was completed |
| `product.created` | New product created |
| `product.updated` | Product was modified |
-| `customer.created` | New customer registered |
+| `user.created` | New customer/user registered (the admin user class emits `admin.created`) |
## Testing Webhooks
### In Development
-Use tools like [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to test webhooks locally:
+Use tools like [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to test webhooks locally. Create a test endpoint pointed at the tunnel:
-```ruby
-# Create a test endpoint
-endpoint = Spree::WebhookEndpoint.create!(
- store: Spree::Store.default,
+<CodeGroup>
+
+```typescript Admin SDK
+const endpoint = await client.webhookEndpoints.create({
url: 'https://your-ngrok-url.ngrok.io/webhooks',
subscriptions: ['order.*'],
- active: true
-)
+ active: true,
+})
-# Trigger an event
-order = Spree::Order.complete.last
-order.publish_event('order.completed')
+// Fire a synthetic delivery to confirm it's reachable
+await client.webhookEndpoints.sendTest(endpoint.id)
+```
-# Check delivery
-endpoint.webhook_deliveries.last.success?
+```bash CLI
+spree api post /webhook_endpoints -d '{
+ "url": "https://your-ngrok-url.ngrok.io/webhooks",
+ "subscriptions": ["order.*"],
+ "active": true
+}'
+spree api post /webhook_endpoints/whe_xxx/send_test
```
+</CodeGroup>
+
+`send_test` delivers a synthetic `webhook.test` event so you can verify the endpoint is reachable and your signature-verification code works, without having to trigger a real order.
+
### In Tests
```ruby
@@ -390,18 +424,27 @@ end
### Deliveries Failing
-Check the delivery record for details:
+Check the delivery records for details — each carries `error_type`, `request_errors`, `response_code`, and `response_body`. Filter the log with [Ransack predicates](/api-reference/admin-api/querying) such as `success_eq=false` or `event_name_eq`:
-```ruby
-delivery = endpoint.webhook_deliveries.failed.last
-delivery.error_type # => 'timeout' or 'connection_error'
-delivery.request_errors # => Error message
-delivery.response_code # => HTTP status code
-delivery.response_body # => Response from your endpoint
+<CodeGroup>
+
+```typescript Admin SDK
+const { data: deliveries } = await client.webhookEndpoints.deliveries.list('whe_xxx', {
+ success_eq: false,
+})
+const failed = deliveries[0]
+// failed.error_type, failed.request_errors, failed.response_code, failed.response_body
+```
+
+```bash CLI
+spree api get /webhook_endpoints/whe_xxx/deliveries -q success_eq=false
```
+</CodeGroup>
+
## Related Documentation
- [Events](/developer/core-concepts/events) - Understanding Spree's event system
+- [Admin SDK](/developer/sdk/admin/quickstart) - Setting up the `@spree/admin-sdk` client used in the management examples above
- [Customization Quickstart](/developer/customization/quickstart) - Overview of all customization options
- [Dependencies](/developer/customization/dependencies) - Customizing Spree services
diff --git a/docs/developer/how-to/custom-api-authentication.mdx b/docs/developer/how-to/custom-api-authentication.mdx
index ae9fa6adc6..1c4fbcd4be 100644
--- a/docs/developer/how-to/custom-api-authentication.mdx
+++ b/docs/developer/how-to/custom-api-authentication.mdx
@@ -1,6 +1,6 @@
---
title: Integrate a Third-Party Identity Provider
-description: Step-by-step guide to plugging a custom identity provider (Auth0, Okta, Firebase, Cognito, or any JWT issuer) into the Spree Store API.
+description: Step-by-step guide to plugging a custom identity provider (Auth0, Okta, Firebase, Cognito, or any JWT issuer) into the Spree Store and Admin APIs.
---
import { Since } from '/snippets/since.mdx';
@@ -9,21 +9,35 @@ import { Since } from '/snippets/since.mdx';
## Overview
-Spree's Store API ships with a pluggable authentication system. You register a **strategy class** for a named provider, and the existing login endpoints will dispatch to it — no controller patching, no route overrides, no fork.
+Both Spree APIs — the customer-facing **Store API** and the back-office **Admin API** — ship with the same pluggable authentication system. You register a **strategy class** for a named provider, and the existing login endpoints dispatch to it — no controller patching, no route overrides, no fork.
By the end of this guide you'll have:
- A custom strategy that verifies a third-party JWT against a JWKS endpoint
- A user account auto-provisioned on first login, reused on subsequent logins
- A standard **Spree-issued JWT + refresh token** returned to the client
-- All Store API endpoints (cart, checkout, account) protected by Spree's own JWT — the third-party token is only used at the exchange step
+- Every API endpoint protected by Spree's own JWT — the third-party token is only used at the login exchange step
-<Info>
-The same pattern works for Admin API integrations via `admin_authentication_strategies`. Examples in this guide target the Store API; substitute `Spree.admin_user_class` and the admin endpoints where noted.
-</Info>
+### Store vs Admin — what changes
+
+The mechanism is identical for both surfaces. A strategy you write works on either side; only the registry you add it to (and a handful of surface-specific details) differ:
+
+| | Store API (customers) | Admin API (staff) |
+|---|---|---|
+| Registry | `Spree.store_authentication_strategies` | `Spree.admin_authentication_strategies` |
+| User class | `Spree.user_class` | `Spree.admin_user_class` |
+| Login endpoint | `POST /api/v3/store/auth/login` | `POST /api/v3/admin/auth/login` |
+| Refresh endpoint | `POST /api/v3/store/auth/refresh` | `POST /api/v3/admin/auth/refresh` |
+| JWT audience | `aud: store_api` | `aud: admin_api` |
+| Refresh token delivery | returned in the response body | set as an `HttpOnly` cookie |
+| Strategy base class | `Spree::Authentication::Strategies::BaseStrategy` | *(same)* |
+
+Everything else — the strategy class you write, the `BaseStrategy` helpers, JWT verification, account provisioning, account linking — is the same. The walkthrough below uses the Store API; each step calls out the one-line Admin swap.
## Architecture
+The flow below uses the Store API; the Admin API is identical with `admin` in the path and `aud: admin_api` on the issued JWT.
+
```
Client → POST /api/v3/store/auth/login
{ provider: "my_idp", token: "<third-party JWT>" }
@@ -130,15 +144,35 @@ end
## Step 2: Register the Strategy
-Add the strategy to `Spree.store_authentication_strategies` in an initializer. The key you choose here is what clients will send as `provider` in the login payload.
+Add the strategy to a registry in an initializer. **This is the only line that decides which API the provider serves** — `store_authentication_strategies` for customer login, `admin_authentication_strategies` for staff login. Register with both to allow the same provider on either surface. The key you choose here is what clients send as `provider` in the login payload.
+
+<CodeGroup>
+
+```ruby Store API
+# config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.store_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
+end
+```
+
+```ruby Admin API
+# config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.admin_authentication_strategies.add(:okta, MyApp::Auth::OktaStrategy)
+end
+```
-```ruby config/initializers/spree.rb
+```ruby Both
+# config/initializers/spree.rb
Rails.application.config.after_initialize do
Spree.store_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
+ Spree.admin_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
end
```
-`Spree.store_authentication_strategies` is a `Spree::Authentication::StrategyRegistry`. The full API:
+</CodeGroup>
+
+Both registries are a `Spree::Authentication::StrategyRegistry` with the same API:
| Method | Purpose |
|---|---|
@@ -147,21 +181,23 @@ end
| `[key]` | Look up a registered class. |
| `key?(key)`, `keys`, `values`, `each`, `to_h` | Standard introspection. |
+The strategy is instantiated with the surface's user class automatically — `Spree.user_class` from the store registry, `Spree.admin_user_class` from the admin registry — and your `authenticate` reads it via the `user_class` helper, so the same class provisions customers on one side and staff on the other.
+
+<Tip>
+Restrict a surface to SSO by removing the built-in email/password strategy after adding yours: `Spree.admin_authentication_strategies.remove(:email)` locks staff to your provider; the store side stays on email/password.
+</Tip>
+
<Warning>
`Spree::UserIdentity` validates that `provider` is a registered strategy key. Registration must happen during boot — before the first login attempt.
</Warning>
-For an admin-side equivalent, register under `Spree.admin_authentication_strategies` instead and instantiate your strategy against `Spree.admin_user_class`:
-
-```ruby
-Spree.admin_authentication_strategies.add(:okta, MyApp::Auth::OktaStrategy)
-```
-
## Step 3: Call the Exchange Endpoint
-`POST /api/v3/store/auth/login` is the single dispatcher. The `provider` field in the body selects the strategy — omit it for built-in email/password, set it to your registered key for everything else. The remaining body fields are whatever your strategy reads from `params`.
+The login endpoint is the single dispatcher — `/api/v3/store/auth/login` for customers, `/api/v3/admin/auth/login` for staff. The `provider` field in the body selects the strategy — omit it for built-in email/password, set it to your registered key for everything else. The remaining body fields are whatever your strategy reads from `params`.
+
+<CodeGroup>
-```http
+```http Store API
POST /api/v3/store/auth/login
X-Spree-API-Key: pk_your_publishable_key
Content-Type: application/json
@@ -172,21 +208,49 @@ Content-Type: application/json
}
```
-The response is the standard Spree auth payload:
+```http Admin API
+POST /api/v3/admin/auth/login
+X-Spree-API-Key: sk_your_secret_key
+Content-Type: application/json
+
+{
+ "provider": "okta",
+ "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."
+}
+```
+
+</CodeGroup>
+
+The response is the standard Spree auth payload. The difference is the refresh token: the **Store API returns it in the body**, while the **Admin API sets it as an `HttpOnly` cookie** scoped to `/api/v3/admin/auth` and omits it from the body.
-```json
+<CodeGroup>
+
+```json Store API
{
"token": "<Spree HS256 JWT, aud=store_api>",
"refresh_token": "rt_xxxxxxxxxxxx",
- "user": { "id": "user_...", "email": "...", "first_name": "...", "...": "..." }
+ "user": { "id": "user_...", "email": "...", "...": "..." }
}
```
-From here, the client sends `Authorization: Bearer <Spree JWT>` on every subsequent Store API call. When the JWT expires (default: 1 hour), the client hits `POST /api/v3/store/auth/refresh` with the refresh token to rotate both.
+```json Admin API
+{
+ "token": "<Spree HS256 JWT, aud=admin_api>",
+ "user": { "id": "user_...", "email": "...", "...": "..." }
+}
+```
+
+The refresh token arrives as a `Set-Cookie: spree_admin_refresh_token=…; HttpOnly; Path=/api/v3/admin/auth` response header rather than in the body.
+
+</CodeGroup>
-From `@spree/sdk` the same call looks like:
+From here, the client sends `Authorization: Bearer <Spree JWT>` on every subsequent call. When the JWT expires (default: 1 hour), it rotates via the refresh endpoint — the Store API takes the refresh token in the body of `POST /api/v3/store/auth/refresh`; the Admin API drives `POST /api/v3/admin/auth/refresh` entirely from the cookie (see [Admin Auth & Cookie Refresh](/api-reference/admin-api/authentication)).
-```ts
+The SDKs wrap the same exchange — `@spree/sdk` for the Store API, `@spree/admin-sdk` for the Admin API:
+
+<CodeGroup>
+
+```ts Store SDK
import { createClient } from '@spree/sdk'
const client = createClient({ baseUrl: 'https://your-store.com', publishableKey: '<pk>' })
@@ -197,6 +261,20 @@ const auth = await client.auth.login({
})
```
+```ts Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({ baseUrl: 'https://your-store.com' })
+
+// Refresh token lands in the HttpOnly cookie; only the access token comes back here.
+const auth = await client.auth.login({
+ provider: 'okta',
+ token: thirdPartyJwt,
+})
+```
+
+</CodeGroup>
+
`LoginCredentials` is a discriminated union — pass `{ email, password }` for the built-in strategy, or `{ provider, ...customFields }` for any strategy you registered.
## Account Linking
@@ -232,20 +310,31 @@ end
## Logout
-```http
+<CodeGroup>
+
+```http Store API
POST /api/v3/store/auth/logout
Content-Type: application/json
{ "refresh_token": "rt_xxxxxxxxxxxx" }
```
+```http Admin API
+POST /api/v3/admin/auth/logout
+Content-Type: application/json
+
+# No body — the refresh token is read from the HttpOnly cookie and cleared.
+```
+
+</CodeGroup>
+
This revokes the Spree refresh token. The Spree JWT itself remains valid until it expires naturally (short-lived by design — default 1 hour). Spree does **not** call the IdP's revocation endpoint; if you need single sign-out, do that from the client.
## Security Notes
A few things worth getting right:
-- **Don't try to pass the third-party JWT through to protected endpoints.** Spree's `JwtAuthentication` concern verifies `iss: 'spree'` and `aud: 'store_api'` with HS256 against the Spree secret — a foreign RS256 token will never validate, and you don't want it to. The exchange-at-login model is the right one.
+- **Don't try to pass the third-party JWT through to protected endpoints.** Spree's `JwtAuthentication` concern verifies `iss: 'spree'` and the expected audience (`store_api` or `admin_api`) with HS256 against the Spree secret — a foreign RS256 token will never validate, and you don't want it to. The exchange-at-login model is the right one.
- **JWKS caching and rotation.** Cache the JWKS (the example uses a 1-hour TTL) but make sure your loader honors the `invalidate: true` option so that an unrecognized `kid` triggers a refetch. Otherwise key rotation at the IdP locks users out for up to the TTL.
- **Validate `iss` and `aud` claims.** Always. The example passes `verify_iss: true, verify_aud: true` to `JWT.decode` — don't drop those.
- **Algorithm pinning.** Hard-code `algorithms: ['RS256']` (or whatever your IdP uses). Never let the token's own `alg` header decide — the classic `alg: none` and HS-as-RS confusion attacks both exploit lax algorithm selection.
@@ -304,5 +393,6 @@ end
- `Spree::Authentication::Strategies::BaseStrategy` — `spree/core/app/models/spree/authentication/strategies/base_strategy.rb`
- `Spree::UserIdentity` — `spree/core/app/models/spree/user_identity.rb`
- `Spree::Api::V3::Store::AuthController` — `spree/api/app/controllers/spree/api/v3/store/auth_controller.rb`
+- `Spree::Api::V3::Admin::AuthController` — `spree/api/app/controllers/spree/api/v3/admin/auth_controller.rb`
- `Spree::Api::V3::JwtAuthentication` — `spree/api/app/controllers/concerns/spree/api/v3/jwt_authentication.rb`
-- See also: [Authentication](/developer/customization/authentication) for `Spree.user_class` integration.
+- See also: [Staff & Roles](/developer/core-concepts/staff-roles) for the admin login flow, [Customers](/developer/core-concepts/customers) for storefront auth, and [Authentication](/developer/customization/authentication) for `Spree.user_class` integration.
diff --git a/docs/developer/multi-store/quickstart.mdx b/docs/developer/multi-store/quickstart.mdx
index dbea2980f1..d29768824a 100644
--- a/docs/developer/multi-store/quickstart.mdx
+++ b/docs/developer/multi-store/quickstart.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Quickstart
description: Enable multiple storefronts on a single Spree app with the spree_multi_store gem, including per-store products, payment methods, taxonomies, and promotions.
---
-To enable multiple stores, you will need to add the `spree_multi_store` gem to your project via:
+To enable multiple stores, you will need to add the [spree_multi_store](/developer/multi-store/quickstart) gem to your project via:
<CodeGroup>
diff --git a/docs/developer/sdk/admin/authentication.mdx b/docs/developer/sdk/admin/authentication.mdx
index 4cb07132c1..4375ae2edb 100644
--- a/docs/developer/sdk/admin/authentication.mdx
+++ b/docs/developer/sdk/admin/authentication.mdx
@@ -80,7 +80,7 @@ try {
### Identity providers
-`auth.login()` also accepts third-party identity-provider payloads when the server has a matching strategy registered in `Spree.store_authentication_strategies`:
+`auth.login()` also accepts third-party identity-provider payloads when the server has a [matching strategy registered](/developer/how-to/custom-api-authentication):
```typescript
const { token } = await client.auth.login({ provider: 'auth0', token: idpJwt })
diff --git a/docs/developer/upgrades/5.3-to-5.4.mdx b/docs/developer/upgrades/5.3-to-5.4.mdx
index 02e2e2b1f6..2def888cef 100644
--- a/docs/developer/upgrades/5.3-to-5.4.mdx
+++ b/docs/developer/upgrades/5.3-to-5.4.mdx
@@ -258,7 +258,7 @@ And run `bundle install`
### (Optional) Install Spree Multi Store
-[Multi-store](/developer/multi-store/quickstart) features like multiple store management & custom domains were moved to a separate gem `spree_multi_store`.
+[Multi-store](/developer/multi-store/quickstart) features like multiple store management & custom domains were moved to a separate gem [spree_multi_store](/developer/multi-store/quickstart).
If you rely on these features please run:
diff --git a/docs/developer/upgrades/5.4-to-5.5.mdx b/docs/developer/upgrades/5.4-to-5.5.mdx
index 2c3a23a41c..806c7e1e73 100644
--- a/docs/developer/upgrades/5.4-to-5.5.mdx
+++ b/docs/developer/upgrades/5.4-to-5.5.mdx
@@ -138,7 +138,7 @@ This is a no-op on the default Database provider (there is no external index to
#### Multi-store catalogs
-If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming `spree_multi_store` extension restores the full `Product has_many :stores` association on top of it.
+If you have products attached to multiple stores via the legacy `spree_products_stores` join, the `populate_publications` task picks **one** "home" store per product and creates publications on every store's default channel. The `spree_products_stores` table is **kept** as legacy compat surface — the upcoming [spree_multi_store](/developer/multi-store/quickstart) extension restores the full `Product has_many :stores` association on top of it.
For single-store deployments this is invisible; you can move on without touching `spree_products_stores` again.
diff --git a/docs/docs.json b/docs/docs.json
index 78b71e9418..bd238a04ba 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -717,13 +717,6 @@
"pages": [
"integrations/marketing/klaviyo"
]
- },
- {
- "group": "SSO, MFA & Social Login",
- "pages": [
- "integrations/sso-mfa-social-login/admin-dashboard",
- "integrations/sso-mfa-social-login/storefront"
- ]
}
]
},
diff --git a/docs/integrations/integrations.mdx b/docs/integrations/integrations.mdx
index 0e4e0e6ee3..d367ac2818 100644
--- a/docs/integrations/integrations.mdx
+++ b/docs/integrations/integrations.mdx
@@ -56,13 +56,3 @@ description: "Browse Spree's third-party integrations for payments, shipping, ta
</Card>
</CardGroup>
-## SSO, MFA & Social Login
-
-<CardGroup>
- <Card title="Admin Panel SSO & MFA" href="/integrations/sso-mfa-social-login/admin-dashboard" img="/images/integrations/logos/Spree-Admin-SSO.png">
- Learn how to secure your Spree admin panel with SSO and MFA integration, using Microsoft Entra ID as an example.
- </Card>
- <Card title="Storefront SSO & Social Login" href="/integrations/sso-mfa-social-login/storefront" img="/images/integrations/logos/Spree-Social-Login.png">
- Enable customer-facing SSO and social login on your Spree storefront, using Microsoft Entra External ID as an example.
- </Card>
-</CardGroup>
diff --git a/docs/integrations/sso-mfa-social-login/admin-dashboard.mdx b/docs/integrations/sso-mfa-social-login/admin-dashboard.mdx
deleted file mode 100644
index 5fc6380875..0000000000
--- a/docs/integrations/sso-mfa-social-login/admin-dashboard.mdx
+++ /dev/null
@@ -1,66 +0,0 @@
----
-title: "SSO and MFA for the Admin Panel"
-sidebarTitle: "Admin SSO & MFA"
-description: "Learn how to secure your Spree admin panel with SSO and MFA integration, using Microsoft Entra ID as an example."
----
-
-Enterprise businesses require **Single Sign-On (SSO)** and **Multi-Factor Authentication (MFA)** to secure sensitive operations, maintain compliance, and simplify IT administration. For Spree Commerce, the **admin panel** is the heart of your business operations, which means securing access here is critical.
-
-## SSO providers
-
-There are many popular SSO providers, such as **Microsoft Entra ID**, **Okta**, **Ping Identity**, and **OneLogin**. Each provider may also offer multiple services under its ecosystem.
-
-For example, Microsoft’s SSO ecosystem includes:
-
-- **Entra ID (previously Azure Active Directory)** → secures your **Spree Commerce admin panel** for workforce users.
-- **Entra External ID (previously Active Directory B2C)** → secures your **Spree storefront** for customer-facing apps, with support for social logins like Google and Facebook.
-
-<Note>
- For the purposes of this article, we are using **Microsoft** as the example provider.
-</Note>
-
-## Why integrate SSO with MFA for the Admin Panel
-
-- **Used by staff, merchants, and operators**
-- **Integration with Entra ID** ensures employees can log in using their corporate credentials
-- Benefits include:
- - Higher security
- - Regulatory compliance (SOC2, HIPAA, GDPR)
- - Simplified IT administration
- - Better user experience with SSO
-- With Microsoft solutions, you can also enable **Multi-Factor Authentication (MFA)** or **passwordless options** (Windows Hello, FIDO2 keys) to further strengthen access security
-
-## Get Started with SSO and MFA
-
-Each SSO integration needs to be scoped individually. The integration plan depends on multiple factors, such as:
-
-- **Required SSO provider**
- - Decide whether you’ll use Microsoft Entra ID, Okta, Ping Identity, OneLogin, or another vendor. Each provider offers different features, protocols, and integration options.
-- **SSO provider settings**
- - Each provider has unique configuration details, such as OAuth endpoints, certificates, tenant IDs, and federation settings. You’ll need to gather these to complete integration.
-- **Existing or planned Spree customizations**
- - Custom authentication flows, extended user models, or unique admin permissions may affect how SSO is integrated. These should be reviewed before implementation.
-- **Spree version**
- - Compatibility matters. Integration strategies can differ depending on whether you’re on the latest Spree release.
-- **Use case: single tenant vs. multi-tenant**
- - Single-tenant stores usually need straightforward workforce SSO. Multi-tenant or SaaS-style deployments may require isolated tenant directories and more complex provisioning.
-- **Identity governance requirements** (role-based access, just-in-time provisioning)
-- **User lifecycle management** (provisioning/de-provisioning)
-- **Security posture** (MFA enforcement, conditional access, passwordless policies)
-- **Compliance certifications required** (ISO, SOC2, HIPAA, PCI DSS)
-- **Traffic scale and performance** (concurrent users, global access, load balancing)
-- **Disaster recovery and redundancy** (failover strategies)
-- **Integration with third-party services** (analytics, CDPs, data warehouses)
-
-<Info>
- Let's get in touch so we can scope your requirements and deliver this important integration for your project.
-</Info>
-
-<Columns cols={2}>
- <Card title="Book a Call" icon="eye" href="https://getvendo.com/book-a-demo/" cta="Click here">
- Schedule a call to explore the options and get your questions answered
- </Card>
- <Card title="Ask a Question" icon="dollar-sign" href="https://spreecommerce.org/get-started/" cta="Click here">
- Send us a message and share your thoughts
- </Card>
-</Columns>
diff --git a/docs/integrations/sso-mfa-social-login/storefront.mdx b/docs/integrations/sso-mfa-social-login/storefront.mdx
deleted file mode 100644
index 9cba8e86c5..0000000000
--- a/docs/integrations/sso-mfa-social-login/storefront.mdx
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: "SSO and Social Login for the Storefront"
-sidebarTitle: "Storefront SSO & Social Login"
-description: "Enable customer-facing SSO and social login on your Spree storefront, using Microsoft Entra External ID as an example."
----
-
-Enterprise businesses benefit from offering **customer-facing SSO and social login** because it streamlines the shopping experience and improves conversions. Customers prefer using accounts they already trust instead of creating new ones.
-
-## SSO providers
-
-There are many popular SSO providers, such as **Microsoft Entra External ID**, **Auth0**, **Okta**, and **Ping Identity**. Each provider may offer several services with different target use cases.
-
-For example, Microsoft’s SSO ecosystem includes:
-
-- **Entra ID (previously Azure Active Directory)** → secures your **Spree Commerce admin panel** for workforce users.
-- **Entra External ID (previously Active Directory B2C)** → secures your **Spree storefront** for customer-facing apps, with support for social logins like Google and Facebook.
-
-<Note>
- For the purposes of this article, we are using **Microsoft** as the example provider.
-</Note>
-
-## Why integrate SSO and Social Login for the Storefront
-
-- **Used by shoppers**
-- Integration with **Entra External ID (B2C)** or other customer identity providers enables frictionless sign-ups and sign-ins
-- Benefits include:
- - Reduced cart abandonment
- - Faster checkout
- - Higher conversion rates
-- Supports **social login options**: Google, Facebook, Amazon, Apple ID, Microsoft
-
-## Get Started with SSO and Social Login
-
-Each storefront integration must be scoped individually. Consider the following:
-
-- **Required SSO provider**
- - Choose from Microsoft Entra External ID, Auth0, Okta, Ping Identity, or others. Your decision depends on features, ecosystem compatibility, and scalability needs.
-- **SSO provider settings, including identity providers**
- - Each SSO platform has unique configuration settings (OAuth endpoints, certificates, client IDs). If you want to enable social logins, you’ll also need to configure providers like Google, Facebook, or Apple.
-- **Scope: social login only vs. SSO + social login**
- - Decide whether you only want to add social login on top of Spree’s existing authentication or fully replace it with a unified SSO + social login solution.
-- **Existing or planned Spree customizations**
- - Customized signup flows, checkout flows, or customer segmentation logic may impact integration design. These need to be factored in during scoping.
-- **Spree version**
- - Ensure compatibility with your Spree version. Older projects may need adjustments to take advantage of newer identity management features.
-- **Identity governance requirements** (segmentation, customer role-based access)
-- **User lifecycle management** (account creation, deactivation, syncing)
-- **Security posture** (MFA for customers, adaptive login, fraud detection)
-- **Compliance certifications required** (GDPR, CCPA, PCI DSS)
-- **Traffic scale and performance** (millions of customer accounts, peak season load)
-- **Disaster recovery and redundancy** (failover, global availability zones)
-- **Integration with third-party services** (marketing automation, CDPs, analytics, loyalty programs)
-
-<Info>
- Let's get in touch so we can scope your requirements and deliver this important integration for your project.
-</Info>
-
-<Columns cols={2}>
- <Card title="Book a Call" icon="eye" href="https://getvendo.com/book-a-demo/" cta="Click here">
- Schedule a call to explore the options and get your questions answered
- </Card>
- <Card title="Ask a Question" icon="dollar-sign" href="https://spreecommerce.org/get-started/" cta="Click here">
- Send us a message and share your thoughts
- </Card>
-</Columns>
diff --git a/docs/plans/6.0-channels-catalogs-b2b.md b/docs/plans/6.0-channels-catalogs-b2b.md
index bbaaf9a683..4796941b8a 100644
--- a/docs/plans/6.0-channels-catalogs-b2b.md
+++ b/docs/plans/6.0-channels-catalogs-b2b.md
@@ -14,9 +14,9 @@ Add three new concepts to Spree's multi-store architecture:
- **Catalog** — product assortment + optional pricing override. Controls what's available and at what price for a specific audience (B2B tier, VIP group, regional assortment).
- **Company** — B2B customer hierarchy (Company → CompanyLocation → CompanyContact) for businesses with multiple buyers and offices.
-`StoreProduct` is replaced by **ProductPublication** — the join between Product and Channel that says "this product is listed on this channel." The legacy `spree_products_stores` join table stays as compat surface for the `spree_multi_store` extension; **core no longer reads or writes it.**
+`StoreProduct` is replaced by **ProductPublication** — the join between Product and Channel that says "this product is listed on this channel." The legacy `spree_products_stores` join table stays as compat surface for the [spree_multi_store](/developer/multi-store/quickstart) extension; **core no longer reads or writes it.**
-`Product` is now `belongs_to :store` (single owner) in core. Multi-store catalog sharing — historically every `Product` belonged to many `Store`s via `spree_products_stores` — moves to the `spree_multi_store` extension. This matches Medusa/Saleor/Vendure: the catalog has one owner, distribution to multiple selling surfaces happens through channels.
+`Product` is now `belongs_to :store` (single owner) in core. Multi-store catalog sharing — historically every `Product` belonged to many `Store`s via `spree_products_stores` — moves to the [spree_multi_store](/developer/multi-store/quickstart) extension. This matches Medusa/Saleor/Vendure: the catalog has one owner, distribution to multiple selling surfaces happens through channels.
## Problem
@@ -137,7 +137,7 @@ See [`spree/core/app/models/spree/product_publication.rb`](../../spree/core/app/
- **New table `spree_product_publications`** with columns `product_id`, `channel_id`, `published_at`, `unpublished_at`, `created_at`, `updated_at`. No `store_id` column — `delegate :store, :store_id, to: :channel` for in-memory access; cross-store reporting queries join through `spree_channels`.
- **Unique index on `(product_id, channel_id)`**. `(product_id, channel_id, store_id)` was abandoned along with the in-place reshape.
- **`Spree::StoreProduct` deleted.** The class is gone in 5.5. Apps on 5.4 that referenced it directly must update to `Spree::ProductPublication`.
-- **Legacy `spree_products_stores` table left untouched.** Core no longer reads or writes it. The upcoming `spree_multi_store` extension uses it to restore the `Product has_many :stores` association for merchants who need shared catalogs across stores.
+- **Legacy `spree_products_stores` table left untouched.** Core no longer reads or writes it. The upcoming [spree_multi_store](/developer/multi-store/quickstart) extension uses it to restore the `Product has_many :stores` association for merchants who need shared catalogs across stores.
`prefix :pp`, validates `(product, channel)`, validates `unpublished_at_after_published_at`, has a `published` scope.
@@ -411,7 +411,7 @@ end
- `Spree::ProductPublication` on the new `spree_product_publications` table — no `store_id` column, `store`/`store_id` delegated to `channel`.
- `Spree::Product belongs_to :store` (single). `for_store(store)` scope is now `where(store_id: store.id)` (was a join through publications).
- `Spree::Product::Channels` concern owns `has_many :product_publications`, `has_many :channels through:`, the deprecated `available_on=`/`discontinue_on=` cascade, and the SPA's `product_publications=` hash-array setter. **No `set_default_publication` callback** — explicit publishing only.
-- `Spree::Product::LegacyMultiStoreSupport` concern owns `#stores` / `#stores=` / `#store_ids` / `#store_ids=` deprecation bridges (auto-included unless `SpreeMultiStore` is defined; the `spree_multi_store` extension supersedes them).
+- `Spree::Product::LegacyMultiStoreSupport` concern owns `#stores` / `#stores=` / `#store_ids` / `#store_ids=` deprecation bridges (auto-included unless `SpreeMultiStore` is defined; the [spree_multi_store](/developer/multi-store/quickstart) extension supersedes them).
- `Spree::Product.available` / `.active` / `.not_discontinued` scopes are channel-aware via `Spree::Current.channel`; jobs/rake without channel context use the legacy column fallback path.
- `Spree::Channel#add_products` / `#remove_products` are the canonical bulk publishing API (used by both bulk-action controllers and the legacy/SPA Publishing cards).
- `Spree::Current.channel` + `X-Spree-Channel` header resolution in API v3 base controller. Falls back to `current_store.default_channel`.
@@ -578,7 +578,7 @@ DELETE /api/v3/admin/company_contacts/:id
Most of the planned 6.0 cleanup already happened in 5.5 (cleaner data model from the start). Remaining items:
- Drop `Spree::Product.available_on`, `Spree::Product.discontinue_on`, `Spree::Product.make_active_at` columns and the deprecated setters in `Spree::Product::Channels`.
-- Drop `Spree::Product::LegacyMultiStoreSupport` (multi-store catalogs live in the `spree_multi_store` extension from 5.5 onward).
+- Drop `Spree::Product::LegacyMultiStoreSupport` (multi-store catalogs live in the [spree_multi_store](/developer/multi-store/quickstart) extension from 5.5 onward).
- Drop `Spree::Product.for_store`'s legacy column-fallback branch (`Spree::Product.available` / `.not_discontinued` always use publications once `Spree::Current.channel` is unconditionally set).
- Make `spree_products.store_id` `NOT NULL` (it's nullable in 5.5 to accommodate the post-migrate / pre-backfill window).
- Drop `spree_orders.channel` string column (5.5+ already ignores it via `ignored_columns`).
@@ -587,13 +587,13 @@ Most of the planned 6.0 cleanup already happened in 5.5 (cleaner data model from
**Already done in 5.5 (don't redo in 6.0):**
- ~~Drop `Spree::StoreProduct` STI subclass~~ — deleted in 5.5.
- ~~Drop `store_id` column from the publications table~~ — new `spree_product_publications` table never had it.
-- ~~Rename `spree_products_stores` → `spree_product_publications`~~ — new table created; legacy `spree_products_stores` left for `spree_multi_store`.
+- ~~Rename `spree_products_stores` → `spree_product_publications`~~ — new table created; legacy `spree_products_stores` left for [spree_multi_store](/developer/multi-store/quickstart).
## Constraints on Current Work
- **`Spree::StoreProduct` is gone.** Use `Spree::ProductPublication` directly. Don't reintroduce the STI alias or any reference to `spree/core/app/models/spree/store_product.rb`.
- **`Spree::ProductPublication` has no `store_id` column.** It's delegated to `channel.store`. Don't write code that calls `ProductPublication.where(store_id: …)` — use a join: `Publication.joins(:channel).where(spree_channels: { store_id: … })`.
-- **`Product belongs_to :store` (single).** Don't write new code assuming `product.stores` is a real ActiveRecord association — the deprecation bridge returns `Array(store)` and won't chain. Multi-store catalogs live in `spree_multi_store`.
+- **`Product belongs_to :store` (single).** Don't write new code assuming `product.stores` is a real ActiveRecord association — the deprecation bridge returns `Array(store)` and won't chain. Multi-store catalogs live in [spree_multi_store](/developer/multi-store/quickstart).
- **`Channel#default` is a boolean column.** Use `Spree::Channel.default.where(store: …)` or `store.default_channel`. Don't look up by `code: 'online'` — merchants can rename it.
- **Channel-aware scopes assume `Spree::Current.channel` is set.** API requests set it via the X-Spree-Channel header concern; jobs / rake tasks fall back to the legacy column path. Don't add new code that reads `Spree::Current.channel` without expecting either branch.
- **`Spree::Channel#add_products` is idempotent and preserves existing publication windows** when called without `published_at` / `unpublished_at` kwargs. Don't change this — bulk-publish ergonomics depend on it.
@@ -608,9 +608,9 @@ Most of the planned 6.0 cleanup already happened in 5.5 (cleaner data model from
3. **Auto-publish on product create.** Admin API: **no** auto-publish — the caller supplies `product_publications: [{ channel_id }]`. Dashboard SPA's create form: **yes**, auto-publishes on `Channel#default == true` (Shopify-style). Sample data: explicitly publishes via `Loader#publish_sample_products`. The `set_default_publication` model callback was removed — moving the decision to the layer that knows the merchant's intent.
-4. **Multi-store catalogs.** Core Spree 5.5+ models Product as `belongs_to :store` (single owner). Merchants who need shared catalogs across stores install the `spree_multi_store` extension, which restores `has_many :stores, through: :spree_products_stores` on top of the legacy join table. Matches the Medusa/Saleor/Vendure pattern (channels are the multi-brand primitive, stores are the tenant root).
+4. **Multi-store catalogs.** Core Spree 5.5+ models Product as `belongs_to :store` (single owner). Merchants who need shared catalogs across stores install the [spree_multi_store](/developer/multi-store/quickstart) extension, which restores `has_many :stores, through: :spree_products_stores` on top of the legacy join table. Matches the Medusa/Saleor/Vendure pattern (channels are the multi-brand primitive, stores are the tenant root).
-5. **Cross-store onboarding via `Channel#add_products`.** Allowed: if a multi-store admin's API key has update permission on a product owned by sibling store A, calling `POST /admin/channels/:id/add_products` (where the channel belongs to store B) co-publishes the product onto store B's channel. The product's owning `store_id` doesn't change. This is the path by which the `spree_multi_store` extension's "publish across stores" UX threads through core.
+5. **Cross-store onboarding via `Channel#add_products`.** Allowed: if a multi-store admin's API key has update permission on a product owned by sibling store A, calling `POST /admin/channels/:id/add_products` (where the channel belongs to store B) co-publishes the product onto store B's channel. The product's owning `store_id` doesn't change. This is the path by which the [spree_multi_store](/developer/multi-store/quickstart) extension's "publish across stores" UX threads through core.
6. **Catalog auto-sync.** Manual assignment only for 6.0, with bulk product assignment via Admin API (`POST /catalogs/:id/products/bulk`). Auto-sync using CollectionRule-style patterns is a future enhancement.
diff --git a/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb
index 78965fcfce..bc9b6ec483 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb
@@ -18,16 +18,16 @@ RSpec.describe 'Admin Authentication API', type: :request, swagger_doc: 'api-ref
The rotatable refresh token is set in an HttpOnly cookie — it is not
included in the response body.
- Dispatches by the `provider` field to a strategy registered in
- `Spree.admin_authentication_strategies`. When `provider` is omitted it
- defaults to `email`, which uses the built-in email/password strategy.
-
- To plug in a third-party identity provider (Okta, Azure AD, Google
- Workspace SSO, a custom JWT issuer, SAML, etc.), register a
- `Spree::Authentication::Strategies::BaseStrategy` subclass under a
- provider key, then send `{ "provider": "<your_key>", ... }` with the
- fields your strategy requires. The endpoint returns the same Spree-issued
- JWT regardless of which strategy authenticated the request.
+ The `provider` field selects the authentication method. When omitted it
+ defaults to `email`, the built-in email/password login.
+
+ To authenticate against a third-party identity provider (Okta, Azure AD,
+ Google Workspace SSO, a custom JWT issuer, SAML, etc.), send
+ `{ "provider": "<your_key>", ... }` with the fields that provider
+ requires. The endpoint returns the same JWT regardless of which provider
+ authenticated the request. See
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
+ for the list of configured providers and their required fields.
DESC
admin_sdk_example 'auth/login'
@@ -49,10 +49,10 @@ RSpec.describe 'Admin Authentication API', type: :request, swagger_doc: 'api-ref
{
title: 'ProviderLogin',
description: <<~D,
- Provider-dispatched login. The `provider` key selects a registered
- strategy class; the remaining fields are forwarded to the strategy's
- `authenticate` method. Required fields depend on the registered strategy
- — consult its documentation.
+ Provider-dispatched login. The `provider` key selects a configured
+ authentication provider; the remaining fields are forwarded to it.
+ Required fields depend on the provider — see
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
D
type: :object,
properties: {
diff --git a/spree/api/spec/integration/spree/api/v3/store/auth_spec.rb b/spree/api/spec/integration/spree/api/v3/store/auth_spec.rb
index 6c8b1957e7..794b15011f 100644
--- a/spree/api/spec/integration/spree/api/v3/store/auth_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/auth_spec.rb
@@ -16,16 +16,16 @@ RSpec.describe 'Authentication API', type: :request, swagger_doc: 'api-reference
description <<~DESC
Authenticates a customer and returns a JWT access token + refresh token.
- Dispatches by the `provider` field to a strategy registered in
- `Spree.store_authentication_strategies`. When `provider` is omitted it
- defaults to `email`, which uses the built-in email/password strategy.
-
- To plug in a third-party identity provider (Auth0, Okta, Firebase, a
- custom JWT issuer, SAML, etc.), register a `Spree::Authentication::Strategies::BaseStrategy`
- subclass under a provider key, then send `{ "provider": "<your_key>", ... }`
- with the fields your strategy requires. The endpoint returns the same
- Spree-issued JWT + refresh token regardless of which strategy authenticated
- the request.
+ The `provider` field selects the authentication method. When omitted it
+ defaults to `email`, the built-in email/password login.
+
+ To authenticate against a third-party identity provider (Auth0, Okta,
+ Firebase, a custom JWT issuer, SAML, etc.), send
+ `{ "provider": "<your_key>", ... }` with the fields that provider
+ requires. The endpoint returns the same JWT + refresh token regardless of
+ which provider authenticated the request. See
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
+ for the list of configured providers and their required fields.
DESC
sdk_example 'auth/login'
@@ -47,10 +47,10 @@ RSpec.describe 'Authentication API', type: :request, swagger_doc: 'api-reference
{
title: 'ProviderLogin',
description: <<~D,
- Provider-dispatched login. The `provider` key selects a registered
- strategy class; the remaining fields are forwarded to the strategy's
- `authenticate` method. Required fields depend on the registered strategy
- — consult its documentation.
+ Provider-dispatched login. The `provider` key selects a configured
+ authentication provider; the remaining fields are forwarded to it.
+ Required fields depend on the provider — see
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
D
type: :object,
properties: {