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.

Hardening Admin API scopes

Damian Legawiec8a7f5341269e
diff --git a/CLAUDE.md b/CLAUDE.md
index 0843f83257..3b436dd1f5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,6 +42,7 @@ Multi-version plans (some phases shipped, some pending):
Pending design work (drafts, no implementation yet):
- `5.4-centralized-translations-admin.md` — Centralized Translations admin page under Products, overview grid + bulk CSV import/export
- `5.4-metafield-translations.md` — Translate MetafieldDefinition names + Metafield text values (ShortText, LongText, RichText) via Mobility translation tables
+- `5.5-admin-api-cli.md` — `spree api` command group in `@spree/cli` (gh-api-style generic verbs + schema introspection + layered auth, CLI-first ahead of MCP servers; core patch: `SCOPES` on `spree:cli:create_api_key`, promotions scopes)
Shipped plans:
- `5.4-store-api-bridges.md` — Bridge 6.0 naming into 5.4 Store API (PR #13782)
@@ -54,6 +55,7 @@ Shipped plans:
- `5.5-admin-auth-cookie-refresh.md` — Admin SPA refresh token in httpOnly cookie, access token in memory, server-side logout
- `5.5-admin-customers-api.md` — Admin Customers + nested addresses/credit_cards/store_credits + CustomerGroups
- `5.5-admin-spa-csv-export.md` — Admin API ExportsController + admin-sdk + `useExport` + toolbar export button
+- `5.5-agent-skills.md` — `spree/agent-skills` standalone repo: 25 Claude Code skills + `spree-expert` subagent + safety hooks, distributed via `npx skills add spree/agent-skills`
## Monorepo Structure
diff --git a/docs/api-reference/admin-api/authentication.mdx b/docs/api-reference/admin-api/authentication.mdx
index 3d7db2c62d..e82a53d543 100644
--- a/docs/api-reference/admin-api/authentication.mdx
+++ b/docs/api-reference/admin-api/authentication.mdx
@@ -113,19 +113,32 @@ Authorization works differently depending on which credentials you use.
Each secret API key carries a list of **scopes** that grant access to specific resources. Scopes follow a `read_<resource>` / `write_<resource>` convention; `write_<resource>` implies `read_<resource>`.
-| Scope | Endpoints |
+| Scope | Grants access to |
|---|---|
-| `read_orders` / `write_orders` | `/orders/*`, `/orders/:id/items` |
-| `read_products` / `write_products` | `/products/*`, `/variants/*`, `/option_types/*`, `/media/*` |
-| `read_customers` / `write_customers` | `/customers/*`, `/customers/:id/addresses`, `/customers/:id/credit_cards` |
-| `read_payments` / `write_payments` | `/orders/:id/payments` |
+| `read_orders` / `write_orders` | `/orders/*` — including nested items and adjustments |
+| `read_products` / `write_products` | `/products/*`, `/variants/*`, `/option_types/*`, `/media/*`, `/prices/*`, `/price_lists/*` |
+| `read_promotions` / `write_promotions` | `/promotions/*` — including nested rules, actions, and coupon codes |
+| `read_customers` / `write_customers` | `/customers/*`, `/customer_groups/*` — including nested addresses and credit cards |
+| `read_payments` / `write_payments` | `/orders/:id/payments` — including capture and void |
| `read_fulfillments` / `write_fulfillments` | `/orders/:id/fulfillments` |
| `read_refunds` / `write_refunds` | `/orders/:id/refunds` |
-| `read_gift_cards` / `write_gift_cards` | `/orders/:id/gift_cards` |
+| `read_gift_cards` / `write_gift_cards` | `/gift_cards/*`, `/gift_card_batches/*`, `/orders/:id/gift_cards` |
| `read_store_credits` / `write_store_credits` | `/customers/:id/store_credits`, `/orders/:id/store_credits` |
+| `read_stock` / `write_stock` | `/stock_locations/*`, `/stock_items/*`, `/stock_transfers/*`, `/stock_reservations/*` |
| `read_categories` / `write_categories` | `/categories/*` |
-| `read_settings` / `write_settings` | `/payment_methods`, `/markets`, `/countries`, `/tax_categories`, `/store` |
-| `read_dashboard` | `/dashboard/*` (analytics) |
+| `read_settings` / `write_settings` | Store configuration — `/store`, `/payment_methods/*`, `/markets/*`, `/channels/*`, `/tax_categories/*`, `/countries`, `/custom_field_definitions/*`, `/store_credit_categories/*`, staff management (`/admin_users`, `/invitations`, `/roles`), `/allowed_origins/*` |
+| `read_webhooks` / `write_webhooks` | `/webhook_endpoints/*` — including delivery logs and redelivery |
+| `read_api_keys` / `write_api_keys` | `/api_keys/*` — creating, revoking, and deleting API keys |
+| `read_dashboard` | `/dashboard/*` (analytics; read-only) |
+
+Custom field **values** are gated by the resource they're attached to: a `write_products` key can manage custom fields on products, variants, and option types; `write_orders` covers order custom fields, and so on. Custom field **definitions** (the schema) are part of `settings`.
+
+**Exports have no scope of their own.** An export is a bulk read, so each export type (`/exports/*`) is gated by the read scope of the resource it exports — `read_customers` lets a key create and download customer exports, `read_promotions` covers coupon-code exports, and so on. The exports list only shows the types the key can read, so a key can never export data it couldn't read through the API directly.
+
+Two scopes are deliberately separate from `settings` because they're security-sensitive:
+
+- **`webhooks`** — webhook endpoints receive event payloads (orders, customers) at whatever URL they point to, so the ability to create them is its own grant.
+- **`api_keys`** — credential management. A key holding `write_api_keys` can create new keys, but only with scopes it already holds itself; scopes can never be amplified through the API.
Two convenience aliases:
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index b013a60a06..77521e1a9e 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -89,15 +89,15 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRlZjA1MzY0LTY2ODctNDY3My1hNDI4LWNjZDI1ODc4YjVjZSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgwOTE2NDk2fQ.4EH3Xu8aKDP0u0jtmqrcOOR9okXtEtJFZLw-YdP4sPM
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImUyMzYxNTc5LWMxZDMtNDc0Yi1hM2E1LTcwNWMzYTZmMGUxYSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgxMjg1MzI3fQ.5GaxxoaCeEEpGgum01ZV0z56ZpHDWaFSyX_KvEob3ws
user:
id: admin_UkLWZg9DAJ
- first_name: Daina
- last_name: Braun
- full_name: Daina Braun
- created_at: '2026-06-08T10:56:35.975Z'
- updated_at: '2026-06-08T10:56:35.975Z'
+ first_name: Lisandra
+ last_name: Dare
+ full_name: Lisandra Dare
+ created_at: '2026-06-12T17:23:47.304Z'
+ updated_at: '2026-06-12T17:23:47.304Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -192,15 +192,15 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBhNTEyYmI5LTlkNjAtNDdjYi04ZjlhLTFiYTM0MWY4MjIzZSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgwOTE2NDk3fQ.eNWcAS3Rm1pAljK2jUjWhfYkqzjk6wraljD5m4DgKvM
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjYxNTkwZmYyLWEwMTctNDUyZi05ZjQ3LTBhM2JhYWZlYWQ0YiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgxMjg1MzI4fQ.l53NCGqm7_mD8L54Wq7AB86HGHqolGJEplh7Dg_QqJw
user:
id: admin_UkLWZg9DAJ
- first_name: Roman
- last_name: Cruickshank
- full_name: Roman Cruickshank
- created_at: '2026-06-08T10:56:37.206Z'
- updated_at: '2026-06-08T10:56:37.206Z'
+ first_name: Lavonda
+ last_name: Bogan
+ full_name: Lavonda Bogan
+ created_at: '2026-06-12T17:23:48.682Z'
+ updated_at: '2026-06-12T17:23:48.682Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -291,12 +291,12 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Corazon
- last_name: O'Hara
- full_name: Corazon O'Hara
- created_at: '2026-06-08T10:57:08.989Z'
- updated_at: '2026-06-08T10:57:08.989Z'
+ first_name: Thelma
+ last_name: Cronin
+ full_name: Thelma Cronin
+ created_at: '2026-06-12T17:24:22.538Z'
+ updated_at: '2026-06-12T17:24:22.538Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -444,8 +444,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-06-08T10:56:31.241Z'
- updated_at: '2026-06-08T10:56:31.241Z'
+ created_at: '2026-06-12T17:23:42.410Z'
+ updated_at: '2026-06-12T17:23:42.410Z'
meta:
page: 1
limit: 25
@@ -526,8 +526,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-06-08T10:56:31.844Z'
- updated_at: '2026-06-08T10:56:31.844Z'
+ created_at: '2026-06-12T17:23:43.075Z'
+ updated_at: '2026-06-12T17:23:43.075Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -611,8 +611,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-06-08T10:56:32.140Z'
- updated_at: '2026-06-08T10:56:32.140Z'
+ created_at: '2026-06-12T17:23:43.396Z'
+ updated_at: '2026-06-12T17:23:43.396Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -670,8 +670,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-06-08T10:56:32.711Z'
- updated_at: '2026-06-08T10:56:33.092Z'
+ created_at: '2026-06-12T17:23:44.064Z'
+ updated_at: '2026-06-12T17:23:44.366Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -749,7 +749,7 @@ paths:
description: |-
Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -785,32 +785,32 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-06-08T10:56:33.709Z'
- updated_at: '2026-06-08T10:56:33.709Z'
+ created_at: '2026-06-12T17:23:45.015Z'
+ updated_at: '2026-06-12T17:23:45.015Z'
revoked_at:
last_used_at:
- plaintext_token: pk_WvcXSjJcJDQJRqu1Yu1vp5yS
+ plaintext_token: pk_5AskmHCv2omYyoBr3mehREcX
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_uXxj3uHMQ
+ token_prefix: sk_qBGxwGooh
scopes:
- write_all
- created_at: '2026-06-08T10:56:33.710Z'
- updated_at: '2026-06-08T10:56:33.710Z'
+ created_at: '2026-06-12T17:23:45.016Z'
+ updated_at: '2026-06-12T17:23:45.016Z'
revoked_at:
last_used_at:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: porro
+ name: minima
key_type: secret
- token_prefix: sk_94S7QchKz
+ token_prefix: sk_2bVt6n2wq
scopes:
- write_all
- created_at: '2026-06-08T10:56:33.711Z'
- updated_at: '2026-06-08T10:56:33.711Z'
+ created_at: '2026-06-12T17:23:45.017Z'
+ updated_at: '2026-06-12T17:23:45.017Z'
revoked_at:
last_used_at:
plaintext_token:
@@ -835,7 +835,7 @@ paths:
description: |-
Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -873,15 +873,15 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_F2iuHSN5C
+ token_prefix: sk_vGdftBeFe
scopes:
- read_orders
- created_at: '2026-06-08T10:56:34.280Z'
- updated_at: '2026-06-08T10:56:34.280Z'
+ created_at: '2026-06-12T17:23:45.625Z'
+ updated_at: '2026-06-12T17:23:45.625Z'
revoked_at:
last_used_at:
- plaintext_token: sk_F2iuHSN5CzK3PoX8AeCMNnAZ
- created_by_email: [email protected]
+ plaintext_token: sk_vGdftBeFecVvHg1towF93knP
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -927,7 +927,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_settings` (for API-key authentication)."
+ description: "**Required scope:** `read_api_keys` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -967,11 +967,11 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-06-08T10:56:34.628Z'
- updated_at: '2026-06-08T10:56:34.628Z'
+ created_at: '2026-06-12T17:23:45.944Z'
+ updated_at: '2026-06-12T17:23:45.944Z'
revoked_at:
last_used_at:
- plaintext_token: pk_T4HNwJvZLLhdNZnbqgti7bem
+ plaintext_token: pk_bZ5pTDmsuFozzLiikk62bCgQ
created_by_email:
delete:
summary: Delete an API key
@@ -980,7 +980,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_settings` (for API-key authentication)."
+ description: "**Required scope:** `write_api_keys` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -1023,7 +1023,7 @@ paths:
description: |-
Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -1061,12 +1061,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_oZErCBJ7u
+ token_prefix: sk_PVNjbM3kV
scopes:
- write_all
- created_at: '2026-06-08T10:56:35.282Z'
- updated_at: '2026-06-08T10:56:35.644Z'
- revoked_at: '2026-06-08T10:56:35.643Z'
+ created_at: '2026-06-12T17:23:46.589Z'
+ updated_at: '2026-06-12T17:23:47.008Z'
+ revoked_at: '2026-06-12T17:23:47.006Z'
last_used_at:
plaintext_token:
created_by_email:
@@ -1116,16 +1116,16 @@ paths:
active: true
default: true
preferred_order_routing_strategy:
- created_at: '2026-06-08T10:56:29.986Z'
- updated_at: '2026-06-08T10:56:29.986Z'
+ created_at: '2026-06-12T17:23:41.100Z'
+ updated_at: '2026-06-12T17:23:41.100Z'
- id: ch_gbHJdmfrXB
name: Wholesale
code: wholesale
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-08T10:56:37.801Z'
- updated_at: '2026-06-08T10:56:37.801Z'
+ created_at: '2026-06-12T17:23:49.367Z'
+ updated_at: '2026-06-12T17:23:49.367Z'
meta:
page: 1
limit: 25
@@ -1185,8 +1185,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-08T10:56:38.384Z'
- updated_at: '2026-06-08T10:56:38.384Z'
+ created_at: '2026-06-12T17:23:50.024Z'
+ updated_at: '2026-06-12T17:23:50.024Z'
requestBody:
content:
application/json:
@@ -1243,8 +1243,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-08T10:56:38.395Z'
- updated_at: '2026-06-08T10:56:38.395Z'
+ created_at: '2026-06-12T17:23:50.035Z'
+ updated_at: '2026-06-12T17:23:50.035Z'
patch:
summary: Update a channel
tags:
@@ -1276,8 +1276,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-08T10:56:38.681Z'
- updated_at: '2026-06-08T10:56:38.986Z'
+ created_at: '2026-06-12T17:23:50.514Z'
+ updated_at: '2026-06-12T17:23:50.908Z'
requestBody:
content:
application/json:
@@ -1442,7 +1442,7 @@ paths:
description: |-
Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.
- **Required scope:** `read_custom_field_definitions` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -1496,8 +1496,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-08T10:56:40.300Z'
- updated_at: '2026-06-08T10:56:40.300Z'
+ created_at: '2026-06-12T17:23:52.898Z'
+ updated_at: '2026-06-12T17:23:52.898Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -1505,8 +1505,8 @@ paths:
field_type: short_text
resource_type: Spree::Order
storefront_visible: true
- created_at: '2026-06-08T10:56:40.301Z'
- updated_at: '2026-06-08T10:56:40.301Z'
+ created_at: '2026-06-12T17:23:52.900Z'
+ updated_at: '2026-06-12T17:23:52.900Z'
meta:
page: 1
limit: 25
@@ -1524,8 +1524,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_custom_field_definitions` (for API-key
- authentication)."
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -1569,8 +1568,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-08T10:56:40.884Z'
- updated_at: '2026-06-08T10:56:40.884Z'
+ created_at: '2026-06-12T17:23:53.559Z'
+ updated_at: '2026-06-12T17:23:53.559Z'
requestBody:
content:
application/json:
@@ -1608,8 +1607,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_custom_field_definitions` (for API-key
- authentication)."
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
parameters:
- name: x-spree-api-key
in: header
@@ -1653,8 +1651,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-08T10:56:40.891Z'
- updated_at: '2026-06-08T10:56:40.891Z'
+ created_at: '2026-06-12T17:23:53.566Z'
+ updated_at: '2026-06-12T17:23:53.566Z'
patch:
summary: Update a custom field definition
tags:
@@ -1662,8 +1660,7 @@ paths:
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_custom_field_definitions` (for API-key
- authentication)."
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
parameters:
- name: x-spree-api-key
in: header
@@ -1693,8 +1690,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: false
- created_at: '2026-06-08T10:56:41.172Z'
- updated_at: '2026-06-08T10:56:41.449Z'
+ created_at: '2026-06-12T17:23:53.886Z'
+ updated_at: '2026-06-12T17:23:54.207Z'
requestBody:
content:
application/json:
@@ -1715,7 +1712,7 @@ paths:
description: |-
Deletes the definition and cascades to all custom field values referencing it.
- **Required scope:** `write_custom_field_definitions` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -1818,14 +1815,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-06-08T10:56:41.734Z'
- updated_at: '2026-06-08T10:56:41.734Z'
+ created_at: '2026-06-12T17:23:54.579Z'
+ updated_at: '2026-06-12T17:23:54.579Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-06-08T10:56:41.735Z'
- updated_at: '2026-06-08T10:56:41.735Z'
+ created_at: '2026-06-12T17:23:54.580Z'
+ updated_at: '2026-06-12T17:23:54.580Z'
meta:
page: 1
limit: 25
@@ -1910,8 +1907,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-06-08T10:56:42.582Z'
- updated_at: '2026-06-08T10:56:42.582Z'
+ created_at: '2026-06-12T17:23:55.564Z'
+ updated_at: '2026-06-12T17:23:55.564Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -2017,24 +2014,24 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-06-08T10:56:43.161Z'
- updated_at: '2026-06-08T10:56:43.161Z'
+ created_at: '2026-06-12T17:23:56.255Z'
+ updated_at: '2026-06-12T17:23:56.255Z'
customers:
- id: cus_UkLWZg9DAJ
- first_name: Santo
- last_name: Walsh
+ first_name: Karly
+ last_name: Labadie
phone:
accepts_email_marketing: false
- full_name: Santo Walsh
+ full_name: Karly Labadie
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-08T10:56:43.423Z'
- updated_at: '2026-06-08T10:56:43.423Z'
+ created_at: '2026-06-12T17:23:56.566Z'
+ updated_at: '2026-06-12T17:23:56.566Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -2112,8 +2109,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-06-08T10:56:44.004Z'
- updated_at: '2026-06-08T10:56:44.278Z'
+ created_at: '2026-06-12T17:23:57.311Z'
+ updated_at: '2026-06-12T17:23:57.647Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -2266,8 +2263,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-06-08T10:56:45.123Z'
- updated_at: '2026-06-08T10:56:45.123Z'
+ created_at: '2026-06-12T17:23:58.540Z'
+ updated_at: '2026-06-12T17:23:58.540Z'
customer_id: cus_UkLWZg9DAJ
meta:
page: 1
@@ -2355,8 +2352,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-06-08T10:56:46.478Z'
- updated_at: '2026-06-08T10:56:46.478Z'
+ created_at: '2026-06-12T17:23:59.952Z'
+ updated_at: '2026-06-12T17:23:59.952Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -2467,8 +2464,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-06-08T10:56:46.752Z'
- updated_at: '2026-06-08T10:56:47.297Z'
+ created_at: '2026-06-12T17:24:00.227Z'
+ updated_at: '2026-06-12T17:24:00.777Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -2601,8 +2598,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-06-08T10:56:48.396Z'
- updated_at: '2026-06-08T10:56:48.396Z'
+ created_at: '2026-06-12T17:24:01.924Z'
+ updated_at: '2026-06-12T17:24:01.924Z'
meta:
page: 1
limit: 25
@@ -2689,8 +2686,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-06-08T10:56:48.944Z'
- updated_at: '2026-06-08T10:56:48.944Z'
+ created_at: '2026-06-12T17:24:02.498Z'
+ updated_at: '2026-06-12T17:24:02.498Z'
delete:
summary: Delete a customer credit card
tags:
@@ -2809,8 +2806,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-06-08T10:56:50.298Z'
- updated_at: '2026-06-08T10:56:50.298Z'
+ created_at: '2026-06-12T17:24:03.896Z'
+ updated_at: '2026-06-12T17:24:03.896Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -2885,8 +2882,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-06-08T10:56:51.478Z'
- updated_at: '2026-06-08T10:56:51.478Z'
+ created_at: '2026-06-12T17:24:05.013Z'
+ updated_at: '2026-06-12T17:24:05.013Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -2977,8 +2974,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-06-08T10:56:52.025Z'
- updated_at: '2026-06-08T10:56:52.343Z'
+ created_at: '2026-06-12T17:24:05.556Z'
+ updated_at: '2026-06-12T17:24:05.841Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -3132,8 +3129,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-08T10:56:53.476Z'
- updated_at: '2026-06-08T10:56:53.476Z'
+ created_at: '2026-06-12T17:24:06.985Z'
+ updated_at: '2026-06-12T17:24:06.985Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3216,8 +3213,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-08T10:56:54.324Z'
- updated_at: '2026-06-08T10:56:54.324Z'
+ created_at: '2026-06-12T17:24:07.836Z'
+ updated_at: '2026-06-12T17:24:07.836Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3333,8 +3330,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-08T10:56:54.595Z'
- updated_at: '2026-06-08T10:56:54.595Z'
+ created_at: '2026-06-12T17:24:08.112Z'
+ updated_at: '2026-06-12T17:24:08.112Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3408,8 +3405,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-08T10:56:55.159Z'
- updated_at: '2026-06-08T10:56:55.444Z'
+ created_at: '2026-06-12T17:24:08.673Z'
+ updated_at: '2026-06-12T17:24:08.959Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3807,7 +3804,7 @@ paths:
description: |-
Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).
- **Required scope:** `read_exports` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -3839,11 +3836,11 @@ paths:
example:
data:
- id: exp_UkLWZg9DAJ
- number: EF093047115
+ number: EF801500147
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-08T10:56:59.677Z'
- updated_at: '2026-06-08T10:56:59.677Z'
+ created_at: '2026-06-12T17:24:13.131Z'
+ updated_at: '2026-06-12T17:24:13.131Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -3876,7 +3873,7 @@ paths:
then redirect the browser to `download_url` to fetch the file.
- **Required scope:** `write_exports` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -3910,11 +3907,11 @@ paths:
application/json:
example:
id: exp_gbHJdmfrXB
- number: EF199522264
+ number: EF876181108
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-08T10:57:00.017Z'
- updated_at: '2026-06-08T10:57:00.017Z'
+ created_at: '2026-06-12T17:24:13.433Z'
+ updated_at: '2026-06-12T17:24:13.433Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -3965,7 +3962,7 @@ paths:
description: |-
Returns export status. While `done` is `false`, the SPA continues polling.
- **Required scope:** `read_exports` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -4001,11 +3998,11 @@ paths:
application/json:
example:
id: exp_UkLWZg9DAJ
- number: EF025250323
+ number: EF904215811
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-08T10:57:00.306Z'
- updated_at: '2026-06-08T10:57:00.306Z'
+ created_at: '2026-06-12T17:24:13.722Z'
+ updated_at: '2026-06-12T17:24:13.722Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4021,7 +4018,7 @@ paths:
description: |-
Removes the export and purges its attachment.
- **Required scope:** `write_exports` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -4064,7 +4061,7 @@ paths:
description: |-
Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.
- **Required scope:** `read_exports` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -4178,7 +4175,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H37428731748
+ number: H35590720789
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4203,8 +4200,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:11.692Z'
- updated_at: '2026-06-08T10:57:11.766Z'
+ created_at: '2026-06-12T17:24:25.258Z'
+ updated_at: '2026-06-12T17:24:25.352Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -4287,7 +4284,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H58592161546
+ number: H01928147257
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4312,8 +4309,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:12.372Z'
- updated_at: '2026-06-08T10:57:12.428Z'
+ created_at: '2026-06-12T17:24:25.980Z'
+ updated_at: '2026-06-12T17:24:26.039Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -4372,7 +4369,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H48155201967
+ number: H47992763995
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -4397,8 +4394,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:13.024Z'
- updated_at: '2026-06-08T10:57:13.385Z'
+ created_at: '2026-06-12T17:24:26.652Z'
+ updated_at: '2026-06-12T17:24:27.050Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -4467,7 +4464,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H51880549825
+ number: H21297889426
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4484,7 +4481,7 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-06-08T10:57:14Z'
+ fulfilled_at: '2026-06-12T17:24:27Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -4492,8 +4489,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:13.742Z'
- updated_at: '2026-06-08T10:57:14.099Z'
+ created_at: '2026-06-12T17:24:27.408Z'
+ updated_at: '2026-06-12T17:24:27.765Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -4551,7 +4548,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H11992775783
+ number: H36610642534
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4576,8 +4573,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:14.457Z'
- updated_at: '2026-06-08T10:57:14.855Z'
+ created_at: '2026-06-12T17:24:28.103Z'
+ updated_at: '2026-06-12T17:24:28.447Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -4635,7 +4632,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H79014622748
+ number: H84093050628
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4660,8 +4657,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:15.195Z'
- updated_at: '2026-06-08T10:57:15.547Z'
+ created_at: '2026-06-12T17:24:28.839Z'
+ updated_at: '2026-06-12T17:24:29.213Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -4722,7 +4719,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H05613456699
+ number: H94460401316
tracking:
tracking_url:
cost: '10.0'
@@ -4747,8 +4744,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-08T10:57:16.243Z'
- updated_at: '2026-06-08T10:57:16.326Z'
+ created_at: '2026-06-12T17:24:29.915Z'
+ updated_at: '2026-06-12T17:24:29.963Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -4844,8 +4841,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-06-08T10:57:00.931Z'
- updated_at: '2026-06-08T10:57:00.931Z'
+ created_at: '2026-06-12T17:24:14.398Z'
+ updated_at: '2026-06-12T17:24:14.398Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -4926,8 +4923,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-06-08T10:57:01.503Z'
- updated_at: '2026-06-08T10:57:01.503Z'
+ created_at: '2026-06-12T17:24:14.972Z'
+ updated_at: '2026-06-12T17:24:14.972Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: admin_UkLWZg9DAJ
@@ -5028,8 +5025,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-06-08T10:57:01.792Z'
- updated_at: '2026-06-08T10:57:01.792Z'
+ created_at: '2026-06-12T17:24:15.269Z'
+ updated_at: '2026-06-12T17:24:15.269Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -5132,7 +5129,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: BAA028CDF578F746
+ code: CD084BB41D246D4F
status: active
currency: USD
amount: '50.0'
@@ -5146,12 +5143,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-08T10:57:02.369Z'
- updated_at: '2026-06-08T10:57:02.369Z'
+ created_at: '2026-06-12T17:24:15.844Z'
+ updated_at: '2026-06-12T17:24:15.844Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: B7B9C97DAE77E96A
+ code: 1942CCC0C95DF267
status: active
currency: USD
amount: '25.0'
@@ -5165,8 +5162,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-08T10:57:02.370Z'
- updated_at: '2026-06-08T10:57:02.370Z'
+ created_at: '2026-06-12T17:24:15.846Z'
+ updated_at: '2026-06-12T17:24:15.846Z'
customer_id:
created_by_id:
meta:
@@ -5251,7 +5248,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: E983499BEFF8FE2F
+ code: 4F5E5C544DDFA6B5
status: active
currency: USD
amount: '25.0'
@@ -5265,8 +5262,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-08T10:57:02.961Z'
- updated_at: '2026-06-08T10:57:02.961Z'
+ created_at: '2026-06-12T17:24:16.432Z'
+ updated_at: '2026-06-12T17:24:16.432Z'
customer_id:
created_by_id: admin_UkLWZg9DAJ
schema:
@@ -5372,7 +5369,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 415FB670C81E9D04
+ code: CF2E19F27E7DA895
status: active
currency: USD
amount: '50.0'
@@ -5386,8 +5383,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-08T10:57:03.255Z'
- updated_at: '2026-06-08T10:57:03.255Z'
+ created_at: '2026-06-12T17:24:16.734Z'
+ updated_at: '2026-06-12T17:24:16.734Z'
customer_id:
created_by_id:
schema:
@@ -5447,7 +5444,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 8BDA7FE50F533A90
+ code: 38197D3D485C7386
status: active
currency: USD
amount: '75.0'
@@ -5461,8 +5458,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-08T10:57:03.831Z'
- updated_at: '2026-06-08T10:57:04.125Z'
+ created_at: '2026-06-12T17:24:17.340Z'
+ updated_at: '2026-06-12T17:24:17.626Z'
customer_id:
created_by_id:
schema:
@@ -5612,8 +5609,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-08T10:57:05.954Z'
- updated_at: '2026-06-08T10:57:05.954Z'
+ created_at: '2026-06-12T17:24:19.453Z'
+ updated_at: '2026-06-12T17:24:19.453Z'
meta:
page: 1
limit: 25
@@ -5703,8 +5700,8 @@ paths:
supported_locales:
- en
- fr
- created_at: '2026-06-08T10:57:06.548Z'
- updated_at: '2026-06-08T10:57:06.548Z'
+ created_at: '2026-06-12T17:24:20.056Z'
+ updated_at: '2026-06-12T17:24:20.056Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -5837,8 +5834,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-08T10:57:06.885Z'
- updated_at: '2026-06-08T10:57:06.885Z'
+ created_at: '2026-06-12T17:24:20.399Z'
+ updated_at: '2026-06-12T17:24:20.399Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -5914,8 +5911,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-08T10:57:07.498Z'
- updated_at: '2026-06-08T10:57:07.783Z'
+ created_at: '2026-06-12T17:24:21.018Z'
+ updated_at: '2026-06-12T17:24:21.314Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -6089,8 +6086,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-08T10:57:09.036Z'
- updated_at: '2026-06-08T10:57:09.036Z'
+ created_at: '2026-06-12T17:24:22.583Z'
+ updated_at: '2026-06-12T17:24:22.583Z'
meta:
page: 1
limit: 25
@@ -6181,8 +6178,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-08T10:57:09.626Z'
- updated_at: '2026-06-08T10:57:09.626Z'
+ created_at: '2026-06-12T17:24:23.162Z'
+ updated_at: '2026-06-12T17:24:23.162Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -6303,8 +6300,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-08T10:57:09.919Z'
- updated_at: '2026-06-08T10:57:09.919Z'
+ created_at: '2026-06-12T17:24:23.455Z'
+ updated_at: '2026-06-12T17:24:23.455Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -6376,8 +6373,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-08T10:57:10.492Z'
- updated_at: '2026-06-08T10:57:10.771Z'
+ created_at: '2026-06-12T17:24:24.039Z'
+ updated_at: '2026-06-12T17:24:24.323Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -6522,7 +6519,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: D1978DA92B314BFD
+ code: B4A00253F5765132
status: active
currency: USD
amount: '10.0'
@@ -6536,8 +6533,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-08T10:57:16.764Z'
- updated_at: '2026-06-08T10:57:17.068Z'
+ created_at: '2026-06-12T17:24:30.324Z'
+ updated_at: '2026-06-12T17:24:30.627Z'
customer_id:
created_by_id:
requestBody:
@@ -6670,8 +6667,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 121399
- slug: product-121399
+ name: Product 12496
+ slug: product-12496
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -6703,12 +6700,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:57:17.775Z'
- updated_at: '2026-06-08T10:57:17.775Z'
+ created_at: '2026-06-12T17:24:31.334Z'
+ updated_at: '2026-06-12T17:24:31.334Z'
digital_links: []
metadata: {}
- created_at: '2026-06-08T10:57:18.061Z'
- updated_at: '2026-06-08T10:57:18.061Z'
+ created_at: '2026-06-12T17:24:31.626Z'
+ updated_at: '2026-06-12T17:24:31.626Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -6775,8 +6772,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 14285
- slug: product-14285
+ name: Product 148513
+ slug: product-148513
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -6808,12 +6805,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:57:19.059Z'
- updated_at: '2026-06-08T10:57:19.059Z'
+ created_at: '2026-06-12T17:24:32.569Z'
+ updated_at: '2026-06-12T17:24:32.569Z'
digital_links: []
metadata: {}
- created_at: '2026-06-08T10:57:19.089Z'
- updated_at: '2026-06-08T10:57:19.089Z'
+ created_at: '2026-06-12T17:24:32.598Z'
+ updated_at: '2026-06-12T17:24:32.598Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -6902,8 +6899,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 158509
- slug: product-158509
+ name: Product 158464
+ slug: product-158464
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -6935,12 +6932,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:57:19.183Z'
- updated_at: '2026-06-08T10:57:19.183Z'
+ created_at: '2026-06-12T17:24:32.673Z'
+ updated_at: '2026-06-12T17:24:32.673Z'
digital_links: []
metadata: {}
- created_at: '2026-06-08T10:57:19.496Z'
- updated_at: '2026-06-08T10:57:19.496Z'
+ created_at: '2026-06-12T17:24:32.963Z'
+ updated_at: '2026-06-12T17:24:32.963Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -7002,8 +6999,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 164071
- slug: product-164071
+ name: Product 166608
+ slug: product-166608
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -7035,12 +7032,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:57:19.842Z'
- updated_at: '2026-06-08T10:57:19.842Z'
+ created_at: '2026-06-12T17:24:33.338Z'
+ updated_at: '2026-06-12T17:24:33.338Z'
digital_links: []
metadata: {}
- created_at: '2026-06-08T10:57:20.129Z'
- updated_at: '2026-06-08T10:57:20.438Z'
+ created_at: '2026-06-12T17:24:33.640Z'
+ updated_at: '2026-06-12T17:24:33.979Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -7154,8 +7151,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R970913639
+ number: R641610767
customer_note:
currency: USD
locale: en
@@ -7198,8 +7195,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:27.159Z'
- updated_at: '2026-06-08T10:57:27.226Z'
+ created_at: '2026-06-12T17:24:41.067Z'
+ updated_at: '2026-06-12T17:24:41.127Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -7370,8 +7367,8 @@ paths:
- id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R311015146
+ number: R244886130
customer_note:
currency: USD
locale: en
@@ -7414,8 +7411,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:29.022Z'
- updated_at: '2026-06-08T10:57:29.022Z'
+ created_at: '2026-06-12T17:24:43.024Z'
+ updated_at: '2026-06-12T17:24:43.024Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -7558,7 +7555,7 @@ paths:
id: or_gbHJdmfrXB
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R734764741
+ number: R886479771
customer_note:
currency: USD
@@ -7602,8 +7599,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:30.750Z'
- updated_at: '2026-06-08T10:57:30.753Z'
+ created_at: '2026-06-12T17:24:44.884Z'
+ updated_at: '2026-06-12T17:24:44.888Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
tags: []
internal_note:
@@ -7787,8 +7784,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R377667939
+ number: R954821619
customer_note:
currency: USD
locale: en
@@ -7831,8 +7828,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:31.030Z'
- updated_at: '2026-06-08T10:57:31.030Z'
+ created_at: '2026-06-12T17:24:45.173Z'
+ updated_at: '2026-06-12T17:24:45.173Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -7903,7 +7900,7 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R109563285
+ number: R935476385
customer_note:
currency: USD
@@ -7947,8 +7944,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:32.132Z'
- updated_at: '2026-06-08T10:57:32.439Z'
+ created_at: '2026-06-12T17:24:46.324Z'
+ updated_at: '2026-06-12T17:24:46.625Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8129,8 +8126,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R852541066
+ number: R858666014
customer_note:
currency: USD
locale: en
@@ -8157,7 +8154,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-06-08T10:57:33.412Z'
+ completed_at: '2026-06-12T17:24:47.655Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8173,8 +8170,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:33.311Z'
- updated_at: '2026-06-08T10:57:33.471Z'
+ created_at: '2026-06-12T17:24:47.569Z'
+ updated_at: '2026-06-12T17:24:47.707Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8255,8 +8252,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R706412366
+ number: R332298067
customer_note:
currency: USD
locale: en
@@ -8283,7 +8280,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-06-08T10:57:34.738Z'
+ completed_at: '2026-06-12T17:24:49.066Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8297,10 +8294,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-06-08T10:57:35.022Z'
+ canceled_at: '2026-06-12T17:24:49.365Z'
approved_at:
- created_at: '2026-06-08T10:57:34.691Z'
- updated_at: '2026-06-08T10:57:35.060Z'
+ created_at: '2026-06-12T17:24:49.003Z'
+ updated_at: '2026-06-12T17:24:49.416Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8359,8 +8356,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R211398927
+ number: R700530633
customer_note:
currency: USD
locale: en
@@ -8387,7 +8384,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-06-08T10:57:35.417Z'
+ completed_at: '2026-06-12T17:24:49.783Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8402,9 +8399,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-06-08T10:57:35.719Z'
- created_at: '2026-06-08T10:57:35.357Z'
- updated_at: '2026-06-08T10:57:35.417Z'
+ approved_at: '2026-06-12T17:24:50.082Z'
+ created_at: '2026-06-12T17:24:49.725Z'
+ updated_at: '2026-06-12T17:24:49.783Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8463,8 +8460,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R155035324
+ number: R883442430
customer_note:
currency: USD
locale: en
@@ -8491,7 +8488,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-06-08T10:57:36.085Z'
+ completed_at: '2026-06-12T17:24:50.441Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8505,10 +8502,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-06-08T10:57:36.371Z'
+ canceled_at: '2026-06-12T17:24:50.726Z'
approved_at:
- created_at: '2026-06-08T10:57:36.023Z'
- updated_at: '2026-06-08T10:57:36.451Z'
+ created_at: '2026-06-12T17:24:50.376Z'
+ updated_at: '2026-06-12T17:24:50.822Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8567,8 +8564,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R297088709
+ number: R467281645
customer_note:
currency: USD
locale: en
@@ -8595,7 +8592,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-06-08T10:57:36.813Z'
+ completed_at: '2026-06-12T17:24:51.184Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8611,8 +8608,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-08T10:57:36.746Z'
- updated_at: '2026-06-08T10:57:36.812Z'
+ created_at: '2026-06-12T17:24:51.117Z'
+ updated_at: '2026-06-12T17:24:51.184Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8687,8 +8684,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-06-08T10:57:37.124Z'
- updated_at: '2026-06-08T10:57:37.125Z'
+ created_at: '2026-06-12T17:24:51.507Z'
+ updated_at: '2026-06-12T17:24:51.509Z'
preferences: {}
preference_schema: []
meta:
@@ -8747,12 +8744,12 @@ paths:
label: Bogus
description:
preference_schema:
- - key: dummy_key
- type: string
- default: PUBLICKEY123
- key: dummy_secret_key
type: password
default:
+ - key: dummy_key
+ type: string
+ default: PUBLICKEY123
- type: custom_payment_source_method
label: Custom Payment Source Method
description:
@@ -8828,8 +8825,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-06-08T10:57:37.721Z'
- updated_at: '2026-06-08T10:57:37.722Z'
+ created_at: '2026-06-12T17:24:52.124Z'
+ updated_at: '2026-06-12T17:24:52.126Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -8897,8 +8894,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-8a4389715a82
- number: P4WYE9BN
+ response_code: BGS-666a0970d255
+ number: PST3ZPXJ
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -8916,14 +8913,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-08T10:57:21.449Z'
- updated_at: '2026-06-08T10:57:21.453Z'
+ created_at: '2026-06-12T17:24:35.003Z'
+ updated_at: '2026-06-12T17:24:35.006Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-08T10:57:21.451Z'
- updated_at: '2026-06-08T10:57:21.451Z'
+ created_at: '2026-06-12T17:24:35.005Z'
+ updated_at: '2026-06-12T17:24:35.005Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -8990,7 +8987,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: P9YJWKYL
+ number: PRZAZQJ8
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -9001,8 +8998,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-08T10:57:22.839Z'
- updated_at: '2026-06-08T10:57:22.839Z'
+ created_at: '2026-06-12T17:24:36.354Z'
+ updated_at: '2026-06-12T17:24:36.354Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -9092,8 +9089,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-593d862e96f0
- number: PG90UG3I
+ response_code: BGS-67d8bd9175fb
+ number: PFKTQFMQ
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9111,14 +9108,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-08T10:57:23.214Z'
- updated_at: '2026-06-08T10:57:23.217Z'
+ created_at: '2026-06-12T17:24:36.816Z'
+ updated_at: '2026-06-12T17:24:36.820Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-08T10:57:23.216Z'
- updated_at: '2026-06-08T10:57:23.216Z'
+ created_at: '2026-06-12T17:24:36.819Z'
+ updated_at: '2026-06-12T17:24:36.819Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -9177,8 +9174,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-0a1bdc7c0459
- number: PKBIGM2X
+ response_code: BGS-b63164b5fd08
+ number: PV70TAWA
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9196,14 +9193,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-08T10:57:23.864Z'
- updated_at: '2026-06-08T10:57:23.866Z'
+ created_at: '2026-06-12T17:24:37.491Z'
+ updated_at: '2026-06-12T17:24:37.494Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-08T10:57:23.865Z'
- updated_at: '2026-06-08T10:57:24.186Z'
+ created_at: '2026-06-12T17:24:37.493Z'
+ updated_at: '2026-06-12T17:24:37.844Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -9272,8 +9269,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-1fec0a04658a
- number: P122PQX0
+ response_code: void-BGS-2993d99c08c2
+ number: PJKLS93Y
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -9291,14 +9288,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-08T10:57:25.233Z'
- updated_at: '2026-06-08T10:57:25.235Z'
+ created_at: '2026-06-12T17:24:38.988Z'
+ updated_at: '2026-06-12T17:24:38.991Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-08T10:57:25.234Z'
- updated_at: '2026-06-08T10:57:25.532Z'
+ created_at: '2026-06-12T17:24:38.990Z'
+ updated_at: '2026-06-12T17:24:39.301Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -9371,8 +9368,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:38.019Z'
- updated_at: '2026-06-08T10:57:38.019Z'
+ created_at: '2026-06-12T17:24:52.444Z'
+ updated_at: '2026-06-12T17:24:52.444Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9386,8 +9383,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:38.020Z'
- updated_at: '2026-06-08T10:57:38.020Z'
+ created_at: '2026-06-12T17:24:52.447Z'
+ updated_at: '2026-06-12T17:24:52.447Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9451,8 +9448,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:38.996Z'
- updated_at: '2026-06-08T10:57:38.998Z'
+ created_at: '2026-06-12T17:24:53.499Z'
+ updated_at: '2026-06-12T17:24:53.501Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -9600,8 +9597,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:39.301Z'
- updated_at: '2026-06-08T10:57:39.301Z'
+ created_at: '2026-06-12T17:24:53.806Z'
+ updated_at: '2026-06-12T17:24:53.806Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9659,8 +9656,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:40.918Z'
- updated_at: '2026-06-08T10:57:41.207Z'
+ created_at: '2026-06-12T17:24:55.427Z'
+ updated_at: '2026-06-12T17:24:55.712Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9818,8 +9815,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:41.507Z'
- updated_at: '2026-06-08T10:57:41.796Z'
+ created_at: '2026-06-12T17:24:56.035Z'
+ updated_at: '2026-06-12T17:24:56.320Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -9867,8 +9864,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-08T10:57:41.806Z'
- updated_at: '2026-06-08T10:57:42.092Z'
+ created_at: '2026-06-12T17:24:56.329Z'
+ updated_at: '2026-06-12T17:24:56.617Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -9979,8 +9976,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-08T10:57:42.151Z'
- updated_at: '2026-06-08T10:57:42.151Z'
+ created_at: '2026-06-12T17:24:56.681Z'
+ updated_at: '2026-06-12T17:24:56.681Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -9991,8 +9988,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-08T10:57:42.159Z'
- updated_at: '2026-06-08T10:57:42.159Z'
+ created_at: '2026-06-12T17:24:56.685Z'
+ updated_at: '2026-06-12T17:24:56.685Z'
meta:
page: 1
limit: 25
@@ -10071,8 +10068,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-06-08T10:57:42.971Z'
- updated_at: '2026-06-08T10:57:42.971Z'
+ created_at: '2026-06-12T17:24:57.494Z'
+ updated_at: '2026-06-12T17:24:57.494Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -10156,8 +10153,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-08T10:57:43.043Z'
- updated_at: '2026-06-08T10:57:43.043Z'
+ created_at: '2026-06-12T17:24:57.574Z'
+ updated_at: '2026-06-12T17:24:57.574Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -10219,8 +10216,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-08T10:57:43.751Z'
- updated_at: '2026-06-08T10:57:44.076Z'
+ created_at: '2026-06-12T17:24:58.283Z'
+ updated_at: '2026-06-12T17:24:58.593Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -10520,8 +10517,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-06-08T10:57:45.538Z'
- updated_at: '2026-06-08T10:57:45.538Z'
+ created_at: '2026-06-12T17:25:00.143Z'
+ updated_at: '2026-06-12T17:25:00.143Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -10588,8 +10585,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-06-08T10:57:46.140Z'
- updated_at: '2026-06-08T10:57:46.140Z'
+ created_at: '2026-06-12T17:25:00.791Z'
+ updated_at: '2026-06-12T17:25:00.791Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -10673,8 +10670,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-06-08T10:57:46.496Z'
- updated_at: '2026-06-08T10:57:46.496Z'
+ created_at: '2026-06-12T17:25:01.167Z'
+ updated_at: '2026-06-12T17:25:01.167Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -10721,8 +10718,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-06-08T10:57:46.820Z'
- updated_at: '2026-06-08T10:57:47.180Z'
+ created_at: '2026-06-12T17:25:01.494Z'
+ updated_at: '2026-06-12T17:25:01.792Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -10860,8 +10857,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 57785
- slug: product-57785
+ name: Product 572113
+ slug: product-572113
meta_title:
meta_description:
meta_keywords:
@@ -10871,14 +10868,16 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Explicabo inventore laboriosam iure maxime sed placeat.
- Corporis at perferendis animi maiores illum quisquam. Odit saepe
- non vel cupiditate. Sapiente harum inventore expedita cumque adipisci.
- Amet perspiciatis quod aliquam eos.
- description_html: Explicabo inventore laboriosam iure maxime sed
- placeat. Corporis at perferendis animi maiores illum quisquam.
- Odit saepe non vel cupiditate. Sapiente harum inventore expedita
- cumque adipisci. Amet perspiciatis quod aliquam eos.
+ description: Optio eum culpa id nostrum aspernatur tenetur asperiores.
+ Qui quos quod laudantium tempora sequi. Adipisci sequi neque commodi
+ tenetur. Veritatis doloremque fugiat quae accusantium inventore
+ perferendis provident laudantium. Similique officiis quasi saepe
+ reiciendis quam molestias.
+ description_html: Optio eum culpa id nostrum aspernatur tenetur
+ asperiores. Qui quos quod laudantium tempora sequi. Adipisci sequi
+ neque commodi tenetur. Veritatis doloremque fugiat quae accusantium
+ inventore perferendis provident laudantium. Similique officiis
+ quasi saepe reiciendis quam molestias.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -10893,14 +10892,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:47.555Z'
- updated_at: '2026-06-08T10:57:47.555Z'
+ created_at: '2026-06-12T17:25:02.180Z'
+ updated_at: '2026-06-12T17:25:02.180Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-08T10:57:47.542Z'
- updated_at: '2026-06-08T10:57:47.562Z'
+ created_at: '2026-06-12T17:25:02.168Z'
+ updated_at: '2026-06-12T17:25:02.188Z'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
@@ -11032,8 +11031,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-06-08T10:57:48.313Z'
- updated_at: '2026-06-08T10:57:48.314Z'
+ created_at: '2026-06-12T17:25:02.877Z'
+ updated_at: '2026-06-12T17:25:02.878Z'
tax_category_id:
schema:
"$ref": "#/components/schemas/Product"
@@ -11213,8 +11212,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 614200
- slug: product-614200
+ name: Product 61236
+ slug: product-61236
meta_title:
meta_description:
meta_keywords:
@@ -11224,16 +11223,24 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Odio impedit nobis rerum nostrum numquam sit illum quae.
- Necessitatibus autem nisi ipsa reiciendis itaque. In earum maiores
- animi placeat debitis. Modi sapiente quas perspiciatis quae labore.
- Laudantium dolorum debitis earum occaecati. Quam in voluptatem deleniti
- distinctio. Reiciendis maiores libero a perferendis delectus exercitationem
- omnis. Occaecati cupiditate eligendi consequatur debitis. Impedit
- laboriosam odit quisquam dignissimos est blanditiis ratione.
+ description: Minima nisi impedit aut sed aspernatur repellendus ullam
+ quisquam. Quod ab vero occaecati quasi. Quasi in tempore iure aut
+ praesentium reprehenderit repellat. Voluptatem fugit eius natus
+ quisquam rerum animi placeat cumque. Pariatur quaerat porro possimus
+ animi at facere eaque. Molestias accusamus neque officiis ut aspernatur
+ totam saepe. Debitis at voluptatibus libero ducimus totam non asperiores
+ reprehenderit. Veritatis eos iusto quis sapiente magnam. Dignissimos
+ inventore quo et ipsam reprehenderit praesentium vitae minima. Inventore
+ eaque praesentium earum ipsam consequatur. Corporis voluptatem iure
+ ipsam iste perferendis quaerat at sit. Nesciunt laudantium itaque
+ necessitatibus possimus provident enim quos. Aperiam a quis aliquam
+ quas necessitatibus eos ut fuga. Quaerat labore nobis animi molestiae.
+ Consequuntur rem molestias distinctio ipsa.
description_html: |-
- Odio impedit nobis rerum nostrum numquam sit illum quae. Necessitatibus autem nisi ipsa reiciendis itaque. In earum maiores animi placeat debitis. Modi sapiente quas perspiciatis quae labore.
- Laudantium dolorum debitis earum occaecati. Quam in voluptatem deleniti distinctio. Reiciendis maiores libero a perferendis delectus exercitationem omnis. Occaecati cupiditate eligendi consequatur debitis. Impedit laboriosam odit quisquam dignissimos est blanditiis ratione.
+ Minima nisi impedit aut sed aspernatur repellendus ullam quisquam. Quod ab vero occaecati quasi. Quasi in tempore iure aut praesentium reprehenderit repellat. Voluptatem fugit eius natus quisquam rerum animi placeat cumque.
+ Pariatur quaerat porro possimus animi at facere eaque. Molestias accusamus neque officiis ut aspernatur totam saepe. Debitis at voluptatibus libero ducimus totam non asperiores reprehenderit. Veritatis eos iusto quis sapiente magnam.
+ Dignissimos inventore quo et ipsam reprehenderit praesentium vitae minima. Inventore eaque praesentium earum ipsam consequatur. Corporis voluptatem iure ipsam iste perferendis quaerat at sit. Nesciunt laudantium itaque necessitatibus possimus provident enim quos.
+ Aperiam a quis aliquam quas necessitatibus eos ut fuga. Quaerat labore nobis animi molestiae. Consequuntur rem molestias distinctio ipsa.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -11248,14 +11255,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:48.860Z'
- updated_at: '2026-06-08T10:57:48.860Z'
+ created_at: '2026-06-12T17:25:03.263Z'
+ updated_at: '2026-06-12T17:25:03.263Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-08T10:57:48.847Z'
- updated_at: '2026-06-08T10:57:48.868Z'
+ created_at: '2026-06-12T17:25:03.252Z'
+ updated_at: '2026-06-12T17:25:03.269Z'
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
@@ -11322,7 +11329,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-632303
+ slug: product-637715
meta_title:
meta_description:
meta_keywords:
@@ -11332,16 +11339,30 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Magni repellendus magnam quasi nemo molestias quia corrupti.
- Debitis dolorum unde aliquam asperiores eius sit incidunt. Ducimus
- esse ipsam neque error rem. Alias esse beatae eum aperiam. Qui exercitationem
- in repudiandae est laboriosam alias quam officia. Aut corporis temporibus
- dolor dolorem repellat debitis. Assumenda ut cumque labore enim
- deleniti adipisci consectetur. Nesciunt laudantium iste tempore
- reprehenderit distinctio.
+ description: Minima esse id porro impedit aliquid quam sint. Vero
+ exercitationem voluptate consequatur fuga eos dolorum corrupti recusandae.
+ Non similique facere beatae repudiandae exercitationem corrupti
+ facilis suscipit. Impedit distinctio expedita tempora itaque. Omnis
+ quisquam eaque iure alias officia. Consequatur molestiae error nostrum
+ consectetur sint perferendis. Nesciunt fugit dolorem dolorum sed
+ totam nulla occaecati. Qui quas aliquam occaecati harum consequatur
+ ratione temporibus perspiciatis. Eos labore officia commodi quisquam.
+ Odio expedita necessitatibus minus non rem pariatur dignissimos
+ voluptatum. Illum molestiae totam perferendis repudiandae consectetur
+ maxime. Tenetur architecto qui voluptatem culpa sint aspernatur
+ eum voluptates. Suscipit reiciendis eveniet error quae temporibus
+ enim. Atque quia repellat sequi dignissimos nostrum soluta perspiciatis
+ aliquam. Iste quis similique eaque in. Sint voluptatum saepe pariatur
+ aspernatur est nisi odio. Sequi atque porro nihil possimus dolorem
+ eum. Laboriosam consectetur vitae iusto autem tempora doloremque
+ non. Sint rerum esse cumque reprehenderit consequuntur ad non ratione.
+ Earum quo quae reiciendis facere.
description_html: |-
- Magni repellendus magnam quasi nemo molestias quia corrupti. Debitis dolorum unde aliquam asperiores eius sit incidunt. Ducimus esse ipsam neque error rem. Alias esse beatae eum aperiam.
- Qui exercitationem in repudiandae est laboriosam alias quam officia. Aut corporis temporibus dolor dolorem repellat debitis. Assumenda ut cumque labore enim deleniti adipisci consectetur. Nesciunt laudantium iste tempore reprehenderit distinctio.
+ Minima esse id porro impedit aliquid quam sint. Vero exercitationem voluptate consequatur fuga eos dolorum corrupti recusandae. Non similique facere beatae repudiandae exercitationem corrupti facilis suscipit.
+ Impedit distinctio expedita tempora itaque. Omnis quisquam eaque iure alias officia. Consequatur molestiae error nostrum consectetur sint perferendis. Nesciunt fugit dolorem dolorum sed totam nulla occaecati. Qui quas aliquam occaecati harum consequatur ratione temporibus perspiciatis.
+ Eos labore officia commodi quisquam. Odio expedita necessitatibus minus non rem pariatur dignissimos voluptatum. Illum molestiae totam perferendis repudiandae consectetur maxime. Tenetur architecto qui voluptatem culpa sint aspernatur eum voluptates.
+ Suscipit reiciendis eveniet error quae temporibus enim. Atque quia repellat sequi dignissimos nostrum soluta perspiciatis aliquam. Iste quis similique eaque in.
+ Sint voluptatum saepe pariatur aspernatur est nisi odio. Sequi atque porro nihil possimus dolorem eum. Laboriosam consectetur vitae iusto autem tempora doloremque non. Sint rerum esse cumque reprehenderit consequuntur ad non ratione. Earum quo quae reiciendis facere.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -11356,14 +11377,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:49.569Z'
- updated_at: '2026-06-08T10:57:49.569Z'
+ created_at: '2026-06-12T17:25:04.038Z'
+ updated_at: '2026-06-12T17:25:04.038Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-08T10:57:49.558Z'
- updated_at: '2026-06-08T10:57:49.867Z'
+ created_at: '2026-06-12T17:25:04.024Z'
+ updated_at: '2026-06-12T17:25:04.344Z'
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
@@ -12017,15 +12038,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-06-08T10:56:40.010Z'
- updated_at: '2026-06-08T10:56:40.010Z'
+ created_at: '2026-06-12T17:23:52.481Z'
+ updated_at: '2026-06-12T17:23:52.481Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-06-08T10:56:40.011Z'
- updated_at: '2026-06-08T10:56:40.011Z'
+ created_at: '2026-06-12T17:23:52.483Z'
+ updated_at: '2026-06-12T17:23:52.483Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -12084,8 +12105,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:54.179Z'
- updated_at: '2026-06-08T10:57:54.179Z'
+ created_at: '2026-06-12T17:25:08.639Z'
+ updated_at: '2026-06-12T17:25:08.639Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -12146,8 +12167,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:54.745Z'
- updated_at: '2026-06-08T10:57:54.745Z'
+ created_at: '2026-06-12T17:25:09.232Z'
+ updated_at: '2026-06-12T17:25:09.232Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -12257,8 +12278,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:55.356Z'
- updated_at: '2026-06-08T10:57:55.356Z'
+ created_at: '2026-06-12T17:25:09.944Z'
+ updated_at: '2026-06-12T17:25:09.944Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -12325,8 +12346,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:55.935Z'
- updated_at: '2026-06-08T10:57:55.935Z'
+ created_at: '2026-06-12T17:25:10.546Z'
+ updated_at: '2026-06-12T17:25:10.546Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -12399,8 +12420,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-06-08T10:57:56.238Z'
- updated_at: '2026-06-08T10:57:56.638Z'
+ created_at: '2026-06-12T17:25:10.853Z'
+ updated_at: '2026-06-12T17:25:11.135Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -12490,7 +12511,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-08T10:57:57.000Z'
+ starts_at: '2026-06-12T17:25:11.475Z'
expires_at:
usage_limit:
match_policy: all
@@ -12501,8 +12522,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-08T10:57:57.003Z'
- updated_at: '2026-06-08T10:57:57.004Z'
+ created_at: '2026-06-12T17:25:11.477Z'
+ updated_at: '2026-06-12T17:25:11.479Z'
action_ids: []
rule_ids: []
meta:
@@ -12606,7 +12627,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-06-08T10:57:58.125Z'
+ starts_at: '2026-06-12T17:25:12.469Z'
expires_at:
usage_limit:
match_policy: all
@@ -12617,8 +12638,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-08T10:57:58.126Z'
- updated_at: '2026-06-08T10:57:58.145Z'
+ created_at: '2026-06-12T17:25:12.471Z'
+ updated_at: '2026-06-12T17:25:12.495Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -12769,7 +12790,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-08T10:57:58.456Z'
+ starts_at: '2026-06-12T17:25:12.804Z'
expires_at:
usage_limit:
match_policy: all
@@ -12780,8 +12801,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-08T10:57:58.457Z'
- updated_at: '2026-06-08T10:57:58.460Z'
+ created_at: '2026-06-12T17:25:12.805Z'
+ updated_at: '2026-06-12T17:25:12.806Z'
action_ids: []
rule_ids: []
patch:
@@ -12875,7 +12896,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-08T10:57:59.375Z'
+ starts_at: '2026-06-12T17:25:13.717Z'
expires_at:
usage_limit:
match_policy: all
@@ -12886,8 +12907,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-08T10:57:59.376Z'
- updated_at: '2026-06-08T10:57:59.658Z'
+ created_at: '2026-06-12T17:25:13.718Z'
+ updated_at: '2026-06-12T17:25:14.003Z'
action_ids: []
rule_ids: []
requestBody:
@@ -13180,12 +13201,12 @@ paths:
label: Option Value(s)
description:
preference_schema:
- - key: match_policy
- type: string
- default: any
- key: eligible_values
type: array
default: []
+ - key: match_policy
+ type: string
+ default: any
- type: product
label: Product(s)
description:
@@ -13318,14 +13339,14 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-cfd82a13871d
+ transaction_id: BGS-68aa088bc90d
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
metadata: {}
- created_at: '2026-06-08T10:57:26.844Z'
- updated_at: '2026-06-08T10:57:26.844Z'
+ created_at: '2026-06-12T17:24:40.748Z'
+ updated_at: '2026-06-12T17:24:40.748Z'
requestBody:
content:
application/json:
@@ -13424,8 +13445,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-06-08T10:58:03.244Z'
- updated_at: '2026-06-08T10:58:03.244Z'
+ created_at: '2026-06-12T17:25:17.833Z'
+ updated_at: '2026-06-12T17:25:17.833Z'
non_expiring: false
meta:
page: 1
@@ -13516,8 +13537,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-06-08T10:58:03.544Z'
- updated_at: '2026-06-08T10:58:03.544Z'
+ created_at: '2026-06-12T17:25:18.145Z'
+ updated_at: '2026-06-12T17:25:18.145Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -13586,8 +13607,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-06-08T10:56:29.978Z'
- updated_at: '2026-06-08T10:58:04.145Z'
+ created_at: '2026-06-12T17:23:41.091Z'
+ updated_at: '2026-06-12T17:25:18.763Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -13663,8 +13684,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-06-08T10:56:29.978Z'
- updated_at: '2026-06-08T10:58:04.762Z'
+ created_at: '2026-06-12T17:23:41.091Z'
+ updated_at: '2026-06-12T17:25:19.408Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -13817,12 +13838,12 @@ paths:
example:
data:
- id: admin_UkLWZg9DAJ
- first_name: Harrison
- last_name: Parisian
- full_name: Harrison Parisian
- created_at: '2026-06-08T10:56:30.306Z'
- updated_at: '2026-06-08T10:56:30.306Z'
+ first_name: Jetta
+ last_name: Rodriguez
+ full_name: Jetta Rodriguez
+ created_at: '2026-06-12T17:23:41.426Z'
+ updated_at: '2026-06-12T17:23:41.426Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -13880,12 +13901,12 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
- first_name: Burt
- last_name: Cole
- full_name: Burt Cole
- created_at: '2026-06-08T10:56:30.644Z'
- updated_at: '2026-06-08T10:56:30.644Z'
+ first_name: Rosemary
+ last_name: Lang
+ full_name: Rosemary Lang
+ created_at: '2026-06-12T17:23:41.772Z'
+ updated_at: '2026-06-12T17:23:41.772Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -13938,12 +13959,12 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
first_name: Renamed
- last_name: Rodriguez
- full_name: Renamed Rodriguez
- created_at: '2026-06-08T10:56:30.927Z'
- updated_at: '2026-06-08T10:56:30.946Z'
+ last_name: Jacobson
+ full_name: Renamed Jacobson
+ created_at: '2026-06-12T17:23:42.066Z'
+ updated_at: '2026-06-12T17:23:42.082Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -14048,15 +14069,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-06-08T10:57:05.016Z'
- updated_at: '2026-06-08T10:57:05.016Z'
- expires_at: '2026-06-22T10:57:05.014Z'
+ created_at: '2026-06-12T17:24:18.489Z'
+ updated_at: '2026-06-12T17:24:18.489Z'
+ expires_at: '2026-06-26T17:24:18.486Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=YJnLJxUSrtebeM9iYcT2mb9P"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=kvK81PwqFhrhTCgxQsWkHEC5"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -14117,13 +14138,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-06-08T10:57:05.335Z'
- updated_at: '2026-06-08T10:57:05.335Z'
- expires_at: '2026-06-22T10:57:05.333Z'
+ created_at: '2026-06-12T17:24:18.802Z'
+ updated_at: '2026-06-12T17:24:18.802Z'
+ expires_at: '2026-06-26T17:24:18.799Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=ttUpsLEE1U6sfGhhu1bU7G62"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=jkitRfxSPJyDt1bngSSRBWic"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -14230,15 +14251,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-06-08T10:57:05.902Z'
- updated_at: '2026-06-08T10:57:05.902Z'
- expires_at: '2026-06-22T10:57:05.900Z'
+ created_at: '2026-06-12T17:24:19.385Z'
+ updated_at: '2026-06-12T17:24:19.385Z'
+ expires_at: '2026-06-26T17:24:19.383Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=GZQipgFcLGqh5JQj54ouvodx"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=XnbTqpmFxFnkvNBc81ve5JRL"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -14287,8 +14308,8 @@ paths:
data:
- id: role_UkLWZg9DAJ
name: admin
- created_at: '2026-06-08T10:58:00.563Z'
- updated_at: '2026-06-08T10:58:00.563Z'
+ created_at: '2026-06-12T17:25:14.947Z'
+ updated_at: '2026-06-12T17:25:14.947Z'
meta:
page: 1
limit: 25
@@ -14320,7 +14341,7 @@ paths:
`pickup_enabled: true`.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14423,8 +14444,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-06-08T10:58:00.850Z'
- updated_at: '2026-06-08T10:58:00.850Z'
+ created_at: '2026-06-12T17:25:15.247Z'
+ updated_at: '2026-06-12T17:25:15.247Z'
meta:
page: 1
limit: 25
@@ -14471,7 +14492,7 @@ paths:
location.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14535,8 +14556,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 30
pickup_instructions:
- created_at: '2026-06-08T10:58:01.432Z'
- updated_at: '2026-06-08T10:58:01.432Z'
+ created_at: '2026-06-12T17:25:15.845Z'
+ updated_at: '2026-06-12T17:25:15.845Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -14650,7 +14671,7 @@ paths:
description: |-
Returns a single stock location by prefixed ID.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14710,8 +14731,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-06-08T10:58:01.761Z'
- updated_at: '2026-06-08T10:58:01.761Z'
+ created_at: '2026-06-12T17:25:16.140Z'
+ updated_at: '2026-06-12T17:25:16.140Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -14738,7 +14759,7 @@ paths:
Setting `default: true` automatically demotes the previous default.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14796,8 +14817,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 45
pickup_instructions:
- created_at: '2026-06-08T10:58:02.382Z'
- updated_at: '2026-06-08T10:58:02.663Z'
+ created_at: '2026-06-12T17:25:16.866Z'
+ updated_at: '2026-06-12T17:25:17.191Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -14892,7 +14913,7 @@ paths:
`Spree::StockLocation.with_deleted`.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15031,13 +15052,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-08T10:58:06.223Z'
- updated_at: '2026-06-08T10:58:06.232Z'
+ created_at: '2026-06-12T17:25:20.879Z'
+ updated_at: '2026-06-12T17:25:20.888Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 791409
+ product_name: Product 79237
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
sku: SKU-98
@@ -15048,10 +15069,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 92.25
- height: 22.97
- width: 108.5
- depth: 180.4
+ weight: 175.85
+ height: 52.53
+ width: 61.32
+ depth: 150.97
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -15074,8 +15095,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:58:06.245Z'
- updated_at: '2026-06-08T10:58:06.245Z'
+ created_at: '2026-06-12T17:25:20.901Z'
+ updated_at: '2026-06-12T17:25:20.901Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -15084,13 +15105,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-08T10:58:06.242Z'
- updated_at: '2026-06-08T10:58:06.252Z'
+ created_at: '2026-06-12T17:25:20.899Z'
+ updated_at: '2026-06-12T17:25:20.911Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 791409
+ product_name: Product 79237
meta:
page: 1
limit: 25
@@ -15201,8 +15222,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:58:06.920Z'
- updated_at: '2026-06-08T10:58:06.920Z'
+ created_at: '2026-06-12T17:25:21.569Z'
+ updated_at: '2026-06-12T17:25:21.569Z'
metadata: {}
position: 3
cost_price:
@@ -15211,13 +15232,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-08T10:58:06.924Z'
- updated_at: '2026-06-08T10:58:06.925Z'
+ created_at: '2026-06-12T17:25:21.573Z'
+ updated_at: '2026-06-12T17:25:21.575Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 802281
+ product_name: Product 804516
'422':
description: validation error
content:
@@ -15404,10 +15425,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 188.6
- height: 96.46
- width: 19.96
- depth: 26.58
+ weight: 1.16
+ height: 177.59
+ width: 10.65
+ depth: 151.88
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -15430,8 +15451,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:58:07.349Z'
- updated_at: '2026-06-08T10:58:07.349Z'
+ created_at: '2026-06-12T17:25:21.996Z'
+ updated_at: '2026-06-12T17:25:21.996Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -15440,13 +15461,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-08T10:58:07.347Z'
- updated_at: '2026-06-08T10:58:07.368Z'
+ created_at: '2026-06-12T17:25:21.994Z'
+ updated_at: '2026-06-12T17:25:22.006Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 826595
+ product_name: Product 828789
'404':
description: variant not found
content:
@@ -15525,10 +15546,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 10.18
- height: 91.91
- width: 190.0
- depth: 145.3
+ weight: 30.56
+ height: 40.97
+ width: 164.18
+ depth: 171.93
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -15551,8 +15572,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-08T10:58:08.060Z'
- updated_at: '2026-06-08T10:58:08.060Z'
+ created_at: '2026-06-12T17:25:22.723Z'
+ updated_at: '2026-06-12T17:25:22.723Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -15561,13 +15582,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-08T10:58:08.058Z'
- updated_at: '2026-06-08T10:58:08.365Z'
+ created_at: '2026-06-12T17:25:22.720Z'
+ updated_at: '2026-06-12T17:25:23.019Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 843476
+ product_name: Product 845657
requestBody:
content:
application/json:
@@ -15724,7 +15745,7 @@ paths:
redeliver.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15805,9 +15826,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-08T10:58:08.780Z'
- updated_at: '2026-06-08T10:58:08.780Z'
- delivered_at: '2026-06-08T10:58:08.780Z'
+ created_at: '2026-06-12T17:25:23.426Z'
+ updated_at: '2026-06-12T17:25:23.426Z'
+ delivered_at: '2026-06-12T17:25:23.425Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
- id: whd_UkLWZg9DAJ
@@ -15823,9 +15844,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-08T10:58:08.779Z'
- updated_at: '2026-06-08T10:58:08.779Z'
- delivered_at: '2026-06-08T10:58:08.779Z'
+ created_at: '2026-06-12T17:25:23.425Z'
+ updated_at: '2026-06-12T17:25:23.425Z'
+ delivered_at: '2026-06-12T17:25:23.425Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
meta:
@@ -15875,7 +15896,7 @@ paths:
of failed deliveries.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15925,9 +15946,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-08T10:58:09.417Z'
- updated_at: '2026-06-08T10:58:09.417Z'
- delivered_at: '2026-06-08T10:58:09.417Z'
+ created_at: '2026-06-12T17:25:24.048Z'
+ updated_at: '2026-06-12T17:25:24.048Z'
+ delivered_at: '2026-06-12T17:25:24.047Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
'404':
@@ -15966,7 +15987,7 @@ paths:
queues it. The original row is preserved for audit history.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16012,8 +16033,8 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-08T10:58:10.346Z'
- updated_at: '2026-06-08T10:58:10.346Z'
+ created_at: '2026-06-12T17:25:24.972Z'
+ updated_at: '2026-06-12T17:25:24.972Z'
delivered_at:
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
@@ -16032,7 +16053,7 @@ paths:
exactly once on create.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16109,8 +16130,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-08T10:58:10.400Z'
- updated_at: '2026-06-08T10:58:10.400Z'
+ created_at: '2026-06-12T17:25:24.999Z'
+ updated_at: '2026-06-12T17:25:24.999Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -16154,7 +16175,7 @@ paths:
omit it to receive every event.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16202,10 +16223,10 @@ paths:
subscriptions:
- order.completed
disabled_reason:
- created_at: '2026-06-08T10:58:11.114Z'
- updated_at: '2026-06-08T10:58:11.114Z'
+ created_at: '2026-06-12T17:25:25.648Z'
+ updated_at: '2026-06-12T17:25:25.648Z'
disabled_at:
- secret_key: 5ad2424be15f9d7e024dd5e7fcd8d36ed1845791aa2dcaa51b58498eca77c37c
+ secret_key: 8a8467ba33df1423b334f3f9bf5ebc62677e04ce10ba482b4b6f91ffea2a28e8
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -16279,7 +16300,7 @@ paths:
description: |-
Returns a single webhook endpoint by prefixed ID.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16325,8 +16346,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-08T10:58:11.626Z'
- updated_at: '2026-06-08T10:58:11.626Z'
+ created_at: '2026-06-12T17:25:26.005Z'
+ updated_at: '2026-06-12T17:25:26.005Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -16358,7 +16379,7 @@ paths:
without an audit reason.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16401,8 +16422,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-08T10:58:12.303Z'
- updated_at: '2026-06-08T10:58:12.587Z'
+ created_at: '2026-06-12T17:25:26.680Z'
+ updated_at: '2026-06-12T17:25:26.975Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -16462,7 +16483,7 @@ paths:
description: |-
Soft-deletes the endpoint and stops future deliveries.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16511,7 +16532,7 @@ paths:
accepts Spree's payloads.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16554,15 +16575,15 @@ paths:
response_body:
success:
payload:
- id: a948973d-8e57-4e1e-86bc-c8cdeb435e70
+ id: 8a7131d4-3cd4-45cd-aa0e-673f1905126c
name: webhook.test
- created_at: '2026-06-08T10:58:13Z'
+ created_at: '2026-06-12T17:25:27Z'
data:
message: This is a test webhook from Spree.
metadata:
- spree_version: 5.5.0.beta
- created_at: '2026-06-08T10:58:13.620Z'
- updated_at: '2026-06-08T10:58:13.620Z'
+ spree_version: 5.5.0.rc1
+ created_at: '2026-06-12T17:25:27.972Z'
+ updated_at: '2026-06-12T17:25:27.972Z'
delivered_at:
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks/orders
@@ -16584,7 +16605,7 @@ paths:
description: |-
Re-enables an endpoint that was manually or automatically disabled.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16625,8 +16646,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-08T10:58:13.678Z'
- updated_at: '2026-06-08T10:58:13.960Z'
+ created_at: '2026-06-12T17:25:28.003Z'
+ updated_at: '2026-06-12T17:25:28.309Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -16655,7 +16676,7 @@ paths:
repeated delivery failures), no notification email is sent.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_webhooks` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16699,9 +16720,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-06-08T10:58:14.003Z'
- updated_at: '2026-06-08T10:58:14.290Z'
- disabled_at: '2026-06-08T10:58:14.290Z'
+ created_at: '2026-06-12T17:25:28.340Z'
+ updated_at: '2026-06-12T17:25:28.632Z'
+ disabled_at: '2026-06-12T17:25:28.632Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
diff --git a/docs/plans/5.5-admin-api-cli.md b/docs/plans/5.5-admin-api-cli.md
new file mode 100644
index 0000000000..ed5f842ea5
--- /dev/null
+++ b/docs/plans/5.5-admin-api-cli.md
@@ -0,0 +1,155 @@
+# `spree api` — Admin API command group in `@spree/cli`
+
+**Status:** Draft
+**Target:** Spree 5.5.x (CLI minor + one core patch)
+**Depends on:** `5.5-admin-api-key-scopes.md` (shipped), `6.0-admin-api.md` (conventions), `5.5-agent-skills.md` (distribution of the companion skill)
+**Author:** Damian Legawiec (`[email protected]`)
+**Last updated:** 2026-06-12
+
+## Summary
+
+Add a `gh api`-style command group to `@spree/cli`: generic HTTP verbs against the Admin API v3 (`spree api get|post|patch|delete <path>`), schema introspection from the bundled OpenAPI spec (`spree api endpoints`, `spree api schema`), and layered credential resolution (`flags > env > project auto-mint > profiles`). This turns the CLI into the first executable agent surface for Spree's back office — usable by Claude Code, Cursor, CI scripts, and humans alike — **before** any MCP server exists.
+
+This is a deliberate sequencing decision ("CLI-first"): developer agents already have shell access and need zero client configuration; the consumer MCP clients that would justify a hosted Admin MCP (claude.ai, ChatGPT) reject static API keys and are blocked on the OAuth 2.1 work in `6.0-platform-auth` regardless; and a CLI is immune to MCP protocol churn (a breaking, stateless MCP spec revision lands 2026-07-28). Shopify made the same call — there is no official Shopify Admin MCP; agent store management goes through their AI Toolkit CLI. Everything built here (credential bootstrap, generic verbs, schema tools, the `SPREE_BASE_URL`/`SPREE_API_KEY` env contract) becomes the substrate a later `spree mcp` wrapper exposes as MCP tools, so nothing is throwaway.
+
+## Key Decisions (do not deviate without discussion)
+
+- **CLI-first; MCP servers come later and get their own plans.** This plan deliberately contains zero MCP code. The future lanes are: a shopper-facing Storefront MCP (`/api/mcp`, separate plan, highest strategic priority since it has no CLI substitute), a hosted Admin MCP riding `6.0-platform-auth` OAuth, and an optional `spree mcp` stdio wrapper over this command group. None of them start before `spree api` ships.
+- **Generic verbs, not per-resource subcommands.** `spree api get /products` — never `spree products list`. A per-resource command family (~38 resources) would duplicate `@spree/admin-sdk`, sprawl the CLI, and add nothing for agents, which compose generic verbs with the schema tools. Precedents: `gh api`, and the Wix/Datadog/Harness redesigns away from API-parity toward few generic verbs.
+- **Layered credential resolution, in this order:**
+ 1. flags (`--base-url`, `--api-key` — the key flag is supported but discouraged: it leaks into shell history and process lists)
+ 2. env vars `SPREE_BASE_URL` + `SPREE_API_KEY` (the agent/CI/sandbox path)
+ 3. project context: inside a spree-starter directory (`detectProject()`), resolve the base URL from `.env` and auto-mint a key through Docker on first use — zero configuration
+ 4. named profiles in `~/.config/spree/config.json`, selected via `--profile` or a default
+- **`sk_` secret keys are the only credential.** They are store-bound (tenant resolution is free), scoped, HMAC-digest stored, and revocable from the admin dashboard — revocation is the kill switch. No JWT support: ~1h expiry with refresh rotation is the admin SPA's model, not a CLI's. A browser/device-code login becomes a fifth resolution source once `6.0-platform-auth` ships an OAuth stack; the resolution chain is designed so it slots in without breaking anything.
+- **Auto-minted keys get `read_all` only.** Write scopes always require an explicit `spree api-key create --scopes write_products,...`. An agent pointed at a long-lived dev database must not be able to mutate by accident.
+- **`spree api` and `spree auth` work without a Docker project.** Today every CLI command hard-requires `docker-compose.yml` via `detectProject()` (`packages/cli/src/context.ts`). The new commands consult project context only as resolution layer 3 and otherwise run standalone against any Spree 5.5+ host — local or remote.
+- **The CLI gains a dependency on `@spree/admin-sdk`** (it currently depends on neither SDK). Retry with backoff, `Retry-After` honoring, automatic `Idempotency-Key` on writes, `SpreeError` with code/status/details, and `X-Spree-Store-Id` handling all come free. No hand-rolled fetch layer.
+- **JSON to stdout by default; humans opt into tables.** Agents and `jq` are the primary consumers. `--format table` renders collections for humans. Errors go to stderr with non-zero exit codes; a 403 scope denial prints the `required_scope` from the error payload plus the exact `spree api-key create --scopes ...` remediation.
+- **Schema tools read a bundled, versioned `admin.yaml` snapshot.** `docs/api-reference/admin.yaml` is rswag-generated (never hand-edited) and already drives `@spree/admin-sdk` codegen — the CLI bundles a snapshot per release and parses it at startup. No live spec fetch in v1; version skew is surfaced as a warning when the server's Spree version (from `spree api status`) doesn't match the bundled snapshot's.
+- **Two core fixes ship first as a 5.5.x patch** (the CLI is unusable against unpatched servers otherwise):
+ 1. `spree:cli:create_api_key` cannot mint secret keys at all today — `Spree::ApiKey` presence-validates `scopes` on secret keys (`spree/core/app/models/spree/api_key.rb`) and the task passes none, so `KEY_TYPE=secret` raises `RecordInvalid`. Add a `SCOPES` env var (comma-separated, validated against `Spree::ApiKey::SCOPES`).
+ 2. `Spree::ApiKey::SCOPES` has no `read_promotions`/`write_promotions` even though the promotions controllers declare `scoped_resource :promotions` — promotion endpoints are reachable only by `*_all` keys. Add both scopes.
+- **Pair with an agent skill, distributed per `5.5-agent-skills.md`.** A `spree-cli` skill in `spree/agent-skills` teaches agents the credential flow, the verb + schema-tool loop, and the read-before-write conventions. Skills are the guidance channel; the CLI is the execution channel — don't duplicate conventions into CLI help text beyond `--help` basics.
+
+## Design Details
+
+### Command surface
+
+```bash
+# Reads — Ransack filters as repeatable -q, JSON:API-style sort
+spree api get /products -q status_eq=active -q name_cont=shirt --sort -created_at --limit 10
+spree api get /orders/ord_x8k2J9aQ --expand items,payments,fulfillments
+
+# Writes — JSON body inline, from file, or from stdin
+spree api post /products -d '{"name":"Classic Tee","price":29.99}'
+spree api post /orders/ord_x8k2J9aQ/refunds -d @refund.json
+cat batch.json | spree api post /prices/bulk_upsert -d -
+
+# State-machine and custom actions are just paths
+spree api patch /orders/ord_x8k2J9aQ/cancel
+spree api delete /products/prod_86Rf07xd
+
+# Schema introspection (bundled admin.yaml)
+spree api endpoints --resource orders # method, path, summary, required scope
+spree api schema "POST /orders/{id}/refunds" # request/response JSON Schema, Ransack fields
+spree api status # server reachability, Spree version, credential + scopes
+
+# Credentials
+spree auth login --profile prod --base-url https://store.example.com # prompts for sk_ on stdin
+spree auth status # profile, base URL, key prefix (sk_a1b2c3d4e5f6…), scopes
+spree auth logout --profile prod
+spree api-key create --scopes read_all # extended with --scopes (maps to rake SCOPES env)
+```
+
+Flag conventions:
+
+| Flag | Meaning |
+|---|---|
+| `-q key=value` (repeatable) | Ransack predicate; wrapped into `q[...]` via the SDK's `transformListParams` |
+| `--sort`, `--page`, `--limit`, `--expand`, `--fields` | passed through to the Admin API conventions from `6.0-admin-api.md` |
+| `-d <json>` / `-d @file` / `-d -` | request body (inline, file, stdin) |
+| `--store-id` | `X-Spree-Store-Id` header, only needed when one host serves multiple stores |
+| `--profile`, `--base-url`, `--api-key` | credential resolution overrides |
+| `--format json\|table` | output rendering (default `json`) |
+
+### Credential resolution and storage
+
+Resolution order (first hit wins): flags → `SPREE_BASE_URL`/`SPREE_API_KEY` env → project credentials → profile.
+
+- **Project credentials** live in `.spree/credentials.json` in the project directory, `0600`, gitignored (`create-spree-app` and spree-starter add `.spree/` to the scaffolded `.gitignore`). Written by the auto-mint flow: `detectProject()` resolves the port → run `spree:cli:create_api_key NAME="@spree/cli (auto)" KEY_TYPE=secret SCOPES=read_all` through Docker (same path as the existing `api-key create` command) → persist `{ baseUrl, token, tokenPrefix, scopes, mintedAt }`. First `spree api get /products` in a fresh project requires zero setup.
+- **Profiles** live in `~/.config/spree/config.json` (`0600`): `{ profiles: { prod: { baseUrl, token, tokenPrefix } }, defaultProfile }`. `spree auth login` reads the key from an interactive prompt or stdin — never from a flag — and validates it with a test call before saving. The persisted `tokenPrefix` (the 12-char `token_prefix` the model already stores) is what `auth status` displays; the plaintext is never echoed after creation.
+- OS-keychain storage is an open question (below); v1 is file-based with `0600`, matching `gh`'s fallback behavior.
+
+### Core rake task changes (5.5.x patch)
+
+```ruby
+desc 'Create an API key'
+task create_api_key: :environment do
+ name = ENV.fetch('NAME')
+ key_type = ENV.fetch('KEY_TYPE')
+ scopes = ENV.fetch('SCOPES', '').split(',').map(&:strip).reject(&:blank?)
+ store = Spree::Store.default
+ key = store.api_keys.create!(name: name, key_type: key_type, scopes: scopes)
+ print key.plaintext_token
+end
+```
+
+Unknown scopes are already rejected by the model's `validate_known_scopes`; the task stays dumb. `read_promotions`/`write_promotions` are added to `Spree::ApiKey::SCOPES` in the same patch (additive, safe — existing keys are unaffected).
+
+### Output and errors
+
+- Collections pass through the API's `{data, meta}` envelope untouched; single resources print the bare object. Everything is `jq`-composable.
+- Exit codes: `0` success, `1` API error (4xx/5xx — the Stripe-style `{error: {code, message, details}}` payload is printed to stderr), `2` usage/configuration error (no credential resolvable, bad flags, unreachable host).
+- A 403 with `code: access_denied` prints `details.required_scope` and the remediation command. This is load-bearing for agents: the error text is what the model reads to self-correct.
+
+### Relationship to future MCP work
+
+| Lane | Surface | Status after this plan |
+|---|---|---|
+| Dev/admin agents (Claude Code, Cursor, CI) | `spree api` + `spree-cli` skill | **Shipped here** |
+| Shopper agents (claude.ai, ChatGPT consumers) | Storefront MCP at `/api/mcp` | Separate plan, next minor — no CLI substitute exists |
+| Merchant copilot on consumer clients | Hosted Admin MCP + OAuth 2.1 | 6.0, rides `6.0-platform-auth`; tool catalog informed by observed CLI usage |
+| MCP clients that can't shell out | `spree mcp` stdio wrapper exposing this command group as tools | Optional, later — the `SPREE_BASE_URL`/`SPREE_API_KEY` env contract defined here is already the stdio-MCP credential convention |
+
+### agent-skills pairing
+
+One new `spree-cli` skill in `github.com/spree/agent-skills` (per that plan's constraints: targets users, not monorepo contributors). It covers: when to reach for `spree api` vs the TypeScript SDKs, the credential layers, the `endpoints → schema → get/post` loop, read-before-write habits, and the scope-denial remediation flow. The existing `spree-api-v3` skill gets a cross-reference.
+
+## Migration Path
+
+All steps are additive; no breaking changes anywhere.
+
+1. **Core 5.5.x patch** (`spree/core`): `SCOPES` env on `spree:cli:create_api_key` (fixes secret-key minting), `read_promotions`/`write_promotions` in `Spree::ApiKey::SCOPES`. Specs for both.
+2. **`@spree/cli` minor**: add `@spree/admin-sdk` dependency; new `src/config.ts` (resolution chain + credential files); `src/commands/auth.ts` and `src/commands/api.ts` following the existing `registerXCommand` pattern; `--scopes` flag on `api-key create`; a build step copying `docs/api-reference/admin.yaml` into the package as the versioned snapshot; Changesets entry.
+3. **Scaffolding**: `create-spree-app` (and the spree-starter template repo) add `.spree/` to `.gitignore`.
+4. **agent-skills**: `spree-cli` skill PR to `spree/agent-skills`.
+5. **Docs**: a page under `docs/developer/` covering the command group, credential layers, and agent usage (Claude Code snippet with the two env vars).
+
+## Constraints on Current Work
+
+- **Do not add per-resource data subcommands to `@spree/cli`** (`spree products list`, `spree orders show`, …). The generic-verb decision is policy; convenience wrappers route through `spree api` or don't exist.
+- **Do not start MCP server implementation** (storefront, admin, or stdio wrapper) before this ships and has its own plan doc. Future MCP servers wrap `@spree/admin-sdk` / these CLI internals — never fork a parallel tool surface.
+- **Keep regenerating `admin.yaml` via rswag after any Admin API change** (`bundle exec rake rswag:specs:swaggerize`). It was already the rule; the CLI's schema tools now make it load-bearing — a stale spec means `spree api schema` lies to agents.
+- **New admin controllers must declare an accurate `scoped_resource`** and, if they introduce a new resource family, add the matching `read_*`/`write_*` pair to `Spree::ApiKey::SCOPES` in the same PR. The CLI surfaces required scopes from the spec; gaps become user-visible immediately.
+
+## Open Questions
+
+- **OS keychain storage** for profile keys (vs `0600` files only)? Cross-platform keychain libs for Node add native-dependency weight to a so-far pure-JS CLI; `gh` ships file-fallback and most users live there. Lean: file-only in v1, revisit on demand.
+- **Built-in `--jq` filter** (like `gh api --jq`)? Convenient, but adds a jq-engine dependency; agents and humans can pipe to real `jq`. Lean: skip in v1.
+- **`--paginate` auto-pagination** for collections? Useful for exports, dangerous for context-limited agents. Lean: skip in v1; `meta.next` is in the envelope.
+- **Should `spree api` also cover the Store API** (`--surface store`, bundling `store.yaml`) for storefront/checkout testing? Plausible later; out of scope now.
+- ~~**Re-scoping existing controllers**~~ — resolved during 5.5 RC (2026-06-12): inventory controllers (`stock_items`, `stock_locations`, `stock_transfers`) moved to `stock`, webhook controllers to `webhooks`, and `api_keys` got a dedicated `read/write_api_keys` pair. See the vocabulary table in `5.5-admin-api-key-scopes.md`.
+- **Version-skew handling beyond a warning**: should `spree api status` compare bundled-spec version vs server version and offer `--spec <path>` overrides for edge/pre-release servers?
+
+## References
+
+- [`5.5-admin-api-key-scopes.md`](./5.5-admin-api-key-scopes.md) — the scope vocabulary this CLI's permission UX is built on
+- [`6.0-admin-api.md`](./6.0-admin-api.md) — endpoint inventory + conventions (`?q`, `?sort`, `?expand`, flat JSON, prefixed IDs)
+- [`5.5-agent-skills.md`](./5.5-agent-skills.md) — distribution channel for the companion `spree-cli` skill
+- [`6.0-platform-auth.md`](./6.0-platform-auth.md) — the OAuth 2.1 stack that later unlocks consumer-client MCP and a browser-login credential source
+- `gh api` manual: https://cli.github.com/manual/gh_api — the generic-verb precedent
+- Stripe CLI auth model (profiles + config file): https://docs.stripe.com/stripe-cli
+- Shopify AI Toolkit (CLI-based store management for agents; no official Admin MCP): https://github.com/Shopify/shopify-ai-toolkit
+- MCP spec 2026-07-28 release candidate (stateless rework — the churn this plan sidesteps): https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/
+- Context-economics findings informing the CLI-first call: GitHub's 93-tool MCP server ≈ 55k tokens; Cursor's 40-tool cap; Datadog/Harness generic-verb redesigns
diff --git a/docs/plans/5.5-admin-api-key-scopes.md b/docs/plans/5.5-admin-api-key-scopes.md
index a86461e0ca..9329169b8f 100644
--- a/docs/plans/5.5-admin-api-key-scopes.md
+++ b/docs/plans/5.5-admin-api-key-scopes.md
@@ -46,16 +46,18 @@ class Spree::ApiKey < Spree.base_class
KNOWN_SCOPES = %w[
read_orders write_orders
read_products write_products
+ read_promotions write_promotions
read_customers write_customers
read_payments write_payments
read_fulfillments write_fulfillments
read_refunds write_refunds
read_gift_cards write_gift_cards
read_store_credits write_store_credits
+ read_stock write_stock
read_categories write_categories
- read_exports write_exports
read_settings write_settings
read_webhooks write_webhooks
+ read_api_keys write_api_keys
read_dashboard
read_all write_all
].freeze
@@ -89,10 +91,13 @@ end
| `read_refunds` / `write_refunds` | `/orders/:id/refunds` |
| `read_gift_cards` / `write_gift_cards` | `/orders/:id/gift_cards`, future `/gift_cards/*` |
| `read_store_credits` / `write_store_credits` | `/customers/:id/store_credits`, `/orders/:id/store_credits` |
+| `read_promotions` / `write_promotions` | `/promotions/*` (rules, actions, coupon codes nested) |
+| `read_stock` / `write_stock` | `/stock_locations/*`, `/stock_items/*`, `/stock_transfers/*`, `/stock_reservations/*` — the full inventory surface |
| `read_categories` / `write_categories` | `/categories/*` |
-| `read_exports` / `write_exports` | `/exports/*`, `/exports/:id/download` |
-| `read_settings` / `write_settings` | `/payment_methods`, `/markets`, `/countries`, `/tax_categories`, `/stores` |
-| `read_webhooks` / `write_webhooks` | future `/webhooks/*` |
+| *(exports — no dedicated scope)* | `/exports/*` is gated by the read scope of the exported resource (`Spree::Export.required_scope`, derived from the class name with per-subclass overrides). An export is a bulk read; a standalone exports scope would let a key exfiltrate data it couldn't read directly. Index is filtered to readable types |
+| `read_settings` / `write_settings` | `/payment_methods`, `/markets`, `/countries`, `/tax_categories`, `/stores`, `/channels`, `/store_credit_categories`, staff (`/admin_users`, `/invitations`, `/roles`), `/allowed_origins`, `/custom_field_definitions/*` (schema config, consolidated — no dedicated scope) |
+| `read_webhooks` / `write_webhooks` | `/webhook_endpoints/*` + nested deliveries — split from `settings` because webhook endpoints exfiltrate event payloads (orders, customers) to arbitrary URLs |
+| `read_api_keys` / `write_api_keys` | `/api_keys/*` — credential administration, deliberately NOT under `settings`; pairs with the create-time anti-amplification guard (a key cannot mint scopes beyond its own). Industry norm (Shopify/Stripe/BigCommerce) is to exclude credential management from scopes entirely; the dedicated pair + guard is the grantable middle ground |
| `read_dashboard` | `/dashboard/*` (analytics; no write counterpart) |
| `read_all` | every `read_*` scope |
| `write_all` | every `read_*` and `write_*` scope (full admin) |
diff --git a/docs/plans/5.5-admin-spa-csv-export.md b/docs/plans/5.5-admin-spa-csv-export.md
index 032546ae76..15129e5f34 100644
--- a/docs/plans/5.5-admin-spa-csv-export.md
+++ b/docs/plans/5.5-admin-spa-csv-export.md
@@ -17,7 +17,7 @@ The legacy Rails admin (`spree/admin`) supports CSV export for products, orders,
- **Status feedback is toast + polling, then auto-download.** No separate page in v1. Email notification (existing `Spree::ExportMailer.export_done`) remains the durable backup. A future iteration can add a persistent `/exports` page if users ask for history.
- **Scope for v1: Products, Orders, Customers.** Other types (gift cards, coupons, newsletter, translations) work backend-side once endpoints exist; we just won't surface buttons for them in v1.
- **Download via signed Blob URL, not a server-side redirect.** The Admin API serializer exposes a short-lived signed URL the SPA fetches and triggers a browser download. This is the only way an SPA on a different origin can reliably download an attachment without losing JWT auth context. The legacy Rails admin's `redirect_to attachment.url` works for the same-origin Turbo flow but does not translate to the SPA.
-- **Auth: JWT only in v1.** Secret API keys (`sk_xxx`) with scopes (per `5.5-admin-api-key-scopes.md`) get exports later. Adding a `read_exports` / `write_exports` scope is straightforward but out of scope here.
+- **Auth: JWT only in v1.** Secret API keys (`sk_xxx`) with scopes (per `5.5-admin-api-key-scopes.md`) get exports later. ~~Adding a `read_exports` / `write_exports` scope is straightforward but out of scope here.~~ *Superseded (2026-06-12): no dedicated exports scope — each export type is gated by the read scope of the exported resource (`Spree::Export.required_scope`), so a key can never export data it couldn't read directly.*
- **No multi-select bulk export.** Like the legacy admin: export "filtered" (current Ransack query) or "all" (clears filters). Multi-select is a broader bulk-actions concern not yet built into the SPA.
## Design Details
@@ -285,7 +285,7 @@ PRs are sequential because each depends on the previous one's API contract.
- **Scoping `index` to current user vs all admins.** Legacy admin uses `accessible_by(current_ability)` which gives full-store admins everyone's exports. The SPA polling flow only needs the user's own. Default to `accessible_by` for parity, but consider an `mine: true` filter param if it becomes noisy.
- **Should `download_url` 30x redirect through our backend** so we can revoke individual exports? Probably not in v1 — `destroy` already purges the attachment, which invalidates the signed URL. Revisit if compliance asks.
- **Do we want a dedicated `/exports` history page?** Not in v1 per design decision above. Reassess after dogfooding — if users export weekly and re-download often, the page is cheap to add (it's just a `ResourceTable` over `client.exports.list`).
-- **Admin API key scopes for exports.** Out of scope here; needs a `read_exports` / `write_exports` scope added in `5.5-admin-api-key-scopes.md` before secret-key clients can hit these endpoints.
+- ~~**Admin API key scopes for exports.**~~ Resolved (2026-06-12): secret-key clients hit these endpoints using the exported resource's read scope (`read_products` for product exports, etc.) — see `5.5-admin-api-key-scopes.md`.
## References
diff --git a/docs/plans/5.5-agent-skills.md b/docs/plans/5.5-agent-skills.md
index 0d4e6bb17f..edddbd7998 100644
--- a/docs/plans/5.5-agent-skills.md
+++ b/docs/plans/5.5-agent-skills.md
@@ -1,10 +1,10 @@
# `spree/agent-skills` — Agentic CLI guidance for Spree projects
-**Status:** Design Finalized
+**Status:** Complete
**Target:** Spree 5.5
**Depends on:** none
**Author:** Damian Legawiec (`[email protected]`)
-**Last updated:** 2026-06-09
+**Last updated:** 2026-06-12
## Summary
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx
index 625df18c84..d5dec55c27 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/api-keys.tsx
@@ -79,16 +79,18 @@ export const Route = createFileRoute('/_authenticated/$storeId/settings/api-keys
const SCOPE_GROUPS: Array<{ label: string; resource: string; readOnly?: boolean }> = [
{ label: 'Orders', resource: 'orders' },
{ label: 'Products', resource: 'products' },
+ { label: 'Promotions', resource: 'promotions' },
{ label: 'Customers', resource: 'customers' },
{ label: 'Payments', resource: 'payments' },
{ label: 'Fulfillments', resource: 'fulfillments' },
{ label: 'Refunds', resource: 'refunds' },
{ label: 'Gift cards', resource: 'gift_cards' },
{ label: 'Store credits', resource: 'store_credits' },
+ { label: 'Stock', resource: 'stock' },
{ label: 'Categories', resource: 'categories' },
- { label: 'Custom field definitions', resource: 'custom_field_definitions' },
{ label: 'Settings', resource: 'settings' },
{ label: 'Webhooks', resource: 'webhooks' },
+ { label: 'API keys', resource: 'api_keys' },
{ label: 'Dashboard', resource: 'dashboard', readOnly: true },
]
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
index c66509c895..cf019f45cb 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
@@ -33,15 +33,23 @@ module Spree
self._scope_check_skipped = false
end
- # Opt out of scope checks (auth, me, tags, direct uploads, etc).
- def skip_scope_check!
- self._scope_check_skipped = true
+ # Opt out of scope checks — for the whole controller (auth, me,
+ # tags, etc.) or for specific actions (`only: :index`) when an
+ # action authorizes another way, e.g. by filtering its collection
+ # per-type (exports).
+ def skip_scope_check!(only: nil)
+ if only
+ self._scope_check_skipped_actions = Array(only).map(&:to_s)
+ else
+ self._scope_check_skipped = true
+ end
end
end
included do
class_attribute :_scoped_resource, instance_accessor: false
class_attribute :_scope_check_skipped, instance_accessor: false, default: false
+ class_attribute :_scope_check_skipped_actions, instance_accessor: false
before_action :authorize_api_key_scope!
end
@@ -50,6 +58,7 @@ module Spree
def authorize_api_key_scope!
return unless current_api_key
return if self.class._scope_check_skipped
+ return if self.class._scope_check_skipped_actions&.include?(action_name)
resource = scoped_resource_name
# Fail closed: a controller authenticated by API key MUST declare
@@ -82,6 +91,13 @@ module Spree
def action_kind
READ_ACTIONS.include?(action_name) ? 'read' : 'write'
end
+
+ # True when authorization derives from the API key's scopes rather
+ # than a JWT admin's CanCanCan ability. Mirrors the credential
+ # precedence in AdminAuthentication#current_ability (JWT user wins).
+ def scope_limited_principal?
+ current_api_key.present? && current_user.blank?
+ end
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
index b41bbe9847..260feea6eb 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
@@ -3,7 +3,10 @@ module Spree
module V3
module Admin
class ApiKeysController < ResourceController
- scoped_resource :settings
+ # Dedicated scope — key management is credential-administration, not
+ # store configuration. A `write_settings` key must not be able to
+ # revoke or destroy higher-privileged keys.
+ scoped_resource :api_keys
# POST /api/v3/admin/api_keys
# Prevents scope amplification: a key minted via a secret API key can
@@ -71,13 +74,6 @@ module Spree
private
- # True when authorization derives from the API key's scopes rather
- # than a JWT admin's CanCanCan ability. Mirrors the credential
- # precedence in AdminAuthentication#current_ability (JWT user wins).
- def scope_limited_principal?
- current_api_key.present? && current_user.blank?
- end
-
def requested_scopes
Array(params[:scopes]).map(&:to_s).reject(&:blank?)
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
index 98c49ba8a8..82d59b6f45 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/custom_field_definitions_controller.rb
@@ -8,7 +8,7 @@ module Spree
# (or any other registered custom-field-bearing resource) to scope the
# list to one parent type.
class CustomFieldDefinitionsController < ResourceController
- scoped_resource :custom_field_definitions
+ scoped_resource :settings
protected
diff --git a/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb
index 1b41c66870..255f078012 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/custom_fields_controller.rb
@@ -67,12 +67,20 @@ module Spree
klass.respond_to?(:for_store) ? klass.for_store(current_store) : klass
end
+ # Product-family parents have no scope pair of their own — their
+ # custom fields are catalog data, gated by `products` like the rest
+ # of the variant/option-type surface.
+ SCOPE_OVERRIDES = { 'option_type' => :products, 'variant' => :products }.freeze
+
# Per-parent scope check: a key holding `write_products` may write a
# product's custom fields, `write_orders` may write an order's, etc.
# Resolves the parent at request time rather than via the static
# `scoped_resource` declaration.
def scoped_resource_name
- parent_lookup&.segment&.pluralize&.to_sym
+ segment = parent_lookup&.segment
+ return unless segment
+
+ SCOPE_OVERRIDES[segment] || segment.pluralize.to_sym
end
# `custom_field_definition_id` is an alias_attribute on Spree::CustomField;
diff --git a/spree/api/app/controllers/spree/api/v3/admin/exports_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/exports_controller.rb
index 52e570d4f7..031691b3ac 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/exports_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/exports_controller.rb
@@ -3,10 +3,18 @@ module Spree
module V3
module Admin
# See `docs/plans/5.5-admin-spa-csv-export.md`.
+ #
+ # There is no standalone exports scope: an export is a bulk read of
+ # the records it contains, so each export type is gated by the read
+ # scope of the exported resource (Spree::Exports::Customers =>
+ # `read_customers`; see Spree::Export.required_scope), and the index
+ # is filtered to the types the key can read.
class ExportsController < ResourceController
include ActiveStorage::SetCurrent
- scoped_resource :exports
+ # The index spans many export types — `scope` filters it to the
+ # readable ones instead of gating on a single scope.
+ skip_scope_check! only: :index
# We stream the CSV inline rather than redirecting to ActiveStorage's
# signed-URL endpoint because the SPA's Vite proxy only forwards
@@ -47,6 +55,32 @@ module Spree
[:user, { attachment_attachment: :blob }]
end
+ def scope
+ collection = super
+ return collection unless scope_limited_principal?
+
+ collection.where(type: readable_export_types)
+ end
+
+ # Loaded by both the scope gate (before_action) and the member
+ # actions — memoize so the record is fetched once.
+ def find_resource
+ @find_resource ||= super
+ end
+
+ # Exports never mutate commerce data; creating or downloading one
+ # is a bulk read, so every action maps to the read-level scope.
+ def action_kind
+ 'read'
+ end
+
+ # Unresolvable types (blank/unknown `type` on create) fall back to
+ # `:all`, so only `read_all`/`write_all` keys reach the model's own
+ # validation.
+ def scoped_resource_name
+ export_class&.required_scope || :all
+ end
+
def build_resource
klass = resolve_export_type(permitted_params[:type]) || Spree::Export
attrs = permitted_params.except(:type).merge(
@@ -82,6 +116,19 @@ module Spree
target = Spree::Export.available_types.map(&:to_s).find { |t| t == name.to_s }
target&.constantize
end
+
+ private
+
+ def export_class
+ action_name == 'create' ? resolve_export_type(params[:type]) : find_resource.class
+ end
+
+ def readable_export_types
+ Spree::Export.available_types.select do |type|
+ required = type.required_scope
+ required ? current_api_key.has_scope?("read_#{required}") : current_api_key.has_scope?('read_all')
+ end.map(&:to_s)
+ end
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/stock_items_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/stock_items_controller.rb
index c839e22a9f..bb20d45d5e 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/stock_items_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/stock_items_controller.rb
@@ -6,7 +6,7 @@ module Spree
# location, so there's deliberately no `create` route — use the
# variants / stock-locations endpoints for that flow.
class StockItemsController < ResourceController
- scoped_resource :settings
+ scoped_resource :stock
protected
diff --git a/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb
index 2d4f02be94..74a59dc21b 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/stock_locations_controller.rb
@@ -3,7 +3,7 @@ module Spree
module V3
module Admin
class StockLocationsController < ResourceController
- scoped_resource :settings
+ scoped_resource :stock
protected
diff --git a/spree/api/app/controllers/spree/api/v3/admin/stock_transfers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/stock_transfers_controller.rb
index 8e0836e6a2..42b444786e 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/stock_transfers_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/stock_transfers_controller.rb
@@ -6,7 +6,7 @@ module Spree
# for receives. Pass `source_location_id` for transfers; omit it to
# record an external receive.
class StockTransfersController < ResourceController
- scoped_resource :settings
+ scoped_resource :stock
def create
authorize!(:create, model_class)
diff --git a/spree/api/app/controllers/spree/api/v3/admin/webhook_deliveries_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/webhook_deliveries_controller.rb
index e84a073909..4894178698 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/webhook_deliveries_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/webhook_deliveries_controller.rb
@@ -6,7 +6,7 @@ module Spree
# context of their endpoint (the delivery log on the endpoint detail
# page) and never accessed by ID at the top level.
class WebhookDeliveriesController < ResourceController
- scoped_resource :settings
+ scoped_resource :webhooks
# POST /api/v3/admin/webhook_endpoints/:webhook_endpoint_id/deliveries/:id/redeliver
#
diff --git a/spree/api/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb
index fefffbe7a9..402e18035e 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/webhook_endpoints_controller.rb
@@ -6,7 +6,7 @@ module Spree
# endpoint-scoped actions the legacy admin had (send_test, enable,
# disable).
class WebhookEndpointsController < ResourceController
- scoped_resource :settings
+ scoped_resource :webhooks
# POST /api/v3/admin/webhook_endpoints/:id/send_test
#
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/api_keys_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/api_keys_controller_spec.rb
index a62584400b..8b08f92a05 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/api_keys_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/api_keys_controller_spec.rb
@@ -8,10 +8,10 @@ RSpec.describe Spree::Api::V3::Admin::ApiKeysController, type: :controller do
before { request.headers.merge!(headers) }
describe 'POST #create — scope amplification guard' do
- # Authenticate as a secret key holding only `write_settings` so the
- # request passes the scope check for the `:settings`-scoped controller
+ # Authenticate as a secret key holding only `write_api_keys` so the
+ # request passes the scope check for the `:api_keys`-scoped controller
# but is bounded by what that key actually holds.
- let(:caller_key) { create(:api_key, :secret, store: store, scopes: ['write_settings']) }
+ let(:caller_key) { create(:api_key, :secret, store: store, scopes: ['write_api_keys']) }
let(:headers) { { 'x-spree-api-key' => caller_key.plaintext_token } }
it 'rejects minting a key with scopes beyond the caller\'s own' do
@@ -24,18 +24,31 @@ RSpec.describe Spree::Api::V3::Admin::ApiKeysController, type: :controller do
end
it 'allows minting a key with scopes the caller already holds' do
- post :create, params: { name: 'sibling', key_type: 'secret', scopes: ['write_settings'] }, as: :json
+ post :create, params: { name: 'sibling', key_type: 'secret', scopes: ['write_api_keys'] }, as: :json
expect(response).to have_http_status(:created)
- expect(json_response['scopes']).to eq(['write_settings'])
+ expect(json_response['scopes']).to eq(['write_api_keys'])
end
it 'allows the implied read scope of a held write scope' do
- post :create, params: { name: 'reader', key_type: 'secret', scopes: ['read_settings'] }, as: :json
+ post :create, params: { name: 'reader', key_type: 'secret', scopes: ['read_api_keys'] }, as: :json
expect(response).to have_http_status(:created)
end
+ context 'when the caller holds only write_settings' do
+ # Key management no longer rides the settings scope — a settings key
+ # cannot mint, revoke, or destroy credentials.
+ let(:caller_key) { create(:api_key, :secret, store: store, scopes: ['write_settings']) }
+
+ it 'is denied with the api_keys required_scope' do
+ post :create, params: { name: 'nope', key_type: 'secret', scopes: ['read_orders'] }, as: :json
+
+ expect(response).to have_http_status(:forbidden)
+ expect(json_response['error']['details']['required_scope']).to eq('write_api_keys')
+ end
+ end
+
context 'when the caller holds write_all' do
let(:caller_key) { create(:api_key, :secret, store: store, scopes: ['write_all']) }
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
index 642725c35f..13fd6bf34a 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/custom_field_definitions_controller_spec.rb
@@ -169,8 +169,8 @@ RSpec.describe Spree::Api::V3::Admin::CustomFieldDefinitionsController, type: :c
let(:api_key_headers) { { 'x-spree-api-key' => api_key.plaintext_token } }
let(:headers) { api_key_headers }
- context 'with read_custom_field_definitions' do
- let(:granted_scope) { 'read_custom_field_definitions' }
+ context 'with read_settings' do
+ let(:granted_scope) { 'read_settings' }
it 'allows index' do
get :index, as: :json
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb
index ef230256b6..56c1b2134b 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/custom_fields_controller_spec.rb
@@ -263,5 +263,28 @@ RSpec.describe Spree::Api::V3::Admin::CustomFieldsController, type: :controller
expect(response).to have_http_status(:forbidden)
end
end
+
+ context 'with a variant parent' do
+ # Regression: `variant` / `option_type` parents used to resolve to the
+ # ungrantable scope names `variants` / `option_types`, locking these
+ # endpoints to *_all keys. Both fold into `products` now.
+ let(:granted_scope) { 'write_products' }
+ let(:variant) { create(:variant) }
+ let(:variant_definition) do
+ create(:metafield_definition, :short_text_field, resource_type: 'Spree::Variant')
+ end
+
+ it 'allows creating a variant custom field with write_products' do
+ post :create,
+ params: {
+ variant_id: variant.prefixed_id,
+ custom_field_definition_id: variant_definition.prefixed_id,
+ value: 'ribbed'
+ },
+ as: :json
+
+ expect(response).to have_http_status(:created)
+ end
+ end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/exports_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/exports_controller_spec.rb
index 12004c9881..dd677c916b 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/exports_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/exports_controller_spec.rb
@@ -201,28 +201,59 @@ RSpec.describe Spree::Api::V3::Admin::ExportsController, type: :controller do
context 'with a secret API key' do
let(:headers) { api_key_headers }
- it 'allows index with read_exports scope' do
- secret_api_key.update!(scopes: ['read_exports'])
- get :index, as: :json
- expect(response).to have_http_status(:ok)
- end
-
- it 'allows create with write_exports scope' do
- secret_api_key.update!(scopes: ['write_exports'])
+ # No standalone exports scope — each export type is gated by the read
+ # scope of the exported resource (Spree::Export.required_scope), so a
+ # key can never export data it couldn't read through the API.
+ it 'allows creating a Products export with read_products' do
+ secret_api_key.update!(scopes: ['read_products'])
post :create, params: { type: 'Spree::Exports::Products' }, as: :json
expect(response).to have_http_status(:created)
end
- it 'rejects create when the key only has read_exports' do
- secret_api_key.update!(scopes: ['read_exports'])
- post :create, params: { type: 'Spree::Exports::Products' }, as: :json
+ it 'rejects creating a Customers export without read_customers' do
+ secret_api_key.update!(scopes: ['read_products'])
+ post :create, params: { type: 'Spree::Exports::Customers' }, as: :json
+
expect(response).to have_http_status(:forbidden)
+ expect(json_response['error']['details']['required_scope']).to eq('read_customers')
end
- it 'rejects exports endpoints when the key has only an unrelated scope' do
- secret_api_key.update!(scopes: ['read_orders'])
+ it 'filters the index to export types the key can read' do
+ customers_export = create(:export, type: 'Spree::Exports::Customers', store: store, user: admin_user)
+ secret_api_key.update!(scopes: ['read_products'])
+
get :index, as: :json
- expect(response).to have_http_status(:forbidden)
+
+ expect(response).to have_http_status(:ok)
+ ids = json_response['data'].map { |e| e['id'] }
+ expect(ids).to include(product_export.prefixed_id)
+ expect(ids).not_to include(customers_export.prefixed_id)
+ end
+
+ it 'hides exports of unreadable types from member actions' do
+ customers_export = create(:export, type: 'Spree::Exports::Customers', store: store, user: admin_user)
+ secret_api_key.update!(scopes: ['read_products'])
+
+ get :show, params: { id: customers_export.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+
+ it 'allows downloading an export of a readable type' do
+ product_export.attachment.attach(
+ io: StringIO.new("name,sku\n"), filename: 'products.csv', content_type: 'text/csv'
+ )
+ secret_api_key.update!(scopes: ['read_products'])
+
+ get :download, params: { id: product_export.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+
+ it 'gates coupon-code exports by the promotions scope' do
+ secret_api_key.update!(scopes: ['read_promotions'])
+ post :create, params: { type: 'Spree::Exports::CouponCodes' }, as: :json
+ expect(response).to have_http_status(:created)
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/scoped_authorization_spec.rb b/spree/api/spec/controllers/spree/api/v3/scoped_authorization_spec.rb
index e9dbcf715d..33f5dad32b 100644
--- a/spree/api/spec/controllers/spree/api/v3/scoped_authorization_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/scoped_authorization_spec.rb
@@ -100,3 +100,35 @@ RSpec.describe Spree::Api::V3::Admin::OrdersController, type: :controller do
end
end
end
+
+# Regression: the promotions controllers declare `scoped_resource :promotions`,
+# but the scope pair was missing from Spree::ApiKey::SCOPES, so no key could
+# ever be minted with it — promotion endpoints were reachable only via *_all.
+RSpec.describe Spree::Api::V3::Admin::PromotionsController, type: :controller do
+ render_views
+ include_context 'API v3 Admin'
+
+ let(:secret_key) { create(:api_key, :secret, store: store, created_by: admin_user, scopes: scopes) }
+
+ before { request.headers['X-Spree-Api-Key'] = secret_key.plaintext_token }
+
+ describe 'with read_promotions' do
+ let(:scopes) { ['read_promotions'] }
+
+ it 'allows reads' do
+ get :index, as: :json
+ expect(response).to have_http_status(:ok)
+ end
+ end
+
+ describe 'without a promotions scope' do
+ let(:scopes) { ['read_orders'] }
+
+ it 'denies with the promotions required_scope' do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:forbidden)
+ expect(JSON.parse(response.body)['error']['details']['required_scope']).to eq('read_promotions')
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb
index 1d968a5912..c36a055079 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe 'Admin API Keys API', type: :request, swagger_doc: 'api-reference
security [api_key: [], bearer_auth: []]
description 'Returns publishable and secret API keys for the current store. ' \
'Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.'
- admin_scope :read, :settings
+ admin_scope :read, :api_keys
admin_sdk_example 'api-keys/list'
@@ -49,7 +49,7 @@ RSpec.describe 'Admin API Keys API', type: :request, swagger_doc: 'api-reference
security [api_key: [], bearer_auth: []]
description 'Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; ' \
'publishable keys expose their token on every read since they are intended for client-side use.'
- admin_scope :write, :settings
+ admin_scope :write, :api_keys
admin_sdk_example 'api-keys/create'
@@ -95,7 +95,7 @@ RSpec.describe 'Admin API Keys API', type: :request, swagger_doc: 'api-reference
tags 'API Keys'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- admin_scope :read, :settings
+ admin_scope :read, :api_keys
admin_sdk_example 'api-keys/get'
@@ -116,7 +116,7 @@ RSpec.describe 'Admin API Keys API', type: :request, swagger_doc: 'api-reference
delete 'Delete an API key' do
tags 'API Keys'
security [api_key: [], bearer_auth: []]
- admin_scope :write, :settings
+ admin_scope :write, :api_keys
admin_sdk_example 'api-keys/delete'
@@ -140,7 +140,7 @@ RSpec.describe 'Admin API Keys API', type: :request, swagger_doc: 'api-reference
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.'
- admin_scope :write, :settings
+ admin_scope :write, :api_keys
admin_sdk_example 'api-keys/revoke'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
index c0b0cc75ae..e91d75ad15 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/custom_field_definitions_spec.rb
@@ -19,7 +19,7 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.'
- admin_scope :read, :custom_field_definitions
+ admin_scope :read, :settings
admin_sdk_example 'custom-field-definitions/list'
@@ -51,7 +51,7 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- admin_scope :write, :custom_field_definitions
+ admin_scope :write, :settings
admin_sdk_example 'custom-field-definitions/create'
@@ -110,7 +110,7 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
tags 'Custom Fields'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- admin_scope :read, :custom_field_definitions
+ admin_scope :read, :settings
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -136,7 +136,7 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
consumes 'application/json'
produces 'application/json'
security [api_key: [], bearer_auth: []]
- admin_scope :write, :custom_field_definitions
+ admin_scope :write, :settings
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -165,7 +165,7 @@ RSpec.describe 'Admin Custom Field Definitions API', type: :request, swagger_doc
tags 'Custom Fields'
security [api_key: [], bearer_auth: []]
description 'Deletes the definition and cascades to all custom field values referencing it.'
- admin_scope :write, :custom_field_definitions
+ admin_scope :write, :settings
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/exports_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/exports_spec.rb
index 345bb110a1..0ef62c417d 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/exports_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/exports_spec.rb
@@ -17,7 +17,7 @@ RSpec.describe 'Admin Exports API', type: :request, swagger_doc: 'api-reference/
security [api_key: [], bearer_auth: []]
description 'Returns CSV exports queued or completed for the current store. ' \
'Polled by the admin SPA to detect when an export finishes (`done: true`).'
- admin_scope :read, :exports
+ admin_scope_note 'the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc.'
admin_sdk_example 'exports/list'
@@ -49,7 +49,7 @@ RSpec.describe 'Admin Exports API', type: :request, swagger_doc: 'api-reference/
Generation is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,
then redirect the browser to `download_url` to fetch the file.
MD
- admin_scope :write, :exports
+ admin_scope_note 'the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc.'
admin_sdk_example 'exports/create'
@@ -108,7 +108,7 @@ RSpec.describe 'Admin Exports API', type: :request, swagger_doc: 'api-reference/
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns export status. While `done` is `false`, the SPA continues polling.'
- admin_scope :read, :exports
+ admin_scope_note 'the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc.'
admin_sdk_example 'exports/get'
@@ -130,7 +130,7 @@ RSpec.describe 'Admin Exports API', type: :request, swagger_doc: 'api-reference/
tags 'Exports'
security [api_key: [], bearer_auth: []]
description 'Removes the export and purges its attachment.'
- admin_scope :write, :exports
+ admin_scope_note 'the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc.'
admin_sdk_example 'exports/delete'
@@ -167,7 +167,7 @@ RSpec.describe 'Admin Exports API', type: :request, swagger_doc: 'api-reference/
'must fetch it (with `Authorization` header) and trigger the ' \
'browser download via a Blob URL — a top-level navigation cannot ' \
'carry the JWT.'
- admin_scope :read, :exports
+ admin_scope_note 'the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc.'
admin_sdk_example 'exports/download'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb
index cfc1b2cd54..d08c609c41 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/stock_locations_spec.rb
@@ -25,7 +25,7 @@ RSpec.describe 'Admin Stock Locations API', type: :request, swagger_doc: 'api-re
customers can collect orders from any active location with
`pickup_enabled: true`.
DESC
- admin_scope :read, :settings
+ admin_scope :read, :stock
admin_sdk_example 'stock-locations/list'
@@ -80,7 +80,7 @@ RSpec.describe 'Admin Stock Locations API', type: :request, swagger_doc: 'api-re
Setting `default: true` automatically demotes the previous default
location.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :stock
admin_sdk_example 'stock-locations/create'
@@ -164,7 +164,7 @@ RSpec.describe 'Admin Stock Locations API', type: :request, swagger_doc: 'api-re
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns a single stock location by prefixed ID.'
- admin_scope :read, :settings
+ admin_scope :read, :stock
admin_sdk_example 'stock-locations/get'
@@ -207,7 +207,7 @@ RSpec.describe 'Admin Stock Locations API', type: :request, swagger_doc: 'api-re
Setting `default: true` automatically demotes the previous default.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :stock
admin_sdk_example 'stock-locations/update'
@@ -274,7 +274,7 @@ RSpec.describe 'Admin Stock Locations API', type: :request, swagger_doc: 'api-re
fulfillments that referenced it keep the historical record via
`Spree::StockLocation.with_deleted`.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :stock
admin_sdk_example 'stock-locations/delete'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/webhook_deliveries_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/webhook_deliveries_spec.rb
index f3be363dc1..f2f92579e8 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/webhook_deliveries_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/webhook_deliveries_spec.rb
@@ -27,7 +27,7 @@ RSpec.describe 'Admin Webhook Deliveries API', type: :request, swagger_doc: 'api
error — everything needed to audit failures and decide whether to
redeliver.
DESC
- admin_scope :read, :settings
+ admin_scope :read, :webhooks
admin_sdk_example 'webhook-endpoints/deliveries/list'
@@ -82,7 +82,7 @@ RSpec.describe 'Admin Webhook Deliveries API', type: :request, swagger_doc: 'api
the response body the receiver returned. Use this for ad-hoc debug
of failed deliveries.
DESC
- admin_scope :read, :settings
+ admin_scope :read, :webhooks
admin_sdk_example 'webhook-endpoints/deliveries/get'
@@ -133,7 +133,7 @@ RSpec.describe 'Admin Webhook Deliveries API', type: :request, swagger_doc: 'api
Creates a new delivery row with the same payload + event_name and
queues it. The original row is preserved for audit history.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/deliveries/redeliver'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/webhook_endpoints_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/webhook_endpoints_spec.rb
index 8f3a68986e..167effb846 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/webhook_endpoints_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/webhook_endpoints_spec.rb
@@ -27,7 +27,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
`secret_key` is `null` on list reads — the plaintext is delivered
exactly once on create.
DESC
- admin_scope :read, :settings
+ admin_scope :read, :webhooks
admin_sdk_example 'webhook-endpoints/list'
@@ -83,7 +83,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
return `null` for the secret. Pass an empty `subscriptions` array or
omit it to receive every event.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/create'
@@ -143,7 +143,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Returns a single webhook endpoint by prefixed ID.'
- admin_scope :read, :settings
+ admin_scope :read, :webhooks
admin_sdk_example 'webhook-endpoints/get'
@@ -190,7 +190,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
Toggling `active` here is equivalent to calling `disable`/`enable`
without an audit reason.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/update'
@@ -233,7 +233,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
tags 'Webhooks'
security [api_key: [], bearer_auth: []]
description 'Soft-deletes the endpoint and stops future deliveries.'
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/delete'
@@ -262,7 +262,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
verify the endpoint is reachable and your signature verification
accepts Spree's payloads.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/send-test'
@@ -297,7 +297,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
produces 'application/json'
security [api_key: [], bearer_auth: []]
description 'Re-enables an endpoint that was manually or automatically disabled.'
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/enable'
@@ -332,7 +332,7 @@ RSpec.describe 'Admin Webhook Endpoints API', type: :request, swagger_doc: 'api-
Manually pauses an endpoint. Unlike auto-disable (triggered after
repeated delivery failures), no notification email is sent.
DESC
- admin_scope :write, :settings
+ admin_scope :write, :webhooks
admin_sdk_example 'webhook-endpoints/disable'
diff --git a/spree/api/spec/support/code_samples_helper.rb b/spree/api/spec/support/code_samples_helper.rb
index afed97fcb3..47b649f20d 100644
--- a/spree/api/spec/support/code_samples_helper.rb
+++ b/spree/api/spec/support/code_samples_helper.rb
@@ -86,7 +86,13 @@ module CodeSamplesHelper
# admin_scope :read, :orders
# admin_scope :write, :customers
def admin_scope(action, resource)
- line = "**Required scope:** `#{action}_#{resource}` (for API-key authentication)."
+ admin_scope_note("`#{action}_#{resource}`")
+ end
+
+ # Free-form variant for endpoints whose required scope is resolved at
+ # request time (e.g. exports — gated by the exported resource's scope).
+ def admin_scope_note(text)
+ line = "**Required scope:** #{text} (for API-key authentication)."
existing = metadata[:operation][:description].to_s
metadata[:operation][:description] = existing.empty? ? line : "#{existing}\n\n#{line}"
end
diff --git a/spree/core/app/models/spree/api_key.rb b/spree/core/app/models/spree/api_key.rb
index d31e125c18..2a2107c573 100644
--- a/spree/core/app/models/spree/api_key.rb
+++ b/spree/core/app/models/spree/api_key.rb
@@ -12,6 +12,7 @@ module Spree
SCOPES = %w[
read_orders write_orders
read_products write_products
+ read_promotions write_promotions
read_customers write_customers
read_payments write_payments
read_fulfillments write_fulfillments
@@ -20,10 +21,9 @@ module Spree
read_store_credits write_store_credits
read_stock write_stock
read_categories write_categories
- read_custom_field_definitions write_custom_field_definitions
- read_exports write_exports
read_settings write_settings
read_webhooks write_webhooks
+ read_api_keys write_api_keys
read_dashboard
read_all write_all
].freeze
diff --git a/spree/core/app/models/spree/export.rb b/spree/core/app/models/spree/export.rb
index 7d0206b58e..ebeccfe866 100644
--- a/spree/core/app/models/spree/export.rb
+++ b/spree/core/app/models/spree/export.rb
@@ -216,6 +216,21 @@ module Spree
Spree.export_types
end
+ # Admin API scope family gating this export type — an export is a bulk
+ # read, so an API key needs `read_<required_scope>` to create, view, and
+ # download it. Derived from the class name
+ # (Spree::Exports::Customers => :customers); override in subclasses whose
+ # records are gated by a different scope (e.g. coupon codes =>
+ # :promotions). Returns nil on the base class, so unmapped types are
+ # only accessible to `read_all`/`write_all` keys.
+ #
+ # @return [Symbol, nil]
+ def required_scope
+ return nil if self == Spree::Export
+
+ to_s.demodulize.underscore.to_sym
+ end
+
def available_models
available_types.map(&:model_class)
end
diff --git a/spree/core/app/models/spree/exports/coupon_codes.rb b/spree/core/app/models/spree/exports/coupon_codes.rb
index 907506334e..e541d72511 100644
--- a/spree/core/app/models/spree/exports/coupon_codes.rb
+++ b/spree/core/app/models/spree/exports/coupon_codes.rb
@@ -1,6 +1,10 @@
module Spree
module Exports
class CouponCodes < Spree::Export
+ def self.required_scope
+ :promotions
+ end
+
def csv_headers
Spree::CSV::CouponCodePresenter::HEADERS
end
diff --git a/spree/core/app/models/spree/exports/newsletter_subscribers.rb b/spree/core/app/models/spree/exports/newsletter_subscribers.rb
index 9949990dd8..2a01154ac2 100644
--- a/spree/core/app/models/spree/exports/newsletter_subscribers.rb
+++ b/spree/core/app/models/spree/exports/newsletter_subscribers.rb
@@ -1,6 +1,10 @@
module Spree
module Exports
class NewsletterSubscribers < Spree::Export
+ def self.required_scope
+ :customers
+ end
+
def scope_includes
[:user, { metafields: :metafield_definition }]
end
diff --git a/spree/core/app/models/spree/exports/product_translations.rb b/spree/core/app/models/spree/exports/product_translations.rb
index 7fdaa2685a..4ef9367a8b 100644
--- a/spree/core/app/models/spree/exports/product_translations.rb
+++ b/spree/core/app/models/spree/exports/product_translations.rb
@@ -1,6 +1,10 @@
module Spree
module Exports
class ProductTranslations < Spree::Export
+ def self.required_scope
+ :products
+ end
+
def scope_includes
[]
end
diff --git a/spree/core/spec/models/spree/export_spec.rb b/spree/core/spec/models/spree/export_spec.rb
index ce0035a203..e0f1fb1a36 100644
--- a/spree/core/spec/models/spree/export_spec.rb
+++ b/spree/core/spec/models/spree/export_spec.rb
@@ -15,6 +15,24 @@ RSpec.describe Spree::Export, :job, type: :model do
end
end
+ describe '.required_scope' do
+ it 'derives the scope family from the class name' do
+ expect(Spree::Exports::Products.required_scope).to eq(:products)
+ expect(Spree::Exports::Customers.required_scope).to eq(:customers)
+ expect(Spree::Exports::GiftCards.required_scope).to eq(:gift_cards)
+ end
+
+ it 'honors subclass overrides where the data is gated by a different scope' do
+ expect(Spree::Exports::CouponCodes.required_scope).to eq(:promotions)
+ expect(Spree::Exports::NewsletterSubscribers.required_scope).to eq(:customers)
+ expect(Spree::Exports::ProductTranslations.required_scope).to eq(:products)
+ end
+
+ it 'returns nil on the base class (fail closed — *_all keys only)' do
+ expect(Spree::Export.required_scope).to be_nil
+ end
+ end
+
describe '#export_file_name' do
before { export.save! }