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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added Admin API documentation
Damian Legawiec710f1a77141a
diff --git a/docs/api-reference/admin-api/authentication.mdx b/docs/api-reference/admin-api/authentication.mdxnew file mode 100644index 0000000000..c733200257--- /dev/null+++ b/docs/api-reference/admin-api/authentication.mdx@@ -0,0 +1,173 @@+---+title: "Authentication"+sidebarTitle: "Authentication"+description: "How to authenticate requests to the Admin API"+---++The Admin API supports two authentication methods: **secret API keys** for server-to-server integrations, and **JWT bearer tokens** for admin SPA / interactive sessions. Every request must include credentials — there is no public surface.++<Warning>+Secret API keys grant full administrative access to your store. **Never embed them in client-side code, mobile apps, or public repositories.** Use them only from secure server environments.+</Warning>++## Secret API key++Pass the key via the `X-Spree-Api-Key` header:++<CodeGroup>++```typescript SDK+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://store.example.com',+ secretKey: 'sk_xxx',+})++// The SDK automatically sends the secret key with every request+const { data: products } = await client.products.list()+```++```bash cURL+curl -X GET 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx'+```++</CodeGroup>++Secret API keys are prefixed with `sk_`. Create them in the Spree admin under **Settings → API Keys** or via the Spree CLI:++```bash+spree api-key create --type secret # Create a new secret key+spree api-key list # List existing keys+spree api-key revoke <key_id> # Revoke a key+```++<Warning>+If you omit the API key, the API returns `401 Unauthorized`:++```json+{+ "error": {+ "code": "authentication_required",+ "message": "Authentication required"+ }+}+```+</Warning>++## JWT bearer token (admin user)++For interactive admin sessions (the Spree admin SPA, custom dashboards, etc.) authenticate as an admin user and use the returned JWT token for subsequent requests.++### Login++<CodeGroup>++```typescript SDK+const { token, user } = await client.auth.login({+ email: '[email protected]',+ password: 'secret123',+})++// Use the token for authenticated requests+const orders = await client.orders.list({}, { bearerToken: token })+```++```bash cURL+curl -X POST 'https://store.example.com/api/v3/admin/auth/login' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{"email": "[email protected]", "password": "secret123"}'+```++</CodeGroup>++### Token refresh++JWT tokens expire after 1 hour by default. Refresh them with the current token:++<CodeGroup>++```typescript SDK+const { token } = await client.auth.refresh({ token: currentToken })+```++```bash cURL+curl -X POST 'https://store.example.com/api/v3/admin/auth/refresh' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -H 'Authorization: Bearer <current_jwt_token>'+```++</CodeGroup>++## Permissions++Authorization works differently depending on which credentials you use.++### Secret API keys: scopes++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 |+|---|---|+| `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_fulfillments` / `write_fulfillments` | `/orders/:id/fulfillments` |+| `read_refunds` / `write_refunds` | `/orders/:id/refunds` |+| `read_gift_cards` / `write_gift_cards` | `/orders/:id/gift_cards` |+| `read_store_credits` / `write_store_credits` | `/customers/:id/store_credits`, `/orders/:id/store_credits` |+| `read_categories` / `write_categories` | `/categories/*` |+| `read_settings` / `write_settings` | `/payment_methods`, `/markets`, `/countries`, `/tax_categories`, `/store` |+| `read_dashboard` | `/dashboard/*` (analytics) |++Two convenience aliases:++- **`read_all`** — every `read_*` scope+- **`write_all`** — every `read_*` and `write_*` scope (full admin)++If the key lacks the required scope, the API returns `403 Forbidden`:++```json+{+ "error": {+ "code": "access_denied",+ "message": "API key lacks scope: write_orders",+ "details": {+ "required_scope": "write_orders"+ }+ }+}+```++The `details.required_scope` field tells you exactly which scope to add.++Pick scopes when creating the key in **Settings → API Keys**. Choose the narrowest set that covers your integration's needs.++### JWT bearer tokens: CanCanCan abilities++JWT-authenticated admin users are authorized via [CanCanCan](https://github.com/CanCanCommunity/cancancan) abilities derived from their `Spree::Role`s. The SPA uses this fine-grained model to render UI conditionally; partial-permission staff users see only the resources their role grants.++If the caller lacks permission for a specific action, the API returns `403 Forbidden`:++```json+{+ "error": {+ "code": "access_denied",+ "message": "You are not authorized to perform this action"+ }+}+```++## Authentication summary++| Method | Header | Use case | Authorization |+|---|---|---|---|+| Secret API key | `X-Spree-Api-Key: sk_xxx` | Server-to-server integrations | Scopes |+| JWT token | `Authorization: Bearer <token>` | Interactive admin sessions; SPA | CanCanCan abilities |++<Note>+If both headers are present, the JWT token wins: CanCanCan applies and scopes are ignored. This lets you use `sk_xxx` to bootstrap a session and then issue per-user JWTs for individual admin actions.+</Note>diff --git a/docs/api-reference/admin-api/errors.mdx b/docs/api-reference/admin-api/errors.mdxnew file mode 100644index 0000000000..45df281d89--- /dev/null+++ b/docs/api-reference/admin-api/errors.mdx@@ -0,0 +1,277 @@+---+title: Errors+description: Error response format and admin-specific error codes+---++The Admin API uses the same Stripe-style error format as the rest of the Spree v3 API. Every error response carries a machine-readable `code` and a human-readable `message`.++## Error response format++```json+{+ "error": {+ "code": "record_not_found",+ "message": "Order not found"+ }+}+```++Validation errors include a `details` field with per-field error messages:++```json+{+ "error": {+ "code": "validation_error",+ "message": "Email is invalid and Phone can't be blank",+ "details": {+ "email": ["is invalid"],+ "phone": ["can't be blank"]+ }+ }+}+```++Some specialized errors carry structured `details` (for example, scope errors include the `required_scope`):++```json+{+ "error": {+ "code": "access_denied",+ "message": "API key lacks scope: write_orders",+ "details": {+ "required_scope": "write_orders"+ }+ }+}+```++### Schema++| Field | Type | Description |+|---|---|---|+| `error.code` | `string` | Machine-readable error code (see tables below) |+| `error.message` | `string` | Human-readable description of the error |+| `error.details` | `object` | Optional. Field-specific validation errors or structured context (varies by `code`). |++## HTTP status codes++| Status | Meaning | When |+|---|---|---|+| `400` | Bad Request | Missing required parameters, malformed JSON |+| `401` | Unauthorized | Missing or invalid API key, expired or invalid JWT token |+| `403` | Forbidden | Authenticated but lacks permission (CanCanCan ability) or scope |+| `404` | Not Found | Resource doesn't exist, isn't accessible to the calling key, or belongs to a different store |+| `409` | Conflict | Resource was modified by a concurrent request (optimistic locking) |+| `422` | Unprocessable Content | Validation failed, invalid state transition, business rule violation |+| `429` | Too Many Requests | Login/refresh rate limit exceeded |++## Authentication & authorization++| Code | Status | Description |+|---|---|---|+| `authentication_required` | 401 | Request reached a protected endpoint with no credentials |+| `authentication_failed` | 401 | Login email/password was wrong |+| `invalid_token` | 401 | API key or JWT token is invalid or expired |+| `invalid_refresh_token` | 401 | Refresh token is invalid or expired |+| `access_denied` | 403 | Caller lacks permission. For API-key callers, `details.required_scope` indicates the missing scope (see [Authentication](/api-reference/admin-api/authentication#permissions)). For JWT callers, the user's role lacks the CanCanCan ability for this action. |+| `current_password_invalid` | 422 | Current password is wrong (when changing password) |++## Resources++| Code | Status | Description |+|---|---|---|+| `record_not_found` | 404 | Resource doesn't exist or isn't accessible in the calling key's store |+| `resource_invalid` | 422 | Resource couldn't be saved |++## Validation++| Code | Status | Description |+|---|---|---|+| `validation_error` | 422 | Model validation failed. Inspect `details` for field-specific messages. |+| `parameter_missing` | 400 | A required parameter is missing |+| `parameter_invalid` | 400 | A parameter has an invalid value |++## Orders++| Code | Status | Description |+|---|---|---|+| `cart_cannot_transition` | 422 | Order state machine refused the transition (e.g., completing an order without an address or payment) |+| `cart_already_updated` | 409 | Order was modified by a concurrent request. Refetch and retry. See [optimistic locking](#optimistic-locking) below. |+| `cart_invalid_state` | 422 | Order is in a state that doesn't allow this operation |+| `cart_empty` | 422 | Cannot complete an order with no line items |++## Customers++| Code | Status | Description |+|---|---|---|+| `customer_has_orders` | 422 | Cannot delete a customer with completed orders. Anonymize instead. |++## Store credits++| Code | Status | Description |+|---|---|---|+| `store_credit_in_use` | 422 | Cannot edit `amount` on or delete a store credit that has been partially or fully used. |++## Tags++| Code | Status | Description |+|---|---|---|+| `invalid_taggable_type` | 422 | The `taggable_type` query param isn't one of the allowed values (`Spree::Product`, `Spree::Order`, `Spree::User`). |++## Payments++| Code | Status | Description |+|---|---|---|+| `payment_failed` | 422 | Payment was declined by the gateway |+| `payment_processing_error` | 422 | Spree couldn't process the payment due to an internal error |+| `gateway_error` | 422 | Payment gateway returned an error |++## Examples++### Insufficient scope (API key)++```bash+curl -X POST 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{"email": "[email protected]"}'+```++```json 403+{+ "error": {+ "code": "access_denied",+ "message": "API key lacks scope: write_orders",+ "details": {+ "required_scope": "write_orders"+ }+ }+}+```++### Validation error (customer create)++```bash+curl -X POST 'https://store.example.com/api/v3/admin/customers' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{}'+```++```json 422+{+ "error": {+ "code": "validation_error",+ "message": "Email can't be blank",+ "details": {+ "email": ["can't be blank"]+ }+ }+}+```++### Customer with completed orders++```bash+curl -X DELETE 'https://store.example.com/api/v3/admin/customers/cus_xxx' \+ -H 'X-Spree-Api-Key: sk_xxx'+```++```json 422+{+ "error": {+ "code": "customer_has_orders",+ "message": "Cannot delete customer with completed orders"+ }+}+```++### Concurrent order update++```bash+curl -X PATCH 'https://store.example.com/api/v3/admin/orders/or_xxx' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{"email": "[email protected]"}'+```++```json 409+{+ "error": {+ "code": "cart_already_updated",+ "message": "Order was modified by another request. Refetch and retry."+ }+}+```++## Handling errors with the SDK++`@spree/admin-sdk` throws a `SpreeError` for every non-2xx response:++```typescript+import { SpreeError } from '@spree/admin-sdk'++try {+ await client.orders.update(orderId, { email: '[email protected]' })+} catch (error) {+ if (error instanceof SpreeError) {+ console.log(error.code) // 'cart_already_updated'+ console.log(error.message) // 'Order was modified by another request...'+ console.log(error.status) // 409+ console.log(error.details) // undefined or { ... }+ }+}+```++### Common patterns++**Branch on error code**:++```typescript+try {+ await client.customers.delete(customerId)+} catch (error) {+ if (error instanceof SpreeError && error.code === 'customer_has_orders') {+ // Anonymize instead of deleting+ return anonymizeCustomer(customerId)+ }+ throw error+}+```++**Retry on optimistic-lock conflicts**:++```typescript+async function updateOrderWithRetry(id, params, attempts = 3) {+ for (let i = 0; i < attempts; i++) {+ try {+ return await client.orders.update(id, params)+ } catch (error) {+ if (error instanceof SpreeError && error.code === 'cart_already_updated' && i < attempts - 1) {+ continue+ }+ throw error+ }+ }+}+```++**Show field-level validation errors**:++```typescript+try {+ await client.customers.create(customerData)+} catch (error) {+ if (error instanceof SpreeError && error.details) {+ for (const [field, messages] of Object.entries(error.details)) {+ setFieldError(field, (messages as string[]).join(', '))+ }+ }+}+```++## Optimistic locking++Orders use a `state_lock_version` column to detect concurrent modifications. Every state-changing operation increments it; if two callers update the same order simultaneously, the second write fails with `cart_already_updated` (409) — refetch and retry.++This protects against race conditions when multiple clients (or the same client, retried) try to mutate the same order. Combined with idempotency at the integration level (e.g., dedupe webhook deliveries by event ID), it makes admin order management safe under concurrency.diff --git a/docs/api-reference/admin-api/introduction.mdx b/docs/api-reference/admin-api/introduction.mdxnew file mode 100644index 0000000000..0b1073928e--- /dev/null+++ b/docs/api-reference/admin-api/introduction.mdx@@ -0,0 +1,70 @@+---+title: "Admin API"+sidebarTitle: "Introduction"+---++<Warning>+**Developer Preview.** The Admin API is in active development and may change between major versions.+</Warning>++The Admin API is a REST API for managing a Spree stores programmatically — products, orders, customers, fulfillments, payments, and more. It is intended for backend integrations, custom admin tooling, and automation.++All routes are prefixed with `/api/v3/admin`. During development the API is available under `http://localhost:3000/api/v3/admin`. For production, replace `http://localhost:3000` with your Spree application URL.++## Admin API vs Store API++| | Admin API | Store API |+|---|---|---|+| **Purpose** | Manage store data | Power storefronts |+| **Audience** | Staff users, backend integrations | Customers, storefronts |+| **Authentication** | Secret API key (`sk_…`) or admin JWT | Publishable API key (`pk_…`), customer JWT, order token |+| **Permissions** | API key scopes (API key authentication) or Admin Staff permission sets | Customer can only read/modify their own data |+| **Write operations** | Full CRUD on most resources | Limited to the current customer's cart, addresses, profile |++If you're building a storefront, use the [Store API](/api-reference/store-api/introduction). The Admin API exposes administrative operations that should never be invoked from a browser.++## Using the SDK++We recommend using `@spree/admin-sdk` to interact with the Admin API. It provides typed clients, automatic retries, and idempotency support.++### Installation++```bash+npm install @spree/admin-sdk+# or+yarn add @spree/admin-sdk+# or+pnpm add @spree/admin-sdk+```++### Quick start++```typescript+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'http://localhost:3000',+ secretKey: 'sk_xxx',+})++const { data: orders } = await client.orders.list({+ status_eq: 'complete',+ limit: 25,+})+```++## What's covered++The Admin API today (in Spree 5.5) covers:++- **Catalog** — products, variants, prices+- **Orders** — list, create, update, items, complete, cancel, approve, resume; nested fulfillments, payments, refunds, gift cards, store credits+- **Customers** — full CRUD, addresses, store credits, credit cards++See the **Endpoints** section in the sidebar for the complete reference, generated from the OpenAPI spec.++Before integrating, read:++- [Authentication](/api-reference/admin-api/authentication) — secret API keys, scopes, and JWT tokens+- [Errors](/api-reference/admin-api/errors) — error format and admin-specific codes+- [Querying](/api-reference/admin-api/querying) — filtering, sorting, pagination, and `expand`diff --git a/docs/api-reference/admin-api/querying.mdx b/docs/api-reference/admin-api/querying.mdxnew file mode 100644index 0000000000..de9902a349--- /dev/null+++ b/docs/api-reference/admin-api/querying.mdx@@ -0,0 +1,318 @@+---+title: "Querying"+sidebarTitle: "Querying"+description: "Filter, sort, paginate, and expand Admin API list responses"+---++The Admin API uses [Ransack](https://activerecord-hackery.github.io/ransack/) for filtering and sorting on collection endpoints. All filter conditions go through the `q` parameter; sorting and pagination are top-level params.++## Filtering++Pass filter conditions via `q`:++<CodeGroup>++```typescript SDK+const orders = await client.orders.list({+ status_eq: 'complete',+ total_gteq: 100,+ email_cont: '@example.com',+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ --data-urlencode 'q[status_eq]=complete' \+ --data-urlencode 'q[total_gteq]=100' \+ --data-urlencode 'q[email_cont][email protected]'+```++</CodeGroup>++<Note>+The SDK automatically wraps filter keys in `q[...]` and appends `[]` for array values — pass flat params.+</Note>++### Common predicates++| Predicate | Description | SDK | cURL |+|---|---|---|---|+| `eq` | Equals | `status_eq: 'complete'` | `q[status_eq]=complete` |+| `not_eq` | Not equals | `status_not_eq: 'canceled'` | `q[status_not_eq]=canceled` |+| `cont` | Contains (case-insensitive) | `email_cont: '@acme'` | `q[email_cont]=@acme` |+| `start` | Starts with | `number_start: 'R10'` | `q[number_start]=R10` |+| `end` | Ends with | `slug_end: 'sale'` | `q[slug_end]=sale` |+| `lt` / `lteq` | Less than / less than or equal | `total_lteq: 50` | `q[total_lteq]=50` |+| `gt` / `gteq` | Greater than / greater than or equal | `total_gteq: 100` | `q[total_gteq]=100` |+| `in` | In a list | `status_in: ['complete', 'canceled']` | `q[status_in][]=complete&q[status_in][]=canceled` |+| `null` / `not_null` | Is null / not null | `completed_at_not_null: true` | `q[completed_at_not_null]=true` |+| `true` / `false` | Boolean | `accepts_email_marketing_true: 1` | `q[accepts_email_marketing_true]=1` |++### Prefixed IDs in filters++Resource ID filters accept Stripe-style prefixed IDs directly. The server decodes them before querying:++<CodeGroup>++```typescript SDK+// All orders for a specific customer+const orders = await client.orders.list({+ user_id_eq: 'cus_UkLWZg9DAJ',+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ --data-urlencode 'q[user_id_eq]=cus_UkLWZg9DAJ'+```++</CodeGroup>++The same applies to `_id_in`, `_id_not_eq`, and other ID predicates.++### Combining filters++Multiple filters combine with AND:++<CodeGroup>++```typescript SDK+// Completed orders over $100 from the last 7 days+const orders = await client.orders.list({+ status_eq: 'complete',+ total_gteq: 100,+ completed_at_gteq: new Date(Date.now() - 7 * 86_400_000).toISOString(),+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ --data-urlencode 'q[status_eq]=complete' \+ --data-urlencode 'q[total_gteq]=100' \+ --data-urlencode 'q[completed_at_gteq]=2026-04-22T00:00:00Z'+```++</CodeGroup>++### Filtering by association++Use underscore notation to filter on associated model attributes:++<CodeGroup>++```typescript SDK+// Customers tagged as "wholesale"+const customers = await client.customers.list({+ tags_name_eq: 'wholesale',+})++// Products in a specific category+const products = await client.products.list({+ taxons_id_eq: 'ctg_xxx',+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/customers' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ --data-urlencode 'q[tags_name_eq]=wholesale'+```++</CodeGroup>++### Custom search scopes++Some resources expose convenience search scopes:++| Resource | Scope | Example |+|---|---|---|+| Customers | `search` | Full-text over email + first/last name |+| Customers | `with_min_total_spent` | Filter by lifetime spend |+| Orders | `multi_search` | Number + email full-text |++<CodeGroup>++```typescript SDK+const customers = await client.customers.list({+ search: 'jane',+})++const vipCustomers = await client.customers.list({+ with_min_total_spent: 1000,+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/customers' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ --data-urlencode 'q[search]=jane'+```++</CodeGroup>++## Sorting++Use the top-level `sort` parameter on any list endpoint. Prefix with `-` for descending. Follows the [JSON:API sorting convention](https://jsonapi.org/format/#fetching-sorting).++<CodeGroup>++```typescript SDK+// Most recent orders first+const orders = await client.orders.list({+ sort: '-completed_at',+})++// Multiple sort keys (priority left to right)+const customers = await client.customers.list({+ sort: '-total_spent,email',+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -d 'sort=-completed_at'+```++</CodeGroup>++Sortable columns are limited to those whitelisted on the model (Ransack's `whitelisted_ransackable_attributes`). Sorting on a virtual column (e.g., a serializer-computed field like `display_total_spent`) is not supported.++## Pagination++All collection endpoints return paginated results. Control with `page` and `limit`:++<CodeGroup>++```typescript SDK+const { data: orders, meta } = await client.orders.list({+ page: 2,+ limit: 50,+})++// meta.count, meta.pages, meta.previous, meta.next ...+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -d 'page=2' \+ -d 'limit=50'+```++</CodeGroup>++| Parameter | Default | Max | Description |+|---|---|---|---|+| `page` | `1` | — | Page number (1-indexed) |+| `limit` | `25` | `100` | Records per page |++### Pagination metadata++Responses include a `meta` object:++```json+{+ "data": [...],+ "meta": {+ "page": 2,+ "limit": 50,+ "count": 327,+ "pages": 7,+ "from": 51,+ "to": 100,+ "in": 50,+ "previous": 1,+ "next": 3+ }+}+```++| Field | Description |+|---|---|+| `page` | Current page number |+| `limit` | Records per page |+| `count` | Total number of matching records |+| `pages` | Total number of pages |+| `from` / `to` / `in` | Position range / count of this page |+| `previous` / `next` | Previous/next page number, or `null` |++## Expanding associations++Most admin endpoints return slim payloads by default — associations are returned as IDs. Use the `expand` parameter to include related resources inline:++<CodeGroup>++```typescript SDK+const order = await client.orders.get('or_xxx', {+ expand: ['items', 'fulfillments', 'payments', 'customer'],+})++// Nested expand+const customer = await client.customers.get('cus_xxx', {+ expand: ['addresses', 'store_credits'],+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders/or_xxx' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -d 'expand=items,fulfillments,payments,customer'+```++</CodeGroup>++### Nested expand++Use dot notation up to 4 levels deep:++```typescript+const order = await client.orders.get('or_xxx', {+ expand: ['items.variant.product', 'fulfillments.tracking'],+})+```++A nested expand implicitly includes its parent — `expand: ['items.variant']` returns both `items` and their `variant` data.++### What can I expand?++Each endpoint documents its supported expand keys in the OpenAPI reference. Common admin expansions:++| Resource | Common expands |+|---|---|+| Orders | `items`, `fulfillments`, `payments`, `customer`, `discounts`, `adjustments`, `billing_address`, `shipping_address` |+| Customers | `addresses`, `store_credits`, `orders` |+| Products | `variants`, `media`, `option_types`, `categories` |++## Field selection++Use the `fields` parameter to request only specific fields on a resource. Reduces payload size for bandwidth-sensitive integrations:++<CodeGroup>++```typescript SDK+const orders = await client.orders.list({+ fields: ['number', 'total', 'status', 'completed_at'],+})+```++```bash cURL+curl -G 'https://store.example.com/api/v3/admin/orders' \+ -H 'X-Spree-Api-Key: sk_xxx' \+ -d 'fields=number,total,status,completed_at'+```++</CodeGroup>++Rules:++- `id` is always included+- Expanded associations return their full payload regardless of `fields`+- Field selection applies to the top-level resource only++<Note>+TypeScript types in `@spree/admin-sdk` remain fully typed regardless of `fields`. At runtime, only the requested fields are present — the rest are `undefined`.+</Note>diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex ec524c5270..e7c07ff8e8 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -19,10 +19,11 @@ info:All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.Single resource endpoints return a flat JSON object.- ## Prefixed IDs+ ## Resource IDs- All resources use Stripe-style prefixed IDs (e.g., `prod_86Rf07xd4z`, `variant_k5nR8xLq`).- These IDs must be used in all API requests.+ Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,+ `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,+ request bodies, and Ransack filters all accept them directly.## Error Handling@@ -38,158 +39,30 @@ info:```version: v3paths:- "/api/v3/admin/auth/login":- post:- summary: Login+ "/api/v3/admin/customers/{customer_id}/addresses":+ get:+ summary: List customer addressestags:- - Authentication+ - Customerssecurity:- api_key: []- description: Authenticates an admin user with email/password and returns a JWT- token- x-codeSamples:- - lang: javascript- label: Spree SDK- source: |-- import { createClient } from '@spree/sdk'-- const client = createClient({- baseUrl: 'https://your-store.com',- publishableKey: '<api-key>',- })+ bearer_auth: []+ description: |-+ Returns the customer's saved addresses.- const auth = await client.admin.auth.login({- email: '[email protected]',- password: 'password123',- })- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- responses:- '200':- description: login successful- content:- application/json:- example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImM5NzViYWMyLWQ2ZDAtNGUzYi05ZjIzLWYzOGQ1ZThkYjI2YiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzc3NDgxOTU3fQ.Elr15JDX9WdP642o93ARGZHULvGT1U3kvyM4ILdsvIQ- refresh_token: WVPfTx9y6NKzbcbexoiCndna- user:- id: admin_UkLWZg9DAJ- email: [email protected]- first_name: Zulema- last_name: Mertz- created_at: '2026-04-29T15:59:16.744Z'- updated_at: '2026-04-29T15:59:16.744Z'- schema:- "$ref": "#/components/schemas/AuthResponse"- '401':- description: non-admin user- content:- application/json:- example:- error:- code: authentication_failed- message: Invalid email or password- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- provider:- type: string- example: email- description: 'Authentication provider (default: email)'- email:- type: string- format: email- example: [email protected]- password:- type: string- example: password123- required:- - password- "/api/v3/admin/auth/refresh":- post:- summary: Refresh token- tags:- - Authentication- security:- - api_key: []- description: Rotates a refresh token and returns a new JWT access token+ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascript- label: Spree SDK+ label: Spree Admin SDKsource: |-- import { createClient } from '@spree/sdk'+ import { createAdminClient } from '@spree/admin-sdk'- const client = createClient({+ const client = createAdminClient({baseUrl: 'https://your-store.com',- publishableKey: '<api-key>',+ secretKey: 'sk_xxx',})- const auth = await client.admin.auth.refresh({- refresh_token: 'rt_xxx',- })- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- responses:- '200':- description: token refreshed- content:- application/json:- example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImZkZjY0ZThmLTNlODctNDUwMS1hYjcwLTBhMTZmMDkxY2ViZSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzc3NDgxOTU4fQ.DNJOApfWkt2la3eF6CjAaNh2YMfa8BF7lNdUoI4vBWU- refresh_token: Xiak23mXy1AEHeVkrcxYGH43- user:- id: admin_UkLWZg9DAJ- email: [email protected]- first_name: Lucille- last_name: Gottlieb- created_at: '2026-04-29T15:59:18.242Z'- updated_at: '2026-04-29T15:59:18.242Z'- schema:- "$ref": "#/components/schemas/AuthResponse"- '401':- description: missing or invalid refresh token- content:- application/json:- example:- error:- code: invalid_refresh_token- message: Invalid or expired refresh token- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- refresh_token:- type: string- description: Refresh token obtained from login- required:- - refresh_token- "/api/v3/admin/customers/{customer_id}/addresses":- get:- summary: List customer addresses- tags:- - Customer Addresses- security:- - api_key: []- bearer_auth: []- description: Returns the customer's saved addresses.+ const { data: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -232,8 +105,8 @@ paths:is_default_shipping: falsestate_name: New Yorklabel:- created_at: '2026-04-29T15:59:18.556Z'- updated_at: '2026-04-29T15:59:18.556Z'+ created_at: '2026-04-29T20:30:07.832Z'+ updated_at: '2026-04-29T20:30:07.832Z'customer_id: cus_UkLWZg9DAJmetadata:meta:@@ -249,13 +122,37 @@ paths:post:summary: Create a customer addresstags:- - Customer Addresses+ - Customerssecurity:- api_key: []bearer_auth: []- description: 'Adds a new address to the customer''s address book. Pass `is_default_billing:- true` or `is_default_shipping: true` to set as the default — the previous- default loses its flag in the same transaction.'+ description: |-+ Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const address = await client.customers.addresses.create('cus_UkLWZg9DAJ', {+ first_name: 'Jane',+ last_name: 'Doe',+ address1: '350 Fifth Avenue',+ city: 'New York',+ postal_code: '10118',+ country_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ label: 'Office',+ is_default_shipping: true,+ })parameters:- name: x-spree-api-keyin: header@@ -297,8 +194,8 @@ paths:is_default_shipping: falsestate_name: New Yorklabel: Office- created_at: '2026-04-29T15:59:19.950Z'- updated_at: '2026-04-29T15:59:19.950Z'+ created_at: '2026-04-29T20:30:09.242Z'+ updated_at: '2026-04-29T20:30:09.242Z'customer_id: cus_UkLWZg9DAJmetadata:requestBody:@@ -339,10 +236,30 @@ paths:patch:summary: Update a customer addresstags:- - Customer Addresses+ - Customerssecurity:- api_key: []bearer_auth: []+ description: |-+ Updates a customer address.++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const address = await client.customers.addresses.update(+ 'cus_UkLWZg9DAJ',+ 'addr_UkLWZg9DAJ',+ { city: 'Manhattan' },+ )parameters:- name: x-spree-api-keyin: header@@ -389,8 +306,8 @@ paths:is_default_shipping: falsestate_name: New Yorklabel:- created_at: '2026-04-29T15:59:20.237Z'- updated_at: '2026-04-29T15:59:20.824Z'+ created_at: '2026-04-29T20:30:09.540Z'+ updated_at: '2026-04-29T20:30:10.087Z'customer_id: cus_UkLWZg9DAJmetadata:requestBody:@@ -408,12 +325,26 @@ paths:delete:summary: Delete a customer addresstags:- - Customer Addresses+ - Customerssecurity:- api_key: []bearer_auth: []- description: Deletes the address. If it was a default, the customer loses that- default (no auto-promotion).+ description: |-+ Deletes the address. If it was a default, the customer loses that default (no auto-promotion).++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -442,12 +373,26 @@ paths:get:summary: List customer credit cardstags:- - Customer Credit Cards+ - Customerssecurity:- api_key: []bearer_auth: []- description: Returns the customer's saved credit cards. Useful for off-session- admin charges via `POST /admin/orders/:id/payments { source_id }`.+ description: |-+ Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.++ **Required scope:** `read_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -481,8 +426,8 @@ paths:gateway_payment_profile_id:customer_id: cus_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- created_at: '2026-04-29T15:59:21.988Z'- updated_at: '2026-04-29T15:59:21.988Z'+ created_at: '2026-04-29T20:30:11.202Z'+ updated_at: '2026-04-29T20:30:11.202Z'meta:page: 1limit: 25@@ -497,10 +442,26 @@ paths:get:summary: Show a customer credit cardtags:- - Customer Credit Cards+ - Customerssecurity:- api_key: []bearer_auth: []+ description: |-+ Returns a saved credit card by ID.++ **Required scope:** `read_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const card = await client.customers.creditCards.get('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -538,15 +499,31 @@ paths:gateway_payment_profile_id:customer_id: cus_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- created_at: '2026-04-29T15:59:22.565Z'- updated_at: '2026-04-29T15:59:22.565Z'+ created_at: '2026-04-29T20:30:11.827Z'+ updated_at: '2026-04-29T20:30:11.827Z'delete:summary: Delete a customer credit cardtags:- - Customer Credit Cards+ - Customerssecurity:- api_key: []bearer_auth: []+ description: |-+ Deletes a saved credit card.++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -575,10 +552,26 @@ paths:get:summary: List customer store creditstags:- - Customer Store Credits+ - Customerssecurity:- api_key: []bearer_auth: []+ description: |-+ Returns store credits issued to the customer.++ **Required scope:** `read_store_credits` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -610,8 +603,8 @@ paths:display_amount_used: "$0.00"display_amount_remaining: "$50.00"currency: USD- created_at: '2026-04-29T15:59:23.961Z'- updated_at: '2026-04-29T15:59:23.961Z'+ created_at: '2026-04-29T20:30:13.224Z'+ updated_at: '2026-04-29T20:30:13.224Z'customer_id: cus_UkLWZg9DAJcreated_by_id: admin_UkLWZg9DAJmetadata:@@ -628,11 +621,31 @@ paths:post:summary: Issue a store credit to a customertags:- - Customer Store Credits+ - Customerssecurity:- api_key: []bearer_auth: []- description: "`created_by` is set automatically from the authenticated admin."+ description: |-+ `created_by` is set automatically from the authenticated admin.++ **Required scope:** `write_store_credits` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {+ amount: 25.00,+ currency: 'USD',+ category_id: 1,+ memo: 'Goodwill credit',+ })parameters:- name: x-spree-api-keyin: header@@ -663,8 +676,8 @@ paths:display_amount_used: "$0.00"display_amount_remaining: "$25.00"currency: USD- created_at: '2026-04-29T15:59:25.093Z'- updated_at: '2026-04-29T15:59:25.093Z'+ created_at: '2026-04-29T20:30:14.367Z'+ updated_at: '2026-04-29T20:30:14.367Z'customer_id: cus_UkLWZg9DAJcreated_by_id: admin_gbHJdmfrXBmetadata:@@ -693,12 +706,30 @@ paths:patch:summary: Update a store credittags:- - Customer Store Credits+ - Customerssecurity:- api_key: []bearer_auth: []- description: Update memo / category / amount. The amount can only be changed- if `amount_used == 0`.+ description: |-+ Update memo / category / amount. The amount can only be changed if `amount_used == 0`.++ **Required scope:** `write_store_credits` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const credit = await client.customers.storeCredits.update(+ 'cus_UkLWZg9DAJ',+ 'sc_UkLWZg9DAJ',+ { memo: 'Reissued for damaged shipment' },+ )parameters:- name: x-spree-api-keyin: header@@ -734,8 +765,8 @@ paths:display_amount_used: "$0.00"display_amount_remaining: "$50.00"currency: USD- created_at: '2026-04-29T15:59:25.639Z'- updated_at: '2026-04-29T15:59:25.927Z'+ created_at: '2026-04-29T20:30:14.904Z'+ updated_at: '2026-04-29T20:30:15.184Z'customer_id: cus_UkLWZg9DAJcreated_by_id: admin_UkLWZg9DAJmetadata:@@ -754,12 +785,26 @@ paths:delete:summary: Delete a store credittags:- - Customer Store Credits+ - Customerssecurity:- api_key: []bearer_auth: []- description: Deletes an unused store credit (amount_used == 0). Returns 422- otherwise.+ description: |-+ Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.++ **Required scope:** `write_store_credits` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -792,7 +837,26 @@ paths:security:- api_key: []bearer_auth: []- description: Returns a paginated list of customers. Supports Ransack search/filters.+ description: |-+ Returns a paginated list of customers. Supports Ransack search/filters.++ **Required scope:** `read_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: customers } = await client.customers.list({+ search: 'jane',+ sort: '-created_at',+ limit: 25,+ })parameters:- name: x-spree-api-keyin: header@@ -840,8 +904,8 @@ paths:login: [email protected]last_sign_in_at:current_sign_in_at:- created_at: '2026-04-29T15:59:27.045Z'- updated_at: '2026-04-29T15:59:27.045Z'+ created_at: '2026-04-29T20:30:16.259Z'+ updated_at: '2026-04-29T20:30:16.259Z'sign_in_count: 0failed_attempts: 0last_sign_in_ip:@@ -872,7 +936,29 @@ paths:security:- api_key: []bearer_auth: []- description: Creates a customer. No welcome email is sent automatically.+ description: |-+ Creates a customer. No welcome email is sent automatically.++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const customer = await client.customers.create({+ email: '[email protected]',+ first_name: 'Jane',+ last_name: 'Doe',+ phone: '+1 212 555 1234',+ tags: ['wholesale'],+ accepts_email_marketing: true,+ })parameters:- name: x-spree-api-keyin: header@@ -902,8 +988,8 @@ paths:login:last_sign_in_at:current_sign_in_at:- created_at: '2026-04-29T15:59:27.893Z'- updated_at: '2026-04-29T15:59:27.893Z'+ created_at: '2026-04-29T20:30:17.089Z'+ updated_at: '2026-04-29T20:30:17.089Z'sign_in_count: 0failed_attempts: 0last_sign_in_ip:@@ -952,8 +1038,24 @@ paths:security:- api_key: []bearer_auth: []- description: Returns full customer details including computed order stats (orders_count,- total_spent, last_order_completed_at).+ description: |-+ Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).++ **Required scope:** `read_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const customer = await client.customers.get('cus_UkLWZg9DAJ', {+ expand: ['addresses', 'store_credits'],+ })parameters:- name: x-spree-api-keyin: header@@ -968,7 +1070,7 @@ paths:- name: idin: pathrequired: true- description: Customer prefixed ID+ description: Customer IDschema:type: string- name: expand@@ -996,8 +1098,8 @@ paths:login: [email protected]last_sign_in_at:current_sign_in_at:- created_at: '2026-04-29T15:59:28.162Z'- updated_at: '2026-04-29T15:59:28.162Z'+ created_at: '2026-04-29T20:30:17.357Z'+ updated_at: '2026-04-29T20:30:17.357Z'sign_in_count: 0failed_attempts: 0last_sign_in_ip:@@ -1018,7 +1120,25 @@ paths:security:- api_key: []bearer_auth: []- description: Updates customer attributes. `tags` replaces the full set.+ description: |-+ Updates customer attributes. `tags` replaces the full set.++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const customer = await client.customers.update('cus_UkLWZg9DAJ', {+ first_name: 'Updated',+ tags: ['wholesale', 'vip'],+ })parameters:- name: x-spree-api-keyin: header@@ -1053,8 +1173,8 @@ paths:login: [email protected]last_sign_in_at:current_sign_in_at:- created_at: '2026-04-29T15:59:28.714Z'- updated_at: '2026-04-29T15:59:28.998Z'+ created_at: '2026-04-29T20:30:17.896Z'+ updated_at: '2026-04-29T20:30:18.172Z'sign_in_count: 0failed_attempts: 0last_sign_in_ip:@@ -1099,7 +1219,22 @@ paths:security:- api_key: []bearer_auth: []- description: Deletes a customer. Returns 422 if the customer has any orders.+ description: |-+ Deletes a customer. Returns 422 if the customer has any orders.++ **Required scope:** `write_customers` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.customers.delete('cus_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1131,18 +1266,18 @@ paths:permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.x-codeSamples:- lang: javascript- label: Spree SDK+ label: Spree Admin SDKsource: |-- import { createClient } from '@spree/sdk'+ import { createAdminClient } from '@spree/admin-sdk'- const client = createClient({+ const client = createAdminClient({baseUrl: 'https://your-store.com',- publishableKey: '<api-key>',+ secretKey: 'sk_xxx',})- const me = await client.admin.me.show()+ const me = await client.me.show()if (me.permissions.some((r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'))) {- // show create product button+ // show "Create product" button}parameters:- name: x-spree-api-key@@ -1164,11 +1299,11 @@ paths:example:user:id: admin_UkLWZg9DAJ- email: [email protected]- first_name: Tanna- last_name: Langosh- created_at: '2026-04-29T15:59:29.836Z'- updated_at: '2026-04-29T15:59:29.836Z'+ email: [email protected]+ first_name: Trudie+ last_name: Braun+ created_at: '2026-04-29T20:30:19.014Z'+ updated_at: '2026-04-29T20:30:19.014Z'permissions:- allow: trueactions:@@ -1237,11 +1372,26 @@ paths:get:summary: List option typestags:- - Option Types+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Returns a paginated list of option types.+ description: |-+ Returns a paginated list of option types.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: optionTypes } = await client.optionTypes.list()parameters:- name: x-spree-api-keyin: header@@ -1284,8 +1434,8 @@ paths:label: Sizeposition: 1kind: dropdown- created_at: '2026-04-29T15:59:29.893Z'- updated_at: '2026-04-29T15:59:29.893Z'+ created_at: '2026-04-29T20:30:19.064Z'+ updated_at: '2026-04-29T20:30:19.064Z'option_values: []meta:page: 1@@ -1322,14 +1472,36 @@ paths:post:summary: Create an option typetags:- - Option Types+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: |+ description: |-Creates a new option type. Supports nested option values.Option values can be provided inline and will be created or updated by name.+++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const optionType = await client.optionTypes.create({+ name: 'color',+ presentation: 'Color',+ option_values: [+ { name: 'red', presentation: 'Red' },+ { name: 'navy', presentation: 'Navy' },+ ],+ })parameters:- name: x-spree-api-keyin: header@@ -1353,8 +1525,8 @@ paths:label: Materialposition: 2kind: dropdown- created_at: '2026-04-29T15:59:30.475Z'- updated_at: '2026-04-29T15:59:30.475Z'+ created_at: '2026-04-29T20:30:19.633Z'+ updated_at: '2026-04-29T20:30:19.633Z'option_values: []schema:"$ref": "#/components/schemas/OptionType"@@ -1411,12 +1583,26 @@ paths:get:summary: Get an option typetags:- - Option Types+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Returns a single option type by prefixed ID, including its option- values.+ description: |-+ Returns a single option type by ID, including its option values.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const optionType = await client.optionTypes.get('ot_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1432,7 +1618,7 @@ paths:- name: idin: pathrequired: true- description: Option type prefixed ID+ description: Option type IDschema:type: stringresponses:@@ -1446,8 +1632,8 @@ paths:label: Sizeposition: 1kind: dropdown- created_at: '2026-04-29T15:59:30.761Z'- updated_at: '2026-04-29T15:59:30.761Z'+ created_at: '2026-04-29T20:30:19.915Z'+ updated_at: '2026-04-29T20:30:19.915Z'option_values: []schema:"$ref": "#/components/schemas/OptionType"@@ -1464,11 +1650,31 @@ paths:patch:summary: Update an option typetags:- - Option Types+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Updates an option type. Supports updating nested option values.+ description: |-+ Updates an option type. Supports updating nested option values.++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const optionType = await client.optionTypes.update('ot_UkLWZg9DAJ', {+ presentation: 'Updated Presentation',+ option_values: [+ { name: 'red', presentation: 'Crimson' },+ ],+ })parameters:- name: x-spree-api-keyin: header@@ -1484,7 +1690,7 @@ paths:- name: idin: pathrequired: true- description: Option type prefixed ID+ description: Option type IDschema:type: stringresponses:@@ -1498,8 +1704,8 @@ paths:label: Updated Presentationposition: 1kind: dropdown- created_at: '2026-04-29T15:59:31.333Z'- updated_at: '2026-04-29T15:59:31.616Z'+ created_at: '2026-04-29T20:30:20.489Z'+ updated_at: '2026-04-29T20:30:20.765Z'option_values: []schema:"$ref": "#/components/schemas/OptionType"@@ -1553,11 +1759,26 @@ paths:delete:summary: Delete an option typetags:- - Option Types+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Deletes an option type.+ description: |-+ Deletes an option type.++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.optionTypes.delete('ot_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1573,7 +1794,7 @@ paths:- name: idin: pathrequired: true- description: Option type prefixed ID+ description: Option type IDschema:type: stringresponses:@@ -1583,11 +1804,26 @@ paths:get:summary: List fulfillmentstags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Returns all shipments for an order.+ description: |-+ Returns all shipments for an order.++ **Required scope:** `read_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: fulfillments } = await client.orders.fulfillments.list('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1603,7 +1839,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -1614,7 +1850,7 @@ paths:example:data:- id: ful_UkLWZg9DAJ- number: H14880110860+ number: H58964048011tracking: U10000tracking_url:cost: '10.0'@@ -1638,8 +1874,8 @@ paths:quantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:33.758Z'- updated_at: '2026-04-29T15:59:33.861Z'+ created_at: '2026-04-29T20:30:21.685Z'+ updated_at: '2026-04-29T20:30:21.773Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -1657,11 +1893,26 @@ paths:get:summary: Show a shipmenttags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Returns details of a specific shipment.+ description: |-+ Returns details of a specific shipment.++ **Required scope:** `read_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1677,13 +1928,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment prefixed ID+ description: Fulfillment IDschema:type: stringresponses:@@ -1693,7 +1944,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H46462677784+ number: H22756559934tracking: U10000tracking_url:cost: '10.0'@@ -1717,19 +1968,36 @@ paths:quantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:34.478Z'- updated_at: '2026-04-29T15:59:34.550Z'+ created_at: '2026-04-29T20:30:22.372Z'+ updated_at: '2026-04-29T20:30:22.437Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJpatch:summary: Update a shipmenttags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Updates a shipment (tracking, shipping rate).+ description: |-+ Updates a shipment (tracking, shipping rate).++ **Required scope:** `write_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {+ tracking: '1Z999AA10123456784',+ })parameters:- name: x-spree-api-keyin: header@@ -1745,13 +2013,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment prefixed ID+ description: Fulfillment IDschema:type: stringresponses:@@ -1761,7 +2029,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H29909540755+ number: H99332454701tracking: 1Z999AA10123456784tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784cost: '10.0'@@ -1785,8 +2053,8 @@ paths:quantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:35.211Z'- updated_at: '2026-04-29T15:59:35.647Z'+ created_at: '2026-04-29T20:30:23.033Z'+ updated_at: '2026-04-29T20:30:23.367Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -1805,11 +2073,26 @@ paths:patch:summary: Fulfill a fulfillmenttags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Marks a fulfillment as fulfilled.+ description: |-+ Marks a fulfillment as fulfilled.++ **Required scope:** `write_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1825,13 +2108,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment prefixed ID+ description: Fulfillment IDschema:type: stringresponses:@@ -1841,7 +2124,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H49727928395+ number: H38654634498tracking: U10000tracking_url:cost: '10.0'@@ -1858,15 +2141,15 @@ paths:display_tax_total: "$0.00"status: shippedfulfillment_type: shipping- fulfilled_at: '2026-04-29T15:59:36Z'+ fulfilled_at: '2026-04-29T20:30:24Z'items:- item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJquantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:35.985Z'- updated_at: '2026-04-29T15:59:36.352Z'+ created_at: '2026-04-29T20:30:23.676Z'+ updated_at: '2026-04-29T20:30:24.061Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -1874,11 +2157,26 @@ paths:patch:summary: Cancel a fulfillmenttags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Cancels a fulfillment.+ description: |-+ Cancels a fulfillment.++ **Required scope:** `write_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1894,13 +2192,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment prefixed ID+ description: Fulfillment IDschema:type: stringresponses:@@ -1910,7 +2208,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H74143874830+ number: H94038749002tracking: U10000tracking_url:cost: '10.0'@@ -1934,8 +2232,8 @@ paths:quantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:36.678Z'- updated_at: '2026-04-29T15:59:37.029Z'+ created_at: '2026-04-29T20:30:24.409Z'+ updated_at: '2026-04-29T20:30:24.750Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -1943,11 +2241,26 @@ paths:patch:summary: Resume a fulfillmenttags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Resumes a canceled fulfillment.+ description: |-+ Resumes a canceled fulfillment.++ **Required scope:** `write_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const fulfillment = await client.orders.fulfillments.resume('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -1963,13 +2276,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment prefixed ID+ description: Fulfillment IDschema:type: stringresponses:@@ -1979,7 +2292,7 @@ paths:application/json:example:id: ful_UkLWZg9DAJ- number: H62532514472+ number: H93270023954tracking: U10000tracking_url:cost: '10.0'@@ -2003,8 +2316,8 @@ paths:quantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:37.367Z'- updated_at: '2026-04-29T15:59:37.764Z'+ created_at: '2026-04-29T20:30:25.071Z'+ updated_at: '2026-04-29T20:30:25.411Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_UkLWZg9DAJ@@ -2012,12 +2325,28 @@ paths:patch:summary: Split a fulfillmenttags:- - Fulfillments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Transfers items from this shipment to a new shipment at a different- stock location.+ description: |-+ Transfers items from this shipment to a new shipment at a different stock location.++ **Required scope:** `write_fulfillments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const fulfillment = await client.orders.fulfillments.split('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {+ quantity: 1,+ })parameters:- name: x-spree-api-keyin: header@@ -2033,13 +2362,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment prefixed ID+ description: Fulfillment IDschema:type: stringresponses:@@ -2050,7 +2379,7 @@ paths:example:data:- id: ful_gbHJdmfrXB- number: H36302623231+ number: H19670751184tracking:tracking_url:cost: '10.0'@@ -2074,8 +2403,8 @@ paths:quantity: 1adjustment_total: '0.0'pre_tax_amount: '0.0'- created_at: '2026-04-29T15:59:38.473Z'- updated_at: '2026-04-29T15:59:38.527Z'+ created_at: '2026-04-29T20:30:26.080Z'+ updated_at: '2026-04-29T20:30:26.120Z'metadata:order_id: or_UkLWZg9DAJstock_location_id: sloc_gbHJdmfrXB@@ -2090,22 +2419,39 @@ paths:properties:variant_id:type: string- description: Variant prefixed ID+ description: Variant IDquantity:type: integerexample: 1stock_location_id:type: string- description: Target stock location prefixed ID+ description: Target stock location ID"/api/v3/admin/orders/{order_id}/gift_cards":post:summary: Apply a gift card to an ordertags:- - Order Gift Cards+ - Orderssecurity:- api_key: []bearer_auth: []- description: Applies a gift card by code to the order. Returns the gift card.+ description: |-+ Applies a gift card by code to the order. Returns the gift card.++ **Required scope:** `write_gift_cards` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.giftCards.apply('or_UkLWZg9DAJ', {+ code: 'GIFT-XXXX-YYYY',+ })parameters:- name: x-spree-api-keyin: header@@ -2121,7 +2467,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -2131,7 +2477,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: A95638B047300283+ code: DC3C210CF25AFB8Bstatus: activecurrency: USDamount: '10.0'@@ -2145,8 +2491,8 @@ paths:redeemed_at:expired: falseactive: true- created_at: '2026-04-29T15:59:38.888Z'- updated_at: '2026-04-29T15:59:39.196Z'+ created_at: '2026-04-29T20:30:26.449Z'+ updated_at: '2026-04-29T20:30:26.740Z'requestBody:content:application/json:@@ -2163,11 +2509,26 @@ paths:delete:summary: Remove a gift card from an ordertags:- - Order Gift Cards+ - Orderssecurity:- api_key: []bearer_auth: []- description: Removes the gift card from the order.+ description: |-+ Removes the gift card from the order.++ **Required scope:** `write_gift_cards` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2183,13 +2544,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Gift card prefixed ID+ description: Gift card IDschema:type: stringresponses:@@ -2203,7 +2564,22 @@ paths:security:- api_key: []bearer_auth: []- description: Returns all line items for an order.+ description: |-+ Returns all line items for an order.++ **Required scope:** `read_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2219,7 +2595,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -2233,8 +2609,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 2currency: USD- name: Product 108448- slug: product-108448+ name: Product 105279+ slug: product-105279options_text: 'Size: S'price: '10.0'display_price: "$10.00"@@ -2265,11 +2641,11 @@ paths:option_type_name: foo-size-10option_type_label: Sizeimage_url:- created_at: '2026-04-29T15:59:39.910Z'- updated_at: '2026-04-29T15:59:39.910Z'+ created_at: '2026-04-29T20:30:27.413Z'+ updated_at: '2026-04-29T20:30:27.413Z'digital_links: []- created_at: '2026-04-29T15:59:40.201Z'- updated_at: '2026-04-29T15:59:40.201Z'+ created_at: '2026-04-29T20:30:27.700Z'+ updated_at: '2026-04-29T20:30:27.700Z'metadata:cost_price: '17.0'tax_category_id: taxcat_UkLWZg9DAJ@@ -2290,7 +2666,25 @@ paths:security:- api_key: []bearer_auth: []- description: Adds a new line item to the order.+ description: |-+ Adds a new line item to the order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const item = await client.orders.items.create('or_UkLWZg9DAJ', {+ variant_id: 'variant_k5nR8xLq',+ quantity: 2,+ })parameters:- name: x-spree-api-keyin: header@@ -2306,7 +2700,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -2319,8 +2713,8 @@ paths:variant_id: variant_VqXmZF31wYquantity: 3currency: USD- name: Product 125274- slug: product-125274+ name: Product 125508+ slug: product-125508options_text: 'Size: S'price: '19.99'display_price: "$19.99"@@ -2351,11 +2745,11 @@ paths:option_type_name: foo-size-12option_type_label: Sizeimage_url:- created_at: '2026-04-29T15:59:41.140Z'- updated_at: '2026-04-29T15:59:41.140Z'+ created_at: '2026-04-29T20:30:28.609Z'+ updated_at: '2026-04-29T20:30:28.609Z'digital_links: []- created_at: '2026-04-29T15:59:41.167Z'- updated_at: '2026-04-29T15:59:41.167Z'+ created_at: '2026-04-29T20:30:28.637Z'+ updated_at: '2026-04-29T20:30:28.637Z'metadata:cost_price: '17.0'tax_category_id: taxcat_UkLWZg9DAJ@@ -2381,7 +2775,22 @@ paths:security:- api_key: []bearer_auth: []- description: Returns details of a specific line item.+ description: |-+ Returns details of a specific line item.++ **Required scope:** `read_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2397,13 +2806,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Item prefixed ID+ description: Item IDschema:type: stringresponses:@@ -2416,8 +2825,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 2currency: USD- name: Product 131748- slug: product-131748+ name: Product 132818+ slug: product-132818options_text: 'Size: S'price: '10.0'display_price: "$10.00"@@ -2448,11 +2857,11 @@ paths:option_type_name: foo-size-13option_type_label: Sizeimage_url:- created_at: '2026-04-29T15:59:41.249Z'- updated_at: '2026-04-29T15:59:41.249Z'+ created_at: '2026-04-29T20:30:28.700Z'+ updated_at: '2026-04-29T20:30:28.700Z'digital_links: []- created_at: '2026-04-29T15:59:41.542Z'- updated_at: '2026-04-29T15:59:41.542Z'+ created_at: '2026-04-29T20:30:28.983Z'+ updated_at: '2026-04-29T20:30:28.983Z'metadata:cost_price: '17.0'tax_category_id: taxcat_UkLWZg9DAJ@@ -2463,7 +2872,24 @@ paths:security:- api_key: []bearer_auth: []- description: Updates an order item quantity or metadata.+ description: |-+ Updates an order item quantity or metadata.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {+ quantity: 5,+ })parameters:- name: x-spree-api-keyin: header@@ -2479,13 +2905,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Item prefixed ID+ description: Item IDschema:type: stringresponses:@@ -2498,8 +2924,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 5currency: USD- name: Product 149920- slug: product-149920+ name: Product 141614+ slug: product-141614options_text: 'Size: S'price: '19.99'display_price: "$19.99"@@ -2530,11 +2956,11 @@ paths:option_type_name: foo-size-14option_type_label: Sizeimage_url:- created_at: '2026-04-29T15:59:41.881Z'- updated_at: '2026-04-29T15:59:41.881Z'+ created_at: '2026-04-29T20:30:29.298Z'+ updated_at: '2026-04-29T20:30:29.298Z'digital_links: []- created_at: '2026-04-29T15:59:42.171Z'- updated_at: '2026-04-29T15:59:42.475Z'+ created_at: '2026-04-29T20:30:29.579Z'+ updated_at: '2026-04-29T20:30:29.882Z'metadata:cost_price: '17.0'tax_category_id: taxcat_UkLWZg9DAJ@@ -2553,7 +2979,22 @@ paths:security:- api_key: []bearer_auth: []- description: Removes an item from the order.+ description: |-+ Removes an item from the order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2569,13 +3010,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Item prefixed ID+ description: Item IDschema:type: stringresponses:@@ -2585,11 +3026,26 @@ paths:get:summary: List paymentstags:- - Payments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Returns all payments for an order.+ description: |-+ Returns all payments for an order.++ **Required scope:** `read_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2605,7 +3061,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -2617,8 +3073,8 @@ paths:data:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-54a70c52b21d- number: PLAV8NZY+ response_code: BGS-cd10ecf5ca24+ number: P2ASUUCUamount: '110.0'display_amount: "$110.00"status: completed@@ -2635,13 +3091,13 @@ paths:gateway_payment_profile_id:customer_id:payment_method_id: pm_gbHJdmfrXB- created_at: '2026-04-29T15:59:43.586Z'- updated_at: '2026-04-29T15:59:43.589Z'+ created_at: '2026-04-29T20:30:30.844Z'+ updated_at: '2026-04-29T20:30:30.846Z'avs_response:cvv_response_code:cvv_response_message:- created_at: '2026-04-29T15:59:43.588Z'- updated_at: '2026-04-29T15:59:43.588Z'+ created_at: '2026-04-29T20:30:30.845Z'+ updated_at: '2026-04-29T20:30:30.845Z'metadata:captured_amount: '0.0'order_id: or_UkLWZg9DAJ@@ -2658,11 +3114,30 @@ paths:post:summary: Create a paymenttags:- - Payments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Creates a new payment for the order.+ description: |-+ Creates a new payment for the order.++ **Required scope:** `write_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const payment = await client.orders.payments.create('or_UkLWZg9DAJ', {+ payment_method_id: 'pm_UkLWZg9DAJ',+ amount: 99.99,+ source_id: 'cc_UkLWZg9DAJ',+ })parameters:- name: x-spree-api-keyin: header@@ -2678,7 +3153,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -2690,7 +3165,7 @@ paths:id: py_gbHJdmfrXBpayment_method_id: pm_EfhxLZ9ck8response_code:- number: PTVQ79F2+ number: PBXFIEHJamount: '110.0'display_amount: "$110.00"status: checkout@@ -2700,8 +3175,8 @@ paths:avs_response:cvv_response_code:cvv_response_message:- created_at: '2026-04-29T15:59:45.006Z'- updated_at: '2026-04-29T15:59:45.006Z'+ created_at: '2026-04-29T20:30:32.198Z'+ updated_at: '2026-04-29T20:30:32.198Z'metadata:captured_amount: '0.0'order_id: or_gbHJdmfrXB@@ -2715,22 +3190,37 @@ paths:properties:payment_method_id:type: string- description: Payment method prefixed ID+ description: Payment method IDamount:type: numberexample: 99.99source_id:type: string- description: Payment source prefixed ID+ description: Payment source ID"/api/v3/admin/orders/{order_id}/payments/{id}":get:summary: Show a paymenttags:- - Payments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Returns details of a specific payment.+ description: |-+ Returns details of a specific payment.++ **Required scope:** `read_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2746,13 +3236,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Payment prefixed ID+ description: Payment IDschema:type: stringresponses:@@ -2763,8 +3253,8 @@ paths:example:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-836f5fa9863f- number: P86A9S9N+ response_code: BGS-c35e9c968ee9+ number: PN5BGX24amount: '110.0'display_amount: "$110.00"status: completed@@ -2781,13 +3271,13 @@ paths:gateway_payment_profile_id:customer_id:payment_method_id: pm_gbHJdmfrXB- created_at: '2026-04-29T15:59:45.398Z'- updated_at: '2026-04-29T15:59:45.401Z'+ created_at: '2026-04-29T20:30:32.565Z'+ updated_at: '2026-04-29T20:30:32.568Z'avs_response:cvv_response_code:cvv_response_message:- created_at: '2026-04-29T15:59:45.400Z'- updated_at: '2026-04-29T15:59:45.400Z'+ created_at: '2026-04-29T20:30:32.567Z'+ updated_at: '2026-04-29T20:30:32.567Z'metadata:captured_amount: '0.0'order_id: or_UkLWZg9DAJ@@ -2795,11 +3285,26 @@ paths:patch:summary: Capture a paymenttags:- - Payments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Captures a pending payment.+ description: |-+ Captures a pending payment.++ **Required scope:** `write_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2815,13 +3320,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Payment prefixed ID+ description: Payment IDschema:type: stringresponses:@@ -2832,8 +3337,8 @@ paths:example:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-43f1ba4bb781- number: PZSM7VMD+ response_code: BGS-83fa93309f40+ number: PLRGMP0Uamount: '110.0'display_amount: "$110.00"status: completed@@ -2850,13 +3355,13 @@ paths:gateway_payment_profile_id:customer_id:payment_method_id: pm_gbHJdmfrXB- created_at: '2026-04-29T15:59:46.099Z'- updated_at: '2026-04-29T15:59:46.103Z'+ created_at: '2026-04-29T20:30:33.202Z'+ updated_at: '2026-04-29T20:30:33.204Z'avs_response:cvv_response_code:cvv_response_message:- created_at: '2026-04-29T15:59:46.101Z'- updated_at: '2026-04-29T15:59:46.450Z'+ created_at: '2026-04-29T20:30:33.204Z'+ updated_at: '2026-04-29T20:30:33.538Z'metadata:captured_amount: '110.0'order_id: or_UkLWZg9DAJ@@ -2864,11 +3369,26 @@ paths:patch:summary: Void a paymenttags:- - Payments+ - Orderssecurity:- api_key: []bearer_auth: []- description: Voids a payment.+ description: |-+ Voids a payment.++ **Required scope:** `write_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2884,13 +3404,13 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: string- name: idin: pathrequired: true- description: Payment prefixed ID+ description: Payment IDschema:type: stringresponses:@@ -2901,8 +3421,8 @@ paths:example:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: void-BGS-c568f8768169- number: PMY7I4KL+ response_code: void-BGS-be7e856c9089+ number: P02ZEG5Mamount: '110.0'display_amount: "$110.00"status: void@@ -2919,13 +3439,13 @@ paths:gateway_payment_profile_id:customer_id:payment_method_id: pm_gbHJdmfrXB- created_at: '2026-04-29T15:59:46.860Z'- updated_at: '2026-04-29T15:59:46.863Z'+ created_at: '2026-04-29T20:30:33.902Z'+ updated_at: '2026-04-29T20:30:33.904Z'avs_response:cvv_response_code:cvv_response_message:- created_at: '2026-04-29T15:59:46.862Z'- updated_at: '2026-04-29T15:59:47.173Z'+ created_at: '2026-04-29T20:30:33.903Z'+ updated_at: '2026-04-29T20:30:34.201Z'metadata:captured_amount: '0.0'order_id: or_UkLWZg9DAJ@@ -2933,11 +3453,26 @@ paths:get:summary: List refundstags:- - Refunds+ - Orderssecurity:- api_key: []bearer_auth: []- description: Returns all refunds for an order.+ description: |-+ Returns all refunds for an order.++ **Required scope:** `read_refunds` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: refunds } = await client.orders.refunds.list('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -2953,7 +3488,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -2976,12 +3511,30 @@ paths:post:summary: Create a refundtags:- - Refunds+ - Orderssecurity:- api_key: []bearer_auth: []- description: Creates a refund for a payment on the order. The refund is automatically- processed via the payment gateway.+ description: |-+ Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.++ **Required scope:** `write_refunds` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {+ payment_id: 'pay_UkLWZg9DAJ',+ amount: 5.00,+ refund_reason_id: 'refrsn_UkLWZg9DAJ',+ })parameters:- name: x-spree-api-keyin: header@@ -2997,7 +3550,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3007,13 +3560,13 @@ paths:application/json:example:id: re_UkLWZg9DAJ- transaction_id: BGS-b4d7d858bbe3+ transaction_id: BGS-6814308937daamount: '5.0'payment_id: py_UkLWZg9DAJrefund_reason_id: rr_UkLWZg9DAJreimbursement_id:- created_at: '2026-04-29T15:59:48.631Z'- updated_at: '2026-04-29T15:59:48.631Z'+ created_at: '2026-04-29T20:30:35.526Z'+ updated_at: '2026-04-29T20:30:35.526Z'requestBody:content:application/json:@@ -3025,23 +3578,39 @@ paths:properties:payment_id:type: string- description: Payment prefixed ID+ description: Payment IDamount:type: numberexample: 10.0refund_reason_id:type: string- description: Refund reason prefixed ID+ description: Refund reason ID"/api/v3/admin/orders/{order_id}/store_credits":post:summary: Apply customer's store credit to an ordertags:- - Order Store Credits+ - Orderssecurity:- api_key: []bearer_auth: []- description: Applies the order customer's available store credit. When `amount`- is omitted, applies up to the order outstanding balance.+ description: |-+ Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.++ **Required scope:** `write_store_credits` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {+ amount: 25.00,+ })parameters:- name: x-spree-api-keyin: header@@ -3057,7 +3626,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3068,8 +3637,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R313817073- email: [email protected]+ number: R524252096+ email: [email protected]customer_note:currency: USDlocale: en@@ -3111,8 +3680,8 @@ paths:display_payment_total: "$0.00"canceled_at:approved_at:- created_at: '2026-04-29T15:59:48.938Z'- updated_at: '2026-04-29T15:59:49.003Z'+ created_at: '2026-04-29T20:30:35.821Z'+ updated_at: '2026-04-29T20:30:35.871Z'tags: []internal_note:metadata:@@ -3133,11 +3702,26 @@ paths:delete:summary: Remove store credit from an ordertags:- - Order Store Credits+ - Orderssecurity:- api_key: []bearer_auth: []- description: Removes any applied store credit from the order.+ description: |-+ Removes any applied store credit from the order.++ **Required scope:** `write_store_credits` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.storeCredits.remove('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -3153,7 +3737,7 @@ paths:- name: order_idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3167,7 +3751,27 @@ paths:security:- api_key: []bearer_auth: []- description: Returns a paginated list of orders for the current store.+ description: |-+ Returns a paginated list of orders for the current store.++ **Required scope:** `read_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: orders, meta } = await client.orders.list({+ status_eq: 'complete',+ completed_at_gt: '2026-01-01',+ sort: '-completed_at',+ limit: 25,+ })parameters:- name: x-spree-api-keyin: header@@ -3232,8 +3836,8 @@ paths:data:- id: or_UkLWZg9DAJmarket_id:- number: R488598395- email: [email protected]+ number: R822015417+ email: [email protected]customer_note:currency: USDlocale: en@@ -3275,8 +3879,8 @@ paths:display_payment_total: "$0.00"canceled_at:approved_at:- created_at: '2026-04-29T15:59:50.803Z'- updated_at: '2026-04-29T15:59:50.803Z'+ created_at: '2026-04-29T20:30:37.594Z'+ updated_at: '2026-04-29T20:30:37.594Z'tags: []internal_note:metadata:@@ -3311,12 +3915,81 @@ paths:security:- api_key: []bearer_auth: []- description: |+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ // One-shot order create: customer, items, addresses, market, notes,+ // metadata, and a coupon code in a single call. Everything except+ // `email` is optional.+ const order = await client.orders.create({+ email: '[email protected]',+ customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders+ use_customer_default_address: false, // true to copy the customer's saved addresses++ currency: 'USD',+ market_id: 'mkt_UkLWZg9DAJ',+ locale: 'en-US',++ customer_note: 'Please leave at the front desk.',+ internal_note: 'VIP customer — handle with care.',+ metadata: {+ external_reference: 'subscription_invoice_2026_04',+ source: 'recurring-engine',+ },++ // Items: each variant_id + quantity. Optional metadata per line.+ items: [+ { variant_id: 'variant_k5nR8xLq', quantity: 2 },+ { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },+ ],++ // Provide addresses inline OR by ID (existing customer addresses).+ shipping_address: {+ first_name: 'Jane',+ last_name: 'Doe',+ address1: '350 Fifth Avenue',+ address2: 'Floor 42',+ city: 'New York',+ postal_code: '10118',+ country_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ company: 'Acme Inc.',+ },+ // shipping_address_id: 'addr_UkLWZg9DAJ', // alternative to inline++ billing_address: {+ first_name: 'Jane',+ last_name: 'Doe',+ address1: '350 Fifth Avenue',+ city: 'New York',+ postal_code: '10118',+ country_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ },+ // billing_address_id: 'addr_UkLWZg9DAJ',++ // Optional. Invalid codes are non-fatal — the order is created either way.+ coupon_code: 'WELCOME10',+ })+ description: |-Creates a new draft order in one shot. Customer, items, addresses, currency,market, locale, notes, metadata, and a coupon code can all be provided inline.Invalid coupon codes are non-fatal — the order is created and the failureis reported on the service result (not in the API response body for now).+++ **Required scope:** `write_orders` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -3337,7 +4010,7 @@ paths:example:id: or_gbHJdmfrXBmarket_id:- number: R032689850+ number: R287865458email: [email protected]customer_note:currency: USD@@ -3380,8 +4053,8 @@ paths:display_payment_total: "$0.00"canceled_at:approved_at:- created_at: '2026-04-29T15:59:51.934Z'- updated_at: '2026-04-29T15:59:51.934Z'+ created_at: '2026-04-29T20:30:38.707Z'+ updated_at: '2026-04-29T20:30:38.707Z'tags: []internal_note:metadata:@@ -3400,7 +4073,7 @@ paths:example: [email protected]customer_id:type: string- description: 'Customer prefixed ID. Alias: user_id (legacy).'+ description: 'Customer ID. Alias: user_id (legacy).'use_customer_default_address:type: booleandescription: When true with customer_id, copies the customer's saved@@ -3410,7 +4083,7 @@ paths:example: USDmarket_id:type: string- description: Market prefixed ID+ description: Market IDlocale:type: stringexample: en-US@@ -3444,7 +4117,7 @@ paths:type: stringshipping_address_id:type: string- description: Existing customer address prefixed ID+ description: Existing customer address IDbilling_address:type: objectproperties:@@ -3466,7 +4139,7 @@ paths:type: stringbilling_address_id:type: string- description: Existing customer address prefixed ID+ description: Existing customer address IDitems:type: arrayitems:@@ -3477,7 +4150,7 @@ paths:properties:variant_id:type: string- description: Variant prefixed ID+ description: Variant IDquantity:type: integerexample: 1@@ -3495,7 +4168,24 @@ paths:security:- api_key: []bearer_auth: []- description: Returns full order details including admin-only fields.+ description: |-+ Returns full order details including admin-only fields.++ **Required scope:** `read_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.get('or_UkLWZg9DAJ', {+ expand: ['items', 'fulfillments', 'payments', 'customer'],+ })parameters:- name: x-spree-api-keyin: header@@ -3511,7 +4201,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID (e.g., or_xxx)+ description: Order ID (e.g., or_xxx)schema:type: string- name: expand@@ -3528,8 +4218,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R785858912- email: [email protected]+ number: R049254058+ email: [email protected]customer_note:currency: USDlocale: en@@ -3571,8 +4261,8 @@ paths:display_payment_total: "$0.00"canceled_at:approved_at:- created_at: '2026-04-29T15:59:52.213Z'- updated_at: '2026-04-29T15:59:52.213Z'+ created_at: '2026-04-29T20:30:38.983Z'+ updated_at: '2026-04-29T20:30:38.983Z'tags: []internal_note:metadata:@@ -3597,8 +4287,25 @@ paths:security:- api_key: []bearer_auth: []- description: Updates an order. Supports updating email, addresses, special instructions,- and line items.+ description: |-+ Updates an order. Supports updating email, addresses, special instructions, and line items.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.update('or_UkLWZg9DAJ', {+ email: '[email protected]',+ internal_note: 'VIP — gift wrap on next order',+ })parameters:- name: x-spree-api-keyin: header@@ -3614,7 +4321,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3625,7 +4332,7 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R277507018+ number: R515145022email: [email protected]customer_note:currency: USD@@ -3668,8 +4375,8 @@ paths:display_payment_total: "$0.00"canceled_at:approved_at:- created_at: '2026-04-29T15:59:53.337Z'- updated_at: '2026-04-29T15:59:53.623Z'+ created_at: '2026-04-29T20:30:40.077Z'+ updated_at: '2026-04-29T20:30:40.360Z'tags: []internal_note:metadata:@@ -3736,7 +4443,7 @@ paths:properties:variant_id:type: string- description: Variant prefixed ID+ description: Variant IDquantity:type: integerexample: 1@@ -3749,7 +4456,22 @@ paths:security:- api_key: []bearer_auth: []- description: Deletes a draft order. Completed orders cannot be deleted.+ description: |-+ Deletes a draft order. Completed orders cannot be deleted.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.delete('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -3765,7 +4487,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3779,7 +4501,22 @@ paths:security:- api_key: []bearer_auth: []- description: Cancels a completed order.+ description: |-+ Cancels a completed order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.cancel('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -3795,7 +4532,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3806,8 +4543,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R094301972- email: [email protected]+ number: R756472256+ email: [email protected]customer_note:currency: USDlocale: en@@ -3834,7 +4571,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: canceledpayment_status: void- completed_at: '2026-04-29T15:59:54.558Z'+ completed_at: '2026-04-29T20:30:41.353Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -3847,10 +4584,10 @@ paths:store_owner_notification_delivered:payment_total: '0.0'display_payment_total: "$0.00"- canceled_at: '2026-04-29T15:59:54.857Z'+ canceled_at: '2026-04-29T20:30:41.657Z'approved_at:- created_at: '2026-04-29T15:59:54.492Z'- updated_at: '2026-04-29T15:59:54.904Z'+ created_at: '2026-04-29T20:30:41.258Z'+ updated_at: '2026-04-29T20:30:41.701Z'tags: []internal_note:metadata:@@ -3866,7 +4603,22 @@ paths:security:- api_key: []bearer_auth: []- description: Approves an order (e.g., for fraud review).+ description: |-+ Approves an order (e.g., for fraud review).++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.approve('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -3882,7 +4634,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3893,8 +4645,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R143148128- email: [email protected]+ number: R788972238+ email: [email protected]customer_note:currency: USDlocale: en@@ -3921,7 +4673,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-04-29T15:59:55.252Z'+ completed_at: '2026-04-29T20:30:42.044Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -3935,9 +4687,9 @@ paths:payment_total: '0.0'display_payment_total: "$0.00"canceled_at:- approved_at: '2026-04-29T15:59:55.541Z'- created_at: '2026-04-29T15:59:55.202Z'- updated_at: '2026-04-29T15:59:55.251Z'+ approved_at: '2026-04-29T20:30:42.330Z'+ created_at: '2026-04-29T20:30:41.992Z'+ updated_at: '2026-04-29T20:30:42.043Z'tags: []internal_note:metadata:@@ -3953,7 +4705,22 @@ paths:security:- api_key: []bearer_auth: []- description: Resumes a previously canceled order.+ description: |-+ Resumes a previously canceled order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.resume('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -3969,7 +4736,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -3980,8 +4747,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R889473296- email: [email protected]+ number: R436308444+ email: [email protected]customer_note:currency: USDlocale: en@@ -4008,7 +4775,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: canceledpayment_status: void- completed_at: '2026-04-29T15:59:55.893Z'+ completed_at: '2026-04-29T20:30:42.658Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -4021,10 +4788,10 @@ paths:store_owner_notification_delivered:payment_total: '0.0'display_payment_total: "$0.00"- canceled_at: '2026-04-29T15:59:56.173Z'+ canceled_at: '2026-04-29T20:30:42.934Z'approved_at:- created_at: '2026-04-29T15:59:55.837Z'- updated_at: '2026-04-29T15:59:56.280Z'+ created_at: '2026-04-29T20:30:42.609Z'+ updated_at: '2026-04-29T20:30:43.011Z'tags: []internal_note:metadata:@@ -4040,8 +4807,22 @@ paths:security:- api_key: []bearer_auth: []- description: Publishes the order.completed event to trigger confirmation email- delivery.+ description: |-+ Publishes the order.completed event to trigger confirmation email delivery.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.resendConfirmation('or_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -4057,7 +4838,7 @@ paths:- name: idin: pathrequired: true- description: Order prefixed ID+ description: Order IDschema:type: stringresponses:@@ -4068,8 +4849,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R880168377- email: [email protected]+ number: R732371039+ email: [email protected]customer_note:currency: USDlocale: en@@ -4096,7 +4877,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-04-29T15:59:56.626Z'+ completed_at: '2026-04-29T20:30:43.350Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -4111,8 +4892,8 @@ paths:display_payment_total: "$0.00"canceled_at:approved_at:- created_at: '2026-04-29T15:59:56.568Z'- updated_at: '2026-04-29T15:59:56.626Z'+ created_at: '2026-04-29T20:30:43.296Z'+ updated_at: '2026-04-29T20:30:43.350Z'tags: []internal_note:metadata:@@ -4124,12 +4905,26 @@ paths:get:summary: List payment methodstags:- - Payment Methods+ - Configurationsecurity:- api_key: []bearer_auth: []- description: 'Returns the store''s configured payment methods. Use `source_required:- true` to know which methods need a saved source.'+ description: |-+ Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.++ **Required scope:** `read_settings` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: paymentMethods } = await client.paymentMethods.list()parameters:- name: x-spree-api-keyin: header@@ -4156,8 +4951,8 @@ paths:source_required: falseactive: trueauto_capture:- created_at: '2026-04-29T15:59:56.924Z'- updated_at: '2026-04-29T15:59:56.925Z'+ created_at: '2026-04-29T20:30:43.650Z'+ updated_at: '2026-04-29T20:30:43.651Z'meta:page: 1limit: 25@@ -4172,10 +4967,26 @@ paths:get:summary: Show a payment methodtags:- - Payment Methods+ - Configurationsecurity:- api_key: []bearer_auth: []+ description: |-+ Returns a payment method by ID.++ **Required scope:** `read_settings` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')parameters:- name: x-spree-api-keyin: header@@ -4206,17 +5017,37 @@ paths:source_required: falseactive: trueauto_capture:- created_at: '2026-04-29T15:59:57.207Z'- updated_at: '2026-04-29T15:59:57.208Z'+ created_at: '2026-04-29T20:30:43.933Z'+ updated_at: '2026-04-29T20:30:43.935Z'"/api/v3/admin/products":get:summary: List productstags:- - Products+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Returns a paginated list of products for the current store.+ description: |-+ Returns a paginated list of products for the current store.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: products } = await client.products.list({+ name_cont: 'shirt',+ status_eq: 'active',+ sort: '-created_at',+ limit: 25,+ })parameters:- name: x-spree-api-keyin: header@@ -4273,35 +5104,25 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 351940- slug: product-351940+ name: Product 309712+ slug: product-309712meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-29T15:59:59.242Z'+ available_on: '2025-04-29T20:30:44.214Z'purchasable: truein_stock: falsebackorderable: trueavailable: true- description: A ipsum vitae iusto laborum corrupti tenetur ex quaerat.- Repellendus architecto tempora cupiditate quisquam dignissimos- maiores. Debitis repellendus libero incidunt iste fugit maxime- beatae atque. Voluptas optio consectetur modi quas debitis suscipit- eos cupiditate. Ea quis autem recusandae sit quae. Aut possimus- alias doloremque eveniet velit harum nisi. Officia fuga cum dolores- quaerat dolorem expedita laboriosam. Amet consequuntur vel voluptates- maiores nihil voluptatem. Rerum voluptatem rem officiis ullam.- Nam ipsum libero necessitatibus modi. Labore officia ipsam iste- illo ad sed ullam qui. Eos sed corrupti voluptatum alias voluptate- ipsa. Iure nulla fugit tempore pariatur praesentium veritatis.- Consequatur esse cumque dolores veritatis. Ut dicta in ipsum vero- provident illo corrupti. Earum nihil rerum quisquam provident- nisi vero quod.+ description: Illo suscipit laboriosam quod libero ad eligendi. Commodi+ reiciendis eius expedita sed. Odio quam culpa odit incidunt necessitatibus+ nemo aliquam repellat. Necessitatibus expedita dolore ipsam voluptates+ cum. Tempore magnam illo natus architecto rem. Iusto suscipit+ fugiat vero fugit sunt aut in veniam. Quas sapiente reiciendis+ temporibus error consequuntur repudiandae.description_html: |-- A ipsum vitae iusto laborum corrupti tenetur ex quaerat. Repellendus architecto tempora cupiditate quisquam dignissimos maiores. Debitis repellendus libero incidunt iste fugit maxime beatae atque. Voluptas optio consectetur modi quas debitis suscipit eos cupiditate.- Ea quis autem recusandae sit quae. Aut possimus alias doloremque eveniet velit harum nisi. Officia fuga cum dolores quaerat dolorem expedita laboriosam. Amet consequuntur vel voluptates maiores nihil voluptatem.- Rerum voluptatem rem officiis ullam. Nam ipsum libero necessitatibus modi. Labore officia ipsam iste illo ad sed ullam qui. Eos sed corrupti voluptatum alias voluptate ipsa.- Iure nulla fugit tempore pariatur praesentium veritatis. Consequatur esse cumque dolores veritatis. Ut dicta in ipsum vero provident illo corrupti. Earum nihil rerum quisquam provident nisi vero quod.+ Illo suscipit laboriosam quod libero ad eligendi. Commodi reiciendis eius expedita sed. Odio quam culpa odit incidunt necessitatibus nemo aliquam repellat. Necessitatibus expedita dolore ipsam voluptates cum.+ Tempore magnam illo natus architecto rem. Iusto suscipit fugiat vero fugit sunt aut in veniam. Quas sapiente reiciendis temporibus error consequuntur repudiandae.default_variant_id: variant_UkLWZg9DAJthumbnail_url:tags: []@@ -4316,15 +5137,15 @@ paths:display_compare_at_amount:price_list_id:variant_id: variant_UkLWZg9DAJ- created_at: '2026-04-29T15:59:59.275Z'- updated_at: '2026-04-29T15:59:59.275Z'+ created_at: '2026-04-29T20:30:44.237Z'+ updated_at: '2026-04-29T20:30:44.237Z'original_price:status: active- make_active_at: '2025-04-29T15:59:59.242Z'+ make_active_at: '2025-04-29T20:30:44.214Z'discontinue_on:deleted_at:- created_at: '2026-04-29T15:59:59.254Z'- updated_at: '2026-04-29T15:59:59.276Z'+ created_at: '2026-04-29T20:30:44.226Z'+ updated_at: '2026-04-29T20:30:44.238Z'cost_price: '17.0'cost_currency: USDmeta:@@ -4362,15 +5183,62 @@ paths:post:summary: Create a producttags:- - Products+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: |+ description: |-Creates a new product. Supports nested variants with prices and option types.Option types and values are auto-created if they don't exist.Prices are upserted by currency. Stock items are upserted by stock location.+++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const product = await client.products.create({+ name: 'Premium T-Shirt',+ price: 29.99,+ description: 'Soft, organic cotton.',+ status: 'active',+ variants: [+ {+ sku: 'TSHIRT-S-NAVY',+ options: [+ { name: 'size', value: 'Small' },+ { name: 'color', value: 'navy' },+ ],+ prices: [+ { currency: 'USD', amount: 29.99 },+ { currency: 'EUR', amount: 27.99 },+ ],+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 50 },+ ],+ },+ {+ sku: 'TSHIRT-M-NAVY',+ options: [+ { name: 'size', value: 'Medium' },+ { name: 'color', value: 'navy' },+ ],+ prices: [{ currency: 'USD', amount: 29.99 }],+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 30 },+ ],+ },+ ],+ })parameters:- name: x-spree-api-keyin: header@@ -4416,15 +5284,15 @@ paths:display_compare_at_amount:price_list_id:variant_id: variant_gbHJdmfrXB- created_at: '2026-04-29T15:59:59.954Z'- updated_at: '2026-04-29T15:59:59.954Z'+ created_at: '2026-04-29T20:30:44.893Z'+ updated_at: '2026-04-29T20:30:44.893Z'original_price:status: draftmake_active_at:discontinue_on:deleted_at:- created_at: '2026-04-29T15:59:59.953Z'- updated_at: '2026-04-29T15:59:59.959Z'+ created_at: '2026-04-29T20:30:44.892Z'+ updated_at: '2026-04-29T20:30:44.897Z'cost_price:cost_currency: USDschema:@@ -4466,17 +5334,14 @@ paths:- archivedsku:type: string- shipping_category_id:- type: string- description: Prefixed ID (e.g., sc_xxx) or integertax_category_id:type: string- description: Prefixed ID or integer- taxon_ids:+ description: Tax category ID+ category_ids:type: arrayitems:type: string- description: Array of prefixed taxon IDs+ description: Array of category IDstags:type: arrayitems:@@ -4486,25 +5351,39 @@ paths:- salevariants:type: array+ description: Array of variant payloads. Variants can declare multiple+ option pairs via `options:` and per-currency prices via `prices:`.+ Stock counts go in `stock_items:` (per stock location).items:type: objectproperties:sku:type: string- price:- type: number- option_type:- type: string- example: Size- option_value:- type: string- example: Small- total_on_hand:- type: integer+ options:+ type: array+ description: One pair per option type the variant participates+ in (e.g. size + color). Option types and values are auto-created+ if missing.+ items:+ type: object+ required:+ - name+ - value+ properties:+ name:+ type: string+ example: size+ value:+ type: string+ example: Smallprices:type: array+ description: Per-currency prices. Upserted by currency.items:type: object+ required:+ - currency+ - amountproperties:currency:type: string@@ -4515,22 +5394,52 @@ paths:compare_at_amount:type: numberexample: 39.99+ stock_items:+ type: array+ description: Per-stock-location inventory. Upserted by stock_location_id.+ items:+ type: objectrequired:- - currency- - amount+ - stock_location_id+ - count_on_hand+ properties:+ stock_location_id:+ type: string+ description: Stock location ID (e.g. sloc_xxx)+ count_on_hand:+ type: integer+ example: 50+ backorderable:+ type: booleanrequired:- name- price- - shipping_category_id"/api/v3/admin/products/{id}":get:summary: Get a producttags:- - Products+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Returns a single product by prefixed ID.+ description: |-+ Returns a single product by ID.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const product = await client.products.get('prod_86Rf07xd4z', {+ expand: ['variants', 'option_types'],+ })parameters:- name: x-spree-api-keyin: header@@ -4546,7 +5455,7 @@ paths:- name: idin: pathrequired: true- description: Product prefixed ID (e.g., prod_xxx)+ description: Product ID (e.g., prod_xxx)schema:type: string- name: expand@@ -4562,35 +5471,35 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 39711- slug: product-39711+ name: Product 344148+ slug: product-344148meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-29T16:00:00.337Z'+ available_on: '2025-04-29T20:30:45.252Z'purchasable: truein_stock: falsebackorderable: trueavailable: true- description: Fugit a hic molestiae veritatis illum voluptate veniam- praesentium. Animi aspernatur aperiam ullam voluptatibus voluptates.- Cumque laborum illum quos nulla. Natus aperiam maiores pariatur- enim. Impedit nisi molestiae dolores sint. Dolor cupiditate tenetur- dignissimos a porro harum. Provident ratione totam sunt pariatur.- Distinctio facilis nam quam at beatae impedit atque. Saepe perspiciatis- libero laudantium magni. Est sunt vel dignissimos fuga. Necessitatibus- fugit assumenda doloremque quae quibusdam. Dolores ducimus ut quos- consectetur. Asperiores similique saepe minima rem. Dignissimos- laborum fuga odit modi. Maxime inventore nesciunt beatae saepe.- Ipsa blanditiis rerum quas magni. Laborum nemo officia itaque ad- delectus. Alias accusamus animi maiores expedita autem asperiores- perferendis dolores. Debitis maiores nemo enim dolorum veritatis- ducimus nisi.+ description: Animi earum et tenetur ratione nisi cum. Sequi veniam+ deleniti nisi reiciendis. Suscipit consectetur aliquid dicta inventore.+ Tempore laudantium provident aliquam eligendi minus id deserunt.+ Voluptates dicta neque molestias quod accusamus tenetur. Nemo nihil+ ipsam veritatis autem aliquid. Voluptates magni sequi ipsa possimus+ cum provident repellendus eaque. Voluptate animi excepturi illum+ quod recusandae. Voluptatibus in ratione corrupti accusamus aut.+ Illo distinctio voluptates at voluptatem. Nihil quibusdam architecto+ blanditiis illo nesciunt velit quaerat expedita. Eum nulla quisquam+ dolorum expedita asperiores. Laudantium amet doloribus dolorum odit+ aut voluptatibus possimus cum. Reprehenderit expedita aperiam accusamus+ eligendi. Rerum in ipsam fuga magni dolores voluptatem. Similique+ itaque rerum consequatur deleniti repudiandae ad enim. Architecto+ eum dignissimos sint mollitia voluptates numquam eligendi.description_html: |-- Fugit a hic molestiae veritatis illum voluptate veniam praesentium. Animi aspernatur aperiam ullam voluptatibus voluptates. Cumque laborum illum quos nulla. Natus aperiam maiores pariatur enim. Impedit nisi molestiae dolores sint.- Dolor cupiditate tenetur dignissimos a porro harum. Provident ratione totam sunt pariatur. Distinctio facilis nam quam at beatae impedit atque. Saepe perspiciatis libero laudantium magni.- Est sunt vel dignissimos fuga. Necessitatibus fugit assumenda doloremque quae quibusdam. Dolores ducimus ut quos consectetur. Asperiores similique saepe minima rem. Dignissimos laborum fuga odit modi.- Maxime inventore nesciunt beatae saepe. Ipsa blanditiis rerum quas magni. Laborum nemo officia itaque ad delectus. Alias accusamus animi maiores expedita autem asperiores perferendis dolores. Debitis maiores nemo enim dolorum veritatis ducimus nisi.+ Animi earum et tenetur ratione nisi cum. Sequi veniam deleniti nisi reiciendis. Suscipit consectetur aliquid dicta inventore. Tempore laudantium provident aliquam eligendi minus id deserunt. Voluptates dicta neque molestias quod accusamus tenetur.+ Nemo nihil ipsam veritatis autem aliquid. Voluptates magni sequi ipsa possimus cum provident repellendus eaque. Voluptate animi excepturi illum quod recusandae. Voluptatibus in ratione corrupti accusamus aut.+ Illo distinctio voluptates at voluptatem. Nihil quibusdam architecto blanditiis illo nesciunt velit quaerat expedita. Eum nulla quisquam dolorum expedita asperiores. Laudantium amet doloribus dolorum odit aut voluptatibus possimus cum.+ Reprehenderit expedita aperiam accusamus eligendi. Rerum in ipsam fuga magni dolores voluptatem. Similique itaque rerum consequatur deleniti repudiandae ad enim. Architecto eum dignissimos sint mollitia voluptates numquam eligendi.default_variant_id: variant_UkLWZg9DAJthumbnail_url:tags: []@@ -4605,15 +5514,15 @@ paths:display_compare_at_amount:price_list_id:variant_id: variant_UkLWZg9DAJ- created_at: '2026-04-29T16:00:00.363Z'- updated_at: '2026-04-29T16:00:00.363Z'+ created_at: '2026-04-29T20:30:45.278Z'+ updated_at: '2026-04-29T20:30:45.278Z'original_price:status: active- make_active_at: '2025-04-29T16:00:00.338Z'+ make_active_at: '2025-04-29T20:30:45.252Z'discontinue_on:deleted_at:- created_at: '2026-04-29T16:00:00.350Z'- updated_at: '2026-04-29T16:00:00.364Z'+ created_at: '2026-04-29T20:30:45.265Z'+ updated_at: '2026-04-29T20:30:45.279Z'cost_price: '17.0'cost_currency: USDschema:@@ -4631,11 +5540,30 @@ paths:patch:summary: Update a producttags:- - Products+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Updates a product. Only provided fields are updated.+ description: |-+ Updates a product. Only provided fields are updated.++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const product = await client.products.update('prod_86Rf07xd4z', {+ name: 'Updated Name',+ status: 'active',+ tags: ['eco', 'sale'],+ })parameters:- name: x-spree-api-keyin: header@@ -4651,7 +5579,7 @@ paths:- name: idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: stringresponses:@@ -4662,35 +5590,21 @@ paths:example:id: prod_UkLWZg9DAJname: Updated Name- slug: product-416925+ slug: product-364026meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-29T16:00:00.997Z'+ available_on: '2025-04-29T20:30:45.885Z'purchasable: truein_stock: falsebackorderable: trueavailable: true- description: Facere animi deserunt nisi architecto esse. Laborum perferendis- neque nisi ea veniam accusantium ullam minima. Saepe odit ducimus- nostrum laudantium possimus quia vitae. Reiciendis voluptatem nisi- aut dignissimos ratione. Nam et accusantium aut quidem minima rerum.- Eaque ipsum accusamus magni facilis sed delectus. Cumque atque corrupti- recusandae debitis reprehenderit optio quo esse. Occaecati assumenda- delectus saepe nam quibusdam tempore itaque. Voluptatem delectus- vitae eius cupiditate. Quasi expedita dignissimos eaque velit. Consequatur- sequi quae nisi a explicabo. Excepturi at a quibusdam iste doloremque- dignissimos tenetur inventore. Quam quos aliquid aliquam nihil.- Voluptatum aspernatur porro occaecati officia. Earum veritatis minus- eaque molestias. Animi dolorum harum velit officia id accusantium.- Aperiam officiis eos excepturi quia autem nisi. Deleniti voluptatem- ratione soluta optio. Possimus cum dolore at magni voluptatem veniam- excepturi cumque.- description_html: |-- Facere animi deserunt nisi architecto esse. Laborum perferendis neque nisi ea veniam accusantium ullam minima. Saepe odit ducimus nostrum laudantium possimus quia vitae. Reiciendis voluptatem nisi aut dignissimos ratione. Nam et accusantium aut quidem minima rerum.- Eaque ipsum accusamus magni facilis sed delectus. Cumque atque corrupti recusandae debitis reprehenderit optio quo esse. Occaecati assumenda delectus saepe nam quibusdam tempore itaque. Voluptatem delectus vitae eius cupiditate.- Quasi expedita dignissimos eaque velit. Consequatur sequi quae nisi a explicabo. Excepturi at a quibusdam iste doloremque dignissimos tenetur inventore. Quam quos aliquid aliquam nihil. Voluptatum aspernatur porro occaecati officia.- Earum veritatis minus eaque molestias. Animi dolorum harum velit officia id accusantium. Aperiam officiis eos excepturi quia autem nisi. Deleniti voluptatem ratione soluta optio. Possimus cum dolore at magni voluptatem veniam excepturi cumque.+ description: Eius corrupti optio consequuntur consectetur. Voluptates+ et vitae magnam ad magni laboriosam accusantium officiis. Quisquam+ doloribus ea temporibus natus ipsum illum quibusdam impedit.+ description_html: Eius corrupti optio consequuntur consectetur. Voluptates+ et vitae magnam ad magni laboriosam accusantium officiis. Quisquam+ doloribus ea temporibus natus ipsum illum quibusdam impedit.default_variant_id: variant_UkLWZg9DAJthumbnail_url:tags: []@@ -4705,15 +5619,15 @@ paths:display_compare_at_amount:price_list_id:variant_id: variant_UkLWZg9DAJ- created_at: '2026-04-29T16:00:01.028Z'- updated_at: '2026-04-29T16:00:01.028Z'+ created_at: '2026-04-29T20:30:45.908Z'+ updated_at: '2026-04-29T20:30:45.908Z'original_price:status: active- make_active_at: '2025-04-29T16:00:00.998Z'+ make_active_at: '2025-04-29T20:30:45.885Z'discontinue_on:deleted_at:- created_at: '2026-04-29T16:00:01.013Z'- updated_at: '2026-04-29T16:00:01.322Z'+ created_at: '2026-04-29T20:30:45.897Z'+ updated_at: '2026-04-29T20:30:46.192Z'cost_price: '17.0'cost_currency: USDschema:@@ -4755,17 +5669,14 @@ paths:- archivedsku:type: string- shipping_category_id:- type: string- description: Prefixed ID (e.g., sc_xxx) or integertax_category_id:type: string- description: Prefixed ID or integer- taxon_ids:+ description: Tax category ID+ category_ids:type: arrayitems:type: string- description: Array of prefixed taxon IDs+ description: Array of category IDstags:type: arrayitems:@@ -4775,25 +5686,39 @@ paths:- salevariants:type: array+ description: Array of variant payloads. Variants can declare multiple+ option pairs via `options:` and per-currency prices via `prices:`.+ Stock counts go in `stock_items:` (per stock location).items:type: objectproperties:sku:type: string- price:- type: number- option_type:- type: string- example: Size- option_value:- type: string- example: Small- total_on_hand:- type: integer+ options:+ type: array+ description: One pair per option type the variant participates+ in (e.g. size + color). Option types and values are auto-created+ if missing.+ items:+ type: object+ required:+ - name+ - value+ properties:+ name:+ type: string+ example: size+ value:+ type: string+ example: Smallprices:type: array+ description: Per-currency prices. Upserted by currency.items:type: object+ required:+ - currency+ - amountproperties:currency:type: string@@ -4804,17 +5729,46 @@ paths:compare_at_amount:type: numberexample: 39.99+ stock_items:+ type: array+ description: Per-stock-location inventory. Upserted by stock_location_id.+ items:+ type: objectrequired:- - currency- - amount+ - stock_location_id+ - count_on_hand+ properties:+ stock_location_id:+ type: string+ description: Stock location ID (e.g. sloc_xxx)+ count_on_hand:+ type: integer+ example: 50+ backorderable:+ type: booleandelete:summary: Delete a producttags:- - Products+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Soft-deletes a product.+ description: |-+ Soft-deletes a product.++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.products.delete('prod_86Rf07xd4z')parameters:- name: x-spree-api-keyin: header@@ -4830,7 +5784,7 @@ paths:- name: idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: stringresponses:@@ -4840,12 +5794,27 @@ paths:get:summary: List tagstags:- - Tags+ - Configurationsecurity:- api_key: []bearer_auth: []description: Returns tag names for a given taggable type. Used for autocompletein tag inputs on products, orders, and customers.+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: tags } = await client.tags.list({+ taggable_type: 'Spree::User',+ q: 'vip',+ })parameters:- name: x-spree-api-keyin: header@@ -4891,12 +5860,28 @@ paths:get:summary: List product variantstags:- - Variants+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Returns a paginated list of variants for a product, including the- master variant.+ description: |-+ Returns a paginated list of variants for a product, including the master variant.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: variants } = await client.products.variants.list('prod_86Rf07xd4z', {+ expand: ['prices', 'stock_items'],+ })parameters:- name: x-spree-api-keyin: header@@ -4912,7 +5897,7 @@ paths:- name: product_idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: string- name: page@@ -4943,7 +5928,7 @@ paths:data:- id: variant_UkLWZg9DAJproduct_id: prod_UkLWZg9DAJ- sku: SKU-60+ sku: SKU-45options_text: ''track_inventory: truemedia_count: 0@@ -4973,13 +5958,13 @@ paths:cost_price: '17.0'cost_currency: USDdeleted_at:- created_at: '2026-04-29T16:00:04.990Z'- updated_at: '2026-04-29T16:00:05.005Z'- product_name: Product 496230+ created_at: '2026-04-29T20:30:47.959Z'+ updated_at: '2026-04-29T20:30:47.971Z'+ product_name: Product 391443display_price: "$0.00"- id: variant_gbHJdmfrXBproduct_id: prod_UkLWZg9DAJ- sku: SKU-61+ sku: SKU-46options_text: 'Size: S'track_inventory: truemedia_count: 0@@ -4987,10 +5972,10 @@ paths:purchasable: truein_stock: falsebackorderable: true- weight: 36.72- height: 157.38- width: 112.26- depth: 120.53+ weight: 16.32+ height: 118.82+ width: 185.67+ depth: 98.8price:id: price_gbHJdmfrXBamount: '19.99'@@ -5005,24 +5990,24 @@ paths:option_values:- id: optval_UkLWZg9DAJoption_type_id: opt_UkLWZg9DAJ- name: size-12+ name: size-7label: Sposition: 1color_code:- option_type_name: foo-size-21+ option_type_name: foo-size-16option_type_label: Sizeimage_url:- created_at: '2026-04-29T16:00:05.016Z'- updated_at: '2026-04-29T16:00:05.016Z'+ created_at: '2026-04-29T20:30:47.979Z'+ updated_at: '2026-04-29T20:30:47.979Z'position: 2total_on_hand: 0tax_category_id: 1cost_price: '17.0'cost_currency: USDdeleted_at:- created_at: '2026-04-29T16:00:05.014Z'- updated_at: '2026-04-29T16:00:05.029Z'- product_name: Product 496230+ created_at: '2026-04-29T20:30:47.977Z'+ updated_at: '2026-04-29T20:30:47.990Z'+ product_name: Product 391443display_price: "$19.99"meta:page: 1@@ -5037,15 +6022,43 @@ paths:post:summary: Create a varianttags:- - Variants+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: |+ description: |-Creates a new variant for a product. Supports nested prices and stock items.Option types and values are auto-created if they don't exist.Prices are upserted by currency. Stock items are upserted by stock location.+++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const variant = await client.products.variants.create('prod_86Rf07xd4z', {+ sku: 'TSHIRT-L-NAVY',+ options: [+ { name: 'size', value: 'Large' },+ { name: 'color', value: 'navy' },+ ],+ prices: [+ { currency: 'USD', amount: 29.99, compare_at_amount: 34.99 },+ { currency: 'EUR', amount: 27.99 },+ ],+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 25 },+ ],+ })parameters:- name: x-spree-api-keyin: header@@ -5061,7 +6074,7 @@ paths:- name: product_idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: stringresponses:@@ -5105,17 +6118,17 @@ paths:option_type_name: sizeoption_type_label: Sizeimage_url:- created_at: '2026-04-29T16:00:05.682Z'- updated_at: '2026-04-29T16:00:05.682Z'+ created_at: '2026-04-29T20:30:48.628Z'+ updated_at: '2026-04-29T20:30:48.628Z'position: 3total_on_hand: 0tax_category_id: 1cost_price:cost_currency: USDdeleted_at:- created_at: '2026-04-29T16:00:05.686Z'- updated_at: '2026-04-29T16:00:05.688Z'- product_name: Product 501527+ created_at: '2026-04-29T20:30:48.631Z'+ updated_at: '2026-04-29T20:30:48.633Z'+ product_name: Product 407587display_price: "$24.99"'422':description: validation error@@ -5169,30 +6182,33 @@ paths:type: stringoptions:type: array- description: Option types and values (auto-created if needed)+ description: One pair per option type the variant participates in+ (e.g. size + color). Option types and values are auto-created+ if missing.items:type: object+ required:+ - name+ - valueproperties:name:type: string- example: Size+ example: sizevalue:type: string- example: Large- required:- - name- - value- total_on_hand:- type: integer- example: 100+ example: Smallposition:type: integerbarcode:type: stringprices:type: array+ description: Per-currency prices. Upserted by currency.items:type: object+ required:+ - currency+ - amountproperties:currency:type: string@@ -5203,29 +6219,49 @@ paths:compare_at_amount:type: numberexample: 39.99- required:- - currency- - amountstock_items:type: array+ description: Per-stock-location inventory. Upserted by stock_location_id.items:type: object+ required:+ - stock_location_id+ - count_on_handproperties:stock_location_id:type: string+ description: Stock location ID (e.g. sloc_xxx)count_on_hand:type: integer+ example: 50backorderable:type: boolean"/api/v3/admin/products/{product_id}/variants/{id}":get:summary: Get a varianttags:- - Variants+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Returns a single variant by prefixed ID.+ description: |-+ Returns a single variant by ID.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const variant = await client.products.variants.get('prod_86Rf07xd4z', 'variant_k5nR8xLq', {+ expand: ['prices', 'stock_items'],+ })parameters:- name: x-spree-api-keyin: header@@ -5241,13 +6277,13 @@ paths:- name: product_idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: string- name: idin: pathrequired: true- description: Variant prefixed ID+ description: Variant IDschema:type: string- name: expand@@ -5265,7 +6301,7 @@ paths:example:id: variant_gbHJdmfrXBproduct_id: prod_UkLWZg9DAJ- sku: SKU-67+ sku: SKU-52options_text: 'Size: S'track_inventory: truemedia_count: 0@@ -5273,10 +6309,10 @@ paths:purchasable: truein_stock: falsebackorderable: true- weight: 112.88- height: 74.83- width: 191.92- depth: 80.98+ weight: 154.41+ height: 111.4+ width: 196.4+ depth: 182.8price:id: price_gbHJdmfrXBamount: '19.99'@@ -5291,24 +6327,24 @@ paths:option_values:- id: optval_UkLWZg9DAJoption_type_id: opt_UkLWZg9DAJ- name: size-15+ name: size-10label: Sposition: 1color_code:- option_type_name: foo-size-24+ option_type_name: foo-size-19option_type_label: Sizeimage_url:- created_at: '2026-04-29T16:00:06.186Z'- updated_at: '2026-04-29T16:00:06.186Z'+ created_at: '2026-04-29T20:30:49.021Z'+ updated_at: '2026-04-29T20:30:49.021Z'position: 2total_on_hand: 0tax_category_id: 1cost_price: '17.0'cost_currency: USDdeleted_at:- created_at: '2026-04-29T16:00:06.184Z'- updated_at: '2026-04-29T16:00:06.199Z'- product_name: Product 524166+ created_at: '2026-04-29T20:30:49.018Z'+ updated_at: '2026-04-29T20:30:49.034Z'+ product_name: Product 421832display_price: "$19.99"'404':description: variant not found@@ -5323,11 +6359,31 @@ paths:patch:summary: Update a varianttags:- - Variants+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Updates a variant. Only provided fields are updated.+ description: |-+ Updates a variant. Only provided fields are updated.++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const variant = await client.products.variants.update('prod_86Rf07xd4z', 'variant_k5nR8xLq', {+ sku: 'UPDATED-SKU',+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 75 },+ ],+ })parameters:- name: x-spree-api-keyin: header@@ -5343,13 +6399,13 @@ paths:- name: product_idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: string- name: idin: pathrequired: true- description: Variant prefixed ID+ description: Variant IDschema:type: stringresponses:@@ -5368,10 +6424,10 @@ paths:purchasable: truein_stock: falsebackorderable: true- weight: 130.34- height: 106.5- width: 7.87- depth: 181.87+ weight: 114.3+ height: 134.7+ width: 53.11+ depth: 92.26price:id: price_gbHJdmfrXBamount: '19.99'@@ -5386,24 +6442,24 @@ paths:option_values:- id: optval_UkLWZg9DAJoption_type_id: opt_UkLWZg9DAJ- name: size-17+ name: size-12label: Sposition: 1color_code:- option_type_name: foo-size-26+ option_type_name: foo-size-21option_type_label: Sizeimage_url:- created_at: '2026-04-29T16:00:06.891Z'- updated_at: '2026-04-29T16:00:06.891Z'+ created_at: '2026-04-29T20:30:49.700Z'+ updated_at: '2026-04-29T20:30:49.700Z'position: 2total_on_hand: 0tax_category_id: 1cost_price: '17.0'cost_currency: USDdeleted_at:- created_at: '2026-04-29T16:00:06.889Z'- updated_at: '2026-04-29T16:00:07.186Z'- product_name: Product 548526+ created_at: '2026-04-29T20:30:49.698Z'+ updated_at: '2026-04-29T20:30:49.990Z'+ product_name: Product 446460display_price: "$19.99"requestBody:content:@@ -5491,11 +6547,26 @@ paths:delete:summary: Delete a varianttags:- - Variants+ - Product Catalogsecurity:- api_key: []bearer_auth: []- description: Soft-deletes a variant.+ description: |-+ Soft-deletes a variant.++ **Required scope:** `write_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.products.variants.delete('prod_86Rf07xd4z', 'variant_k5nR8xLq')parameters:- name: x-spree-api-keyin: header@@ -5511,13 +6582,13 @@ paths:- name: product_idin: pathrequired: true- description: Product prefixed ID+ description: Product IDschema:type: string- name: idin: pathrequired: true- description: Variant prefixed ID+ description: Variant IDschema:type: stringresponses:@@ -5531,68 +6602,31 @@ servers:tags:- name: Authenticationdescription: Admin user authentication-- name: Products- description: Product management-- name: Variants- description: Product variant management-- name: Option Types- description: Option type and value management-- name: Prices- description: Variant price management+- name: Product Catalog+ description: Products, variants, and option types- name: Orders- description: Order management — list, create, update, items, complete, cancel, approve-- name: Payments- description: Order payment management — capture, void, off-session charges-- name: Refunds- description: Order refund management-- name: Fulfillments- description: Order fulfillment management — ship, cancel, split-- name: Order Gift Cards- description: Apply / remove gift cards on an order-- name: Order Store Credits- description: Apply / remove customer store credit on an order+ description: Order management — orders, items, payments, fulfillments, refunds,+ gift cards, store credits- name: Customers- description: Customer management — profile, tags, marketing consent, notes-- name: Customer Addresses- description: Saved address book per customer with default billing/shipping flags-- name: Customer Store Credits- description: Per-customer store credit balances issued by admin-- name: Customer Credit Cards- description: Customer's saved credit cards (read-only)-- name: Payment Methods- description: Store-configured payment methods (read-only)-- name: Tags- description: Tag autocomplete for product/order/customer tag inputs+ description: Customer management — profiles, addresses, store credits, credit cards+- name: Configuration+ description: Store configuration — payment methods, tag autocompletex-tagGroups:- name: Authenticationtags:- Authentication-- name: Catalog- tags:- - Products- - Variants- - Prices-- name: Options+- name: Product Catalogtags:- - Option Types+ - Product Catalog- name: Orderstags:- Orders- - Payments- - Refunds- - Fulfillments- - Order Gift Cards- - Order Store Credits- name: Customerstags:- Customers- - Customer Addresses- - Customer Store Credits- - Customer Credit Cards- name: Configurationtags:- - Payment Methods- - Tags+ - Configurationcomponents:securitySchemes:api_key:@@ -5795,11 +6829,11 @@ components:properties:item_id:type: string- description: Line item prefixed ID+ description: Line item IDexample: li_abc123variant_id:type: string- description: Variant prefixed ID+ description: Variant IDexample: variant_abc123quantity:type: integerdiff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex d347eaf18d..fe5bad1acb 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -40,624 +40,6 @@ info:```version: v3paths:- "/api/v3/admin/orders/{order_id}/adjustments":- get:- summary: List adjustments- tags:- - Adjustments- security:- - api_key: []- bearer_auth: []- description: Returns all adjustments for an order. Read-only — adjustments are- computed from promotions, taxes, and fees.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order prefixed ID- schema:- type: string- responses:- '200':- description: adjustments found- content:- application/json:- example:- data:- - id: adj_UkLWZg9DAJ- label: Admin discount- display_amount: "$0.00"- included: false- created_at: '2026-04-29T15:59:32.503Z'- updated_at: '2026-04-29T15:59:32.510Z'- amount: '0.0'- order_id: or_UkLWZg9DAJ- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- "/api/v3/admin/orders/{order_id}/adjustments/{id}":- get:- summary: Show an adjustment- tags:- - Adjustments- security:- - api_key: []- bearer_auth: []- description: Returns details of a specific adjustment.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order prefixed ID- schema:- type: string- - name: id- in: path- required: true- description: Adjustment prefixed ID- schema:- type: string- responses:- '200':- description: adjustment found- content:- application/json:- example:- id: adj_UkLWZg9DAJ- label: Admin discount- display_amount: "$0.00"- included: false- created_at: '2026-04-29T15:59:33.096Z'- updated_at: '2026-04-29T15:59:33.098Z'- amount: '0.0'- order_id: or_UkLWZg9DAJ- "/api/v3/admin/products/{product_id}/media":- get:- summary: List product media- tags:- - Product Media- security:- - api_key: []- bearer_auth: []- description: Returns a paginated list of media (images, video) for a product.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Number of records per page- schema:- type: integer- responses:- '200':- description: media found- content:- application/json:- example:- data:- - id: media_UkLWZg9DAJ- product_id: prod_UkLWZg9DAJ- variant_ids:- - variant_UkLWZg9DAJ- position: 1- alt:- media_type: image- focal_point_x:- focal_point_y:- external_video_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg- created_at: '2026-04-29T15:59:57.579Z'- updated_at: '2026-04-29T15:59:57.584Z'- viewable_id: variant_UkLWZg9DAJ- viewable_type: Spree::Variant- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- post:- summary: Create a product media item- tags:- - Product Media- security:- - api_key: []- bearer_auth: []- description: Creates a new media item (image, video) for a product.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- responses:- '202':- description: media import from URL enqueued- '422':- description: validation error (attachment required)- content:- application/json:- example:- error:- code: validation_error- message: Attachment can't be blank- details:- attachment:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- alt:- type: string- example: Product front view- position:- type: integer- example: 1- type:- type: string- example: Spree::Image- description: Media type (defaults to Spree::Image)- url:- type: string- example: https://example.com/image.jpg- description: External URL to import image from (async). Returns- 202 Accepted.- "/api/v3/admin/products/{product_id}/media/{id}":- patch:- summary: Update a product media item- tags:- - Product Media- security:- - api_key: []- bearer_auth: []- description: Updates a product media item. Only provided fields are updated.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: id- in: path- required: true- description: Media prefixed ID- schema:- type: string- responses:- '200':- description: media updated- content:- application/json:- example:- id: media_UkLWZg9DAJ- product_id: prod_UkLWZg9DAJ- variant_ids:- - variant_UkLWZg9DAJ- position: 1- alt: Updated alt text- media_type: image- focal_point_x:- focal_point_y:- external_video_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg- created_at: '2026-04-29T15:59:58.609Z'- updated_at: '2026-04-29T15:59:58.899Z'- viewable_id: variant_UkLWZg9DAJ- viewable_type: Spree::Variant- requestBody:- content:- application/json:- schema:- type: object- properties:- alt:- type: string- example: Updated alt text- position:- type: integer- example: 2- delete:- summary: Delete a product media item- tags:- - Product Media- security:- - api_key: []- bearer_auth: []- description: Deletes a media item from a product.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: id- in: path- required: true- description: Media prefixed ID- schema:- type: string- responses:- '204':- description: media deleted- "/api/v3/admin/products/{product_id}/variants/{variant_id}/media":- get:- summary: List variant media- tags:- - Variant Media- security:- - api_key: []- bearer_auth: []- description: Returns a paginated list of media (images, video) for a variant.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: variant_id- in: path- required: true- description: Variant prefixed ID- schema:- type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Number of records per page- schema:- type: integer- responses:- '200':- description: variant media found- content:- application/json:- example:- data:- - id: media_UkLWZg9DAJ- product_id: prod_UkLWZg9DAJ- variant_ids:- - variant_gbHJdmfrXB- position: 1- alt:- media_type: image- focal_point_x:- focal_point_y:- external_video_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg- created_at: '2026-04-29T16:00:03.230Z'- updated_at: '2026-04-29T16:00:03.232Z'- viewable_id: variant_gbHJdmfrXB- viewable_type: Spree::Variant- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- post:- summary: Create a variant media item- tags:- - Variant Media- security:- - api_key: []- bearer_auth: []- description: Creates a new media item (image, video) for a variant.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: variant_id- in: path- required: true- description: Variant prefixed ID- schema:- type: string- responses:- '202':- description: variant media import from URL enqueued- '422':- description: validation error (attachment required)- content:- application/json:- example:- error:- code: validation_error- message: Attachment can't be blank- details:- attachment:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- alt:- type: string- example: Variant image- position:- type: integer- example: 1- type:- type: string- example: Spree::Image- description: Media type (defaults to Spree::Image)- url:- type: string- example: https://example.com/image.jpg- description: External URL to import image from (async). Returns- 202 Accepted.- "/api/v3/admin/products/{product_id}/variants/{variant_id}/media/{id}":- patch:- summary: Update a variant media item- tags:- - Variant Media- security:- - api_key: []- bearer_auth: []- description: Updates a variant media item. Only provided fields are updated.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: variant_id- in: path- required: true- description: Variant prefixed ID- schema:- type: string- - name: id- in: path- required: true- description: Media prefixed ID- schema:- type: string- responses:- '200':- description: variant media updated- content:- application/json:- example:- id: media_UkLWZg9DAJ- product_id: prod_UkLWZg9DAJ- variant_ids:- - variant_gbHJdmfrXB- position: 1- alt: Updated variant image- media_type: image- focal_point_x:- focal_point_y:- external_video_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--91c795e37aabebcd6d835b0ec511e9ff9f42229d/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--412eb7d358e08c9e384728ff0d6150a725ae2ff4/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--341cac2fb7fb7b5265fbca9cf5f6ba03a645f4fb/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2a20e958723b87ff75d0681199260faa9b1fdcd1/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--ddd095e8f694911905f100ba0f63bd3131a293ce/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--3b629ef2aa813d248c6f5821ac29239af940250f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--132b3a0a2b76bb0a03fa5fe8d337136a7ec3a980/thinking-cat.jpg- created_at: '2026-04-29T16:00:04.299Z'- updated_at: '2026-04-29T16:00:04.592Z'- viewable_id: variant_gbHJdmfrXB- viewable_type: Spree::Variant- requestBody:- content:- application/json:- schema:- type: object- properties:- alt:- type: string- example: Updated variant image- position:- type: integer- example: 2- delete:- summary: Delete a variant media item- tags:- - Variant Media- security:- - api_key: []- bearer_auth: []- description: Deletes a media item from a variant.- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product prefixed ID- schema:- type: string- - name: variant_id- in: path- required: true- description: Variant prefixed ID- schema:- type: string- - name: id- in: path- required: true- description: Media prefixed ID- schema:- type: string- responses:- '204':- description: variant media deleted"/api/v3/store/customers/me/addresses":get:summary: List customer addresses@@ -720,7 +102,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 67 Lovely Street+ address1: 65 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -738,7 +120,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 66 Lovely Street+ address1: 64 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -756,7 +138,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 65 Lovely Street+ address1: 63 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1005,7 +387,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 79 Lovely Street+ address1: 77 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1080,7 +462,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 85 Lovely Street+ address1: 83 Lovely Streetaddress2: Northwestpostal_code: '10118'city: Los Angeles@@ -1208,16 +590,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjBkN2ZkNGY4LWM3MjAtNDZlNS05OWM4LTk5ODQ1NThlN2Y0ZiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDgyMDEzfQ.rSgbM_4Burg-CxDBtJdl-zhm-dmwW2i8i3BH5VE8m78- refresh_token: wCxXpbHe4qCGW8kCmGwF1TBZ+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjUyMWQ1YzAxLWZkZjgtNDQ3My04MDk2LTBhNmIyYzlhMzQyNiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjU1fQ.REJwQWqlzarNd_TADKFBUnuFk7HCQJPoCCBcaQIV2pE+ refresh_token: XPJQbpb99u3n8mfatXsiPygLuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Brent- last_name: Howell+ first_name: Mathew+ last_name: Bayerphone:accepts_email_marketing: false- full_name: Brent Howell+ full_name: Mathew Bayeravailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -1290,16 +672,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjkxMjkxN2U4LTkzY2QtNDk4Yi05YzlkLTkwMmNlNTY4ZDMxOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDgyMDE0fQ.iNMfHrigR-mVxbt7gnYGxM5Qziq9rq5K9Q_sSEaJq8U- refresh_token: ig5mKBAuVE5MemW2UaubSick+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjU2ZTA2YmZiLTQ2MTQtNGYxNC05YmFmLWJiOTY3OWU0N2QwYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjU2fQ.Y_B6-QarGKzxJu4d76m-B489kmJ9fXBpbgXo9HnLA0Y+ refresh_token: VzP8jvcXUsAmMAXyYLGxjqdeuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Bernadine- last_name: Doyle+ first_name: Ahmad+ last_name: Gradyphone:accepts_email_marketing: false- full_name: Bernadine Doyle+ full_name: Ahmad Gradyavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -1463,9 +845,9 @@ paths:data:- id: cart_gbHJdmfrXBmarket_id:- number: R496917299- token: 14v8s9wyYvneSSMd6DD5r2LtMDguAnDm9u6- email: [email protected]+ number: R182881602+ token: 7xmFzBupB64Eqt1AJrjxAZshQ6hpfxqeukX+ email: [email protected]customer_note:currency: USDlocale: en@@ -1507,8 +889,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 579733- slug: product-579733+ name: Product 477312+ slug: product-477312options_text: ''price: '10.0'display_price: "$10.00"@@ -1533,7 +915,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H64308445398+ number: H50238594154tracking: U10000tracking_url:cost: '100.0'@@ -1562,7 +944,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Shanel Schaefer+ name: Rashida Wardaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1594,7 +976,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 100 Lovely Street+ address1: 98 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1613,7 +995,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 101 Lovely Street+ address1: 99 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1632,9 +1014,9 @@ paths:market:- id: cart_UkLWZg9DAJmarket_id:- number: R384180305- token: QBU9FrPXCFJzmaRRAjyZBy9Kz4fd2FdpYt5- email: [email protected]+ number: R180174120+ token: M8LpDgv8esPyaFgerorVBCzTNxbbRBiBcH6+ email: [email protected]customer_note:currency: USDlocale: en@@ -1676,8 +1058,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 566791- slug: product-566791+ name: Product 466677+ slug: product-466677options_text: ''price: '10.0'display_price: "$10.00"@@ -1702,7 +1084,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H91469194561+ number: H72269460516tracking: U10000tracking_url:cost: '100.0'@@ -1731,7 +1113,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Shanel Schaefer+ name: Rashida Wardaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1763,7 +1145,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 98 Lovely Street+ address1: 96 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1782,7 +1164,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 99 Lovely Street+ address1: 97 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -1874,8 +1256,8 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R691642289- token: W1AjJm3NKZSMmctV9Tda2rfwcLhQZcmem8Y+ number: R019335701+ token: gt4CxjNxUGXa3c8guMYCXPvRMWBbpKPSDCyemail:customer_note:currency: USD@@ -2030,9 +1412,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R511540545- token: NMTe7trEmwcBD9EW6mWjsFPYsLZKUD3NKhk- email: [email protected]+ number: R136520724+ token: RDTgrgyzKwVcNA6uExX2tPfK9FiT5RiXg5X+ email: [email protected]customer_note:currency: USDlocale: en@@ -2059,7 +1441,7 @@ paths:display_delivery_total: "$0.00"warnings:- code: line_item_removed- message: Product 619413 was removed because it was sold out+ message: Product 517886 was removed because it was sold outline_item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJstore_credit_total: '0.0'@@ -2084,7 +1466,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 108 Lovely Street+ address1: 106 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2103,7 +1485,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 109 Lovely Street+ address1: 107 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2201,9 +1583,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R101821028- token: auf9jP48vgoAgv6dDF5pocrdj2xRFmaC79Y- email: [email protected]+ number: R589446831+ token: 5jpsbFd46zdFZnxX83WMCjoaVuRUz5NjNCv+ email: [email protected]customer_note: Leave at doorcurrency: USDlocale: en@@ -2247,8 +1629,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 628443- slug: product-628443+ name: Product 52369+ slug: product-52369options_text: ''price: '19.99'display_price: "$19.99"@@ -2273,7 +1655,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H07153056867+ number: H91438962756tracking:tracking_url:cost: '10.0'@@ -2302,7 +1684,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Kendrick Nienow+ name: Ike Schummaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2334,7 +1716,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 112 Lovely Street+ address1: 110 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2353,7 +1735,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 113 Lovely Street+ address1: 111 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2539,9 +1921,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R496488366- token: QyG1CoSmhsREvUj68UV6mdCjbK6B588iEDX- email: [email protected]+ number: R265003786+ token: aFhxuJ1gwfZ9RxSPHFyEdgDesj1URBDnDwg+ email: [email protected]customer_note:currency: USDlocale: en@@ -2583,8 +1965,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 643922- slug: product-643922+ name: Product 545852+ slug: product-545852options_text: ''price: '10.0'display_price: "$10.00"@@ -2609,7 +1991,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H01312263235+ number: H27932063184tracking: U10000tracking_url:cost: '100.0'@@ -2638,7 +2020,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Kyra Jast+ name: Hiram Schmidtaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2670,7 +2052,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 118 Lovely Street+ address1: 116 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2689,7 +2071,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 119 Lovely Street+ address1: 117 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2772,8 +2154,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R661978413- email: [email protected]+ number: R600375601+ email: [email protected]customer_note:currency: USDlocale: en@@ -2800,7 +2182,7 @@ paths:display_delivery_total: "$10.00"fulfillment_status: backorderpayment_status: paid- completed_at: '2026-04-29T16:00:20.549Z'+ completed_at: '2026-04-29T20:31:02.835Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -2810,8 +2192,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 662849- slug: product-662849+ name: Product 566923+ slug: product-566923options_text: ''price: '19.99'display_price: "$19.99"@@ -2836,7 +2218,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H95827918638+ number: H21719438891tracking:tracking_url:cost: '10.0'@@ -2865,7 +2247,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Carola Lueilwitz+ name: Zella Flatleyaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2894,8 +2276,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-def49f44c66f- number: P97I9JEM+ response_code: BGS-3cd8d54d3a63+ number: P5SEJH2Namount: '29.99'display_amount: "$29.99"status: completed@@ -2922,7 +2304,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 126 Lovely Street+ address1: 124 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -2941,7 +2323,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 127 Lovely Street+ address1: 125 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -3751,16 +3133,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImYzY2MwMDFiLTMzMTgtNGE5YS1hNzM3LWRhNTAwMTE4MmMyNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDgyMDI3fQ.2nR7D1VUtVOj9FetV56yOhfIdSpAoQGXQIT5X19D3YE- refresh_token: JxbtKAkym9dtQo5d3PawV1A2+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImNlZTBlMmVlLTVjYTMtNGNmNy1hYjRkLWFlNzY3MWE0ODAyMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjY5fQ.b_0Zzjl18__wi6pnjPBGIzu7aE8I1LJ-7Uz5vg2e-_4+ refresh_token: NYmxCAw5u8FtKDzarLk2VB1Auser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Gayla- last_name: Witting+ first_name: Katlyn+ last_name: Kuhnphone:accepts_email_marketing: false- full_name: Gayla Witting+ full_name: Katlyn Kuhnavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -3930,8 +3312,8 @@ paths:data:- id: or_UkLWZg9DAJmarket_id:- number: R832819108- email: [email protected]+ number: R270430768+ email: [email protected]customer_note:currency: USDlocale: en@@ -3958,7 +3340,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-04-29T16:00:28.242Z'+ completed_at: '2026-04-29T20:31:10.038Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -3968,8 +3350,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 755263- slug: product-755263+ name: Product 653038+ slug: product-653038options_text: ''price: '10.0'display_price: "$10.00"@@ -3994,7 +3376,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H44154252716+ number: H02369830101tracking: U10000tracking_url:cost: '100.0'@@ -4023,7 +3405,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Alane Hegmann+ name: Shayla Gerlachaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4055,7 +3437,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 146 Lovely Street+ address1: 144 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4074,7 +3456,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 147 Lovely Street+ address1: 145 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4185,8 +3567,8 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R624689755- email: [email protected]+ number: R634795563+ email: [email protected]customer_note:currency: USDlocale: en@@ -4213,7 +3595,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-04-29T16:00:28.955Z'+ completed_at: '2026-04-29T20:31:10.734Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -4223,8 +3605,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 772121- slug: product-772121+ name: Product 673736+ slug: product-673736options_text: ''price: '10.0'display_price: "$10.00"@@ -4249,7 +3631,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H33308593214+ number: H68508572865tracking: U10000tracking_url:cost: '100.0'@@ -4278,7 +3660,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Valery Conn+ name: Rivka Harveyaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4310,7 +3692,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 152 Lovely Street+ address1: 150 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4329,7 +3711,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 153 Lovely Street+ address1: 151 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4398,8 +3780,8 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImQ5MmE1OWU0LTMzMDAtNDk0Ny04MzFmLTU4OGZlYzNjNGYxOCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDgyMDMwfQ.-EYQoFb28Sqk6onWxtgXarFXyr3ysIgg2W1uGpM440w- refresh_token: KV2opHCMpzNqp5bpPCo9Yd6u+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImEwYjExODAyLTY3ZWEtNGUzNy04M2Q4LTg1MTQ2YTVhNGIwMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzc3NDk4MjcxfQ.5idDO7ASyl4HrqvrIOBrurfHFjFFGZl-jjAwtgtiP7o+ refresh_token: 2AobsjUHtC2zLJjrBGx7jc5zuser:id: cus_UkLWZg9DAJemail: [email protected]@@ -4513,12 +3895,12 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Jonah- last_name: Rutherford+ email: [email protected]+ first_name: Manuela+ last_name: O'Konphone: 555-555-0199accepts_email_marketing: false- full_name: Jonah Rutherford+ full_name: Manuela O'Konavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses:@@ -4526,7 +3908,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 159 Lovely Street+ address1: 157 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4544,7 +3926,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 158 Lovely Street+ address1: 156 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4563,7 +3945,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 159 Lovely Street+ address1: 157 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4582,7 +3964,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 158 Lovely Street+ address1: 156 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4652,7 +4034,7 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Namephone: 555-555-0199@@ -4665,7 +4047,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 161 Lovely Street+ address1: 159 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4683,7 +4065,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 160 Lovely Street+ address1: 158 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4702,7 +4084,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 161 Lovely Street+ address1: 159 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4721,7 +4103,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 160 Lovely Street+ address1: 158 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4892,9 +4274,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R684238326- token: u6ecSSHe1CGhDripbUftdK41Jsec1LqM4bc- email: [email protected]+ number: R686751507+ token: PfLkSHCKhzw3ZFoT3Evj6bX72KEAePEERfW+ email: [email protected]customer_note:currency: USDlocale: en@@ -4943,8 +4325,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 855536- slug: product-855536+ name: Product 755782+ slug: product-755782options_text: ''price: '10.0'display_price: "$10.00"@@ -4969,7 +4351,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H53375671698+ number: H81703772553tracking: U10000tracking_url:cost: '100.0'@@ -4998,7 +4380,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Camila McCullough+ name: Larita Lakinaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5030,7 +4412,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 178 Lovely Street+ address1: 176 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5049,7 +4431,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 179 Lovely Street+ address1: 177 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5152,9 +4534,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R636351307- token: ZuEsV7CieZAFaG4m17MPKposzN9bASB18Gg- email: [email protected]+ number: R666419309+ token: nc7Dy8DuA7PFHd5sn1zM2b8gpHDPfgEp1tt+ email: [email protected]customer_note:currency: USDlocale: en@@ -5196,8 +4578,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 878882- slug: product-878882+ name: Product 772017+ slug: product-772017options_text: ''price: '10.0'display_price: "$10.00"@@ -5222,7 +4604,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H40345253216+ number: H42154252733tracking: U10000tracking_url:cost: '100.0'@@ -5251,7 +4633,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Shane DuBuque+ name: Margarett Hoegeraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5283,7 +4665,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 186 Lovely Street+ address1: 184 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5302,7 +4684,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 187 Lovely Street+ address1: 185 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5394,9 +4776,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R682532547- token: cJ71DWMVgw44QB3afABkDchQ8VC76qvjNjp- email: [email protected]+ number: R679060655+ token: gePNeiWirzf2J7y37iBdarBX4qVLfs3eEgi+ email: [email protected]customer_note:currency: USDlocale: en@@ -5440,8 +4822,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 89648- slug: product-89648+ name: Product 796254+ slug: product-796254options_text: ''price: '10.0'display_price: "$10.00"@@ -5466,7 +4848,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H83618197901+ number: H02184977229tracking: U10000tracking_url:cost: '100.0'@@ -5495,7 +4877,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Yer Cassin+ name: Bridget Helleraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5527,7 +4909,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 194 Lovely Street+ address1: 192 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5546,7 +4928,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 195 Lovely Street+ address1: 193 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5652,9 +5034,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R134509356- token: Pc31yhLMexVeuwqP7x3aKHw8r1v9n8X1PHk- email: [email protected]+ number: R134922089+ token: v2NsykGGYJxbRhYHnN1wb62cK4Q7KNoBxYx+ email: [email protected]customer_note:currency: USDlocale: en@@ -5693,8 +5075,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 919205- slug: product-919205+ name: Product 813626+ slug: product-813626options_text: ''price: '10.0'display_price: "$10.00"@@ -5719,7 +5101,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H44860419830+ number: H20006652345tracking: U10000tracking_url:cost: '100.0'@@ -5748,7 +5130,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Lue Windler+ name: Taisha Kochaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5777,8 +5159,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260429160039175123- number: P1F24VXD+ response_code: 1-SC-20260429203120465620+ number: PYZM56EOamount: '50.0'display_amount: "$50.00"status: checkout@@ -5805,7 +5187,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 202 Lovely Street+ address1: 200 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5824,7 +5206,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 203 Lovely Street+ address1: 201 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -5957,9 +5339,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R058228208- token: vKMtw8bFJNKEKCDEo6wkcCGjagCReoeQ5hT- email: [email protected]+ number: R739841957+ token: Zsmwu1S5EBR4ua9KCtREh1LboGrdYxeCjXh+ email: [email protected]customer_note:currency: USDlocale: en@@ -6001,8 +5383,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 955154- slug: product-955154+ name: Product 856826+ slug: product-856826options_text: ''price: '10.0'display_price: "$10.00"@@ -6027,7 +5409,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H82159045492+ number: H08780625784tracking: U10000tracking_url:cost: '100.0'@@ -6056,7 +5438,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Arleen Bartell+ name: Lynsey Bodeaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6085,8 +5467,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260429160041706187- number: PB0HE5QW+ response_code: 1-SC-20260429203123363868+ number: P605ZYX4amount: '50.0'display_amount: "$50.00"status: invalid@@ -6113,7 +5495,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 218 Lovely Street+ address1: 216 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6132,7 +5514,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 219 Lovely Street+ address1: 217 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6210,7 +5592,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: 2FE4341082F198C4+ code: 49492AAAF001FBB7status: activecurrency: USDamount: '10.0'@@ -6306,7 +5688,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: ED365F485FE3776A+ code: 7C8C28BE6FE5ECDEstatus: activecurrency: USDamount: '10.0'@@ -6397,9 +5779,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R775361233- token: W1EWaRx5iBZnn83Vn66BSjeqUq9jQjy438s- email: [email protected]+ number: R160774453+ token: VshV5k2uUhjKTJj8apmDPv31xd5qkh3sh5Y+ email: [email protected]customer_note:currency: USDlocale: en@@ -6447,8 +5829,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 984707- slug: product-984707+ name: Product 888823+ slug: product-888823options_text: ''price: '10.0'display_price: "$10.00"@@ -6475,8 +5857,8 @@ paths:variant_id: variant_gbHJdmfrXBquantity: 1currency: USD- name: Product 99985- slug: product-99985+ name: Product 895490+ slug: product-895490options_text: ''price: '19.99'display_price: "$19.99"@@ -6506,7 +5888,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 233 Lovely Street+ address1: 231 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6619,9 +6001,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R042592274- token: uJnik897i8sPndA2u7koP8pUgbZW9rte8gs- email: [email protected]+ number: R417441624+ token: 6fGMJoT6FeteiGKiWb7Awm5ZSeEZGUYFXPT+ email: [email protected]customer_note:currency: USDlocale: en@@ -6666,8 +6048,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 102651- slug: product-102651+ name: Product 925658+ slug: product-925658options_text: ''price: '10.0'display_price: "$10.00"@@ -6697,7 +6079,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 242 Lovely Street+ address1: 240 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -6790,9 +6172,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R910961026- token: uEZu67z8eF6jkqokHhX5ZG5oj3hk4gparTn- email: [email protected]+ number: R327511489+ token: vz6NujDsYszBfSh8snFmiUjv4XN8jV22n8D+ email: [email protected]customer_note:currency: USDlocale: en@@ -6843,7 +6225,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 245 Lovely Street+ address1: 243 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -7393,7 +6775,7 @@ paths:example:id: or_UkLWZg9DAJmarket_id:- number: R404436615+ number: R773500111email: [email protected]customer_note:currency: USD@@ -7421,7 +6803,7 @@ paths:display_delivery_total: "$100.00"fulfillment_status:payment_status:- completed_at: '2026-04-29T16:00:49.872Z'+ completed_at: '2026-04-29T20:31:31.385Z'store_credit_total: '0.0'display_store_credit_total: "$0.00"covered_by_store_credit: false@@ -7431,8 +6813,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 106449- slug: product-106449+ name: Product 966442+ slug: product-966442options_text: ''price: '10.0'display_price: "$10.00"@@ -7457,7 +6839,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H83574844550+ number: H86313255182tracking: U10000tracking_url:cost: '100.0'@@ -7486,7 +6868,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Nora Mueller+ name: Tandra Weberaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7518,7 +6900,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 253 Lovely Street+ address1: 251 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -7537,7 +6919,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 254 Lovely Street+ address1: 252 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -7631,9 +7013,9 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_7c95fb2319657ba994cc2207+ external_id: bogus_5be4f6882cb65c798b36044bexternal_data:- client_secret: bogus_secret_1dccd1a9fa1716cf+ client_secret: bogus_secret_83acefba58c748facustomer_external_id:expires_at:amount: '110.0'@@ -7731,7 +7113,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_ccc13a869ffecd10dffe7812+ external_id: bogus_eea6b836764131d01d8930c3external_data:client_secret: secret_123customer_external_id:@@ -7793,7 +7175,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_554e57fdc224df25d5e22aa4+ external_id: bogus_c42d7bb8c46ce77865501174external_data:client_secret: secret_123customer_external_id:@@ -7895,7 +7277,7 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_b2779ff1fd23789a717fc8b5+ external_id: bogus_da9af71a978676085b99ce61external_data:client_secret: secret_123customer_external_id:@@ -7980,8 +7362,8 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_18928969f2502cd4c2c1ce32- external_client_secret: bogus_seti_secret_64707f0d54f29d38+ external_id: bogus_seti_69d0c0fba541cf751511c029+ external_client_secret: bogus_seti_secret_e91402dff84ebb58external_data: {}payment_method_id: pm_UkLWZg9DAJpayment_source_id:@@ -8080,8 +7462,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_95227153d866b2994ca7ca92- external_client_secret: seti_secret_17c2c2cef27524e368875fb0+ external_id: seti_test_c9f7f791cdf7b9c36dea5ae9+ external_client_secret: seti_secret_e7cca325c5d0792f378adc51external_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -8157,8 +7539,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_7dba83629f90b18f1b1e43fa- external_client_secret: seti_secret_f0f84f9147db743c3bd09176+ external_id: seti_test_73a3566842a3d01db9a800e0+ external_client_secret: seti_secret_2f94274fab6af1dfb46b5b39external_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -8252,7 +7634,7 @@ paths:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJresponse_code:- number: PT31KFV5+ number: PHAY8LI4amount: '110.0'display_amount: "$110.00"status: checkout@@ -8348,7 +7730,7 @@ paths:body_html: ''- id: pol_OIJLhNcSbfname: Privacy Policy- slug: privacy-policy-ea963688-a324-427f-98ef-cb1454aa0b36+ slug: privacy-policy-24a44547-bd29-493a-9028-25e30b0c6417body: We respect your privacy.body_html: |<div class="trix-content">@@ -8592,12 +7974,12 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 1167671- slug: product-1167671+ name: Product 1066950+ slug: product-1066950meta_description:meta_keywords:variant_count: 1- available_on: '2025-04-29T16:01:00.580Z'+ available_on: '2025-04-29T20:31:41.571Z'purchasable: truein_stock: falsebackorderable: true@@ -8619,41 +8001,40 @@ paths:price_list_id:original_price:- id: prod_gbHJdmfrXB- name: Product 1171988- slug: product-1171988+ name: Product 1078704+ slug: product-1078704meta_description:meta_keywords:variant_count: 0- available_on: '2025-04-29T16:01:00.655Z'+ available_on: '2025-04-29T20:31:41.632Z'purchasable: truein_stock: falsebackorderable: trueavailable: true- description: Odio ullam voluptatum illo laborum. Molestiae temporibus- architecto iusto ratione officia aliquam similique facilis. Molestiae- omnis error enim veritatis. Sequi voluptate asperiores repudiandae- dignissimos accusantium maxime perspiciatis praesentium. Dicta- assumenda reprehenderit commodi quo placeat minima voluptatum- incidunt. Labore quos quod quo id consectetur fugiat eaque. Nobis- amet cum voluptates rem minus quasi corporis. Exercitationem reprehenderit- maxime enim inventore assumenda. Voluptatibus debitis aliquam- inventore quis similique. Eaque accusantium corporis saepe doloremque- laudantium quam. Similique aspernatur molestiae reiciendis consequatur- distinctio quia. Distinctio quaerat doloribus totam ex laudantium- nulla eaque. Odit laborum voluptas voluptates pariatur animi praesentium- accusamus. Quae et numquam a cupiditate pariatur ducimus impedit.- Ducimus consequatur neque eligendi natus nihil esse. Rem sapiente- maiores iusto reiciendis. Ad dolore eum sed odio tempore eveniet- ipsum accusamus. Fugit aperiam quasi aut officia eligendi. Ipsa- adipisci asperiores doloribus eaque. Maxime perferendis non recusandae- sed id ipsam suscipit ducimus. Minima officiis fugit laborum dolorum- neque eius.+ description: Id qui consequatur sapiente dolor eveniet ipsum. Quidem+ vel possimus corporis aut a porro doloremque. Quasi sint totam+ placeat quos vel dicta iusto sapiente. Amet non tempora perferendis+ saepe. Nesciunt distinctio accusantium vitae tempore. Aut et id+ odio qui sapiente minima nemo ipsum. Et veniam nesciunt minus+ itaque quam. Aspernatur ipsum facere aut dignissimos. Ullam natus+ commodi magnam quisquam aperiam laudantium ut asperiores. Quis+ facere dolorum deserunt soluta. Commodi ut in harum rem maiores+ dolore. Facilis ex vel saepe cupiditate. Cumque molestias esse+ nulla odio itaque. Non velit cumque reprehenderit eaque iste.+ Fugit quidem deserunt quisquam accusamus sed sequi dolorum. Repellat+ voluptatum perferendis doloribus culpa quibusdam at voluptas.+ Sed deserunt perspiciatis ea temporibus. Eaque veniam necessitatibus+ inventore dicta reiciendis doloremque. Cupiditate officia illo+ impedit assumenda. Consequuntur commodi inventore quidem molestiae+ laborum. Quaerat voluptatem maiores quos veniam neque molestias.+ Eaque unde officiis illo dignissimos voluptate laboriosam ad enim.+ Et accusamus adipisci dolor facere tempore itaque.description_html: |-- Odio ullam voluptatum illo laborum. Molestiae temporibus architecto iusto ratione officia aliquam similique facilis. Molestiae omnis error enim veritatis. Sequi voluptate asperiores repudiandae dignissimos accusantium maxime perspiciatis praesentium.- Dicta assumenda reprehenderit commodi quo placeat minima voluptatum incidunt. Labore quos quod quo id consectetur fugiat eaque. Nobis amet cum voluptates rem minus quasi corporis. Exercitationem reprehenderit maxime enim inventore assumenda. Voluptatibus debitis aliquam inventore quis similique.- Eaque accusantium corporis saepe doloremque laudantium quam. Similique aspernatur molestiae reiciendis consequatur distinctio quia. Distinctio quaerat doloribus totam ex laudantium nulla eaque. Odit laborum voluptas voluptates pariatur animi praesentium accusamus. Quae et numquam a cupiditate pariatur ducimus impedit.- Ducimus consequatur neque eligendi natus nihil esse. Rem sapiente maiores iusto reiciendis. Ad dolore eum sed odio tempore eveniet ipsum accusamus. Fugit aperiam quasi aut officia eligendi.- Ipsa adipisci asperiores doloribus eaque. Maxime perferendis non recusandae sed id ipsam suscipit ducimus. Minima officiis fugit laborum dolorum neque eius.+ Id qui consequatur sapiente dolor eveniet ipsum. Quidem vel possimus corporis aut a porro doloremque. Quasi sint totam placeat quos vel dicta iusto sapiente. Amet non tempora perferendis saepe.+ Nesciunt distinctio accusantium vitae tempore. Aut et id odio qui sapiente minima nemo ipsum. Et veniam nesciunt minus itaque quam. Aspernatur ipsum facere aut dignissimos.+ Ullam natus commodi magnam quisquam aperiam laudantium ut asperiores. Quis facere dolorum deserunt soluta. Commodi ut in harum rem maiores dolore. Facilis ex vel saepe cupiditate. Cumque molestias esse nulla odio itaque.+ Non velit cumque reprehenderit eaque iste. Fugit quidem deserunt quisquam accusamus sed sequi dolorum. Repellat voluptatum perferendis doloribus culpa quibusdam at voluptas. Sed deserunt perspiciatis ea temporibus. Eaque veniam necessitatibus inventore dicta reiciendis doloremque.+ Cupiditate officia illo impedit assumenda. Consequuntur commodi inventore quidem molestiae laborum. Quaerat voluptatem maiores quos veniam neque molestias. Eaque unde officiis illo dignissimos voluptate laboriosam ad enim. Et accusamus adipisci dolor facere tempore itaque.default_variant_id: variant_EfhxLZ9ck8thumbnail_url:tags: []@@ -8755,12 +8136,12 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 1446790- slug: product-1446790+ name: Product 1341741+ slug: product-1341741meta_description:meta_keywords:variant_count: 1- available_on: '2025-04-29T16:01:02.256Z'+ available_on: '2025-04-29T20:31:43.333Z'purchasable: truein_stock: falsebackorderable: true@@ -8787,7 +8168,7 @@ paths:amount_in_cents: 999currency: USDdisplay_amount: "$9.99"- recorded_at: '2026-04-14T16:01:02Z'+ recorded_at: '2026-04-14T20:31:43Z'schema:"$ref": "#/components/schemas/Product"'404':@@ -9162,9 +8543,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R021918322- token: SAUJRQh1TveULkP81cF4ixpTswBACZZcF6F- email: [email protected]+ number: R702444710+ token: KKKKz15uUX3wLs3WeMci3aiDUn8NLgjRMRd+ email: [email protected]customer_note:currency: USDlocale: en@@ -9203,8 +8584,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1643340- slug: product-1643340+ name: Product 1546874+ slug: product-1546874options_text: ''price: '10.0'display_price: "$10.00"@@ -9229,7 +8610,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H00294560922+ number: H03249355163tracking: U10000tracking_url:cost: '100.0'@@ -9258,7 +8639,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Silva Hills+ name: Nada Hettingeraddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -9287,8 +8668,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260429160107728556- number: PE5SHORE+ response_code: 1-SC-20260429203148434892+ number: POQWOLDSamount: '10.0'display_amount: "$10.00"status: checkout@@ -9315,7 +8696,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 317 Lovely Street+ address1: 315 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -9334,7 +8715,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 318 Lovely Street+ address1: 316 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -9431,9 +8812,9 @@ paths:example:id: cart_UkLWZg9DAJmarket_id:- number: R685003154- token: 2HqSo4dFnwipJUsBxSm53XA3SC7q9auGjkx- email: [email protected]+ number: R968281647+ token: vyW18bBrgGcr9BHW4DWLGKxUtYnnhyyRGVG+ email: [email protected]customer_note:currency: USDlocale: en@@ -9475,8 +8856,8 @@ paths:variant_id: variant_UkLWZg9DAJquantity: 1currency: USD- name: Product 1662543- slug: product-1662543+ name: Product 1567335+ slug: product-1567335options_text: ''price: '10.0'display_price: "$10.00"@@ -9501,7 +8882,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H00399261907+ number: H34150382243tracking: U10000tracking_url:cost: '100.0'@@ -9530,7 +8911,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Ermelinda Trantow+ name: Kylee Jonesaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -9562,7 +8943,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 325 Lovely Street+ address1: 323 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -9581,7 +8962,7 @@ paths:first_name: Johnlast_name: Doefull_name: John Doe- address1: 326 Lovely Street+ address1: 324 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -9660,7 +9041,7 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: qKXFEJg674GQFMJdhX4aP21s+ token: NtdmeixQzCBf9oTPYdxpf9Svis_default: falseis_private: truemeta:@@ -9736,7 +9117,7 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: L23Wwbu1VdwURuQb3d9QhNo3+ token: 8cXeJyppojDAcyKGtrqEhahvis_default: falseis_private: trueschema:@@ -9832,7 +9213,7 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: vnMGJpfADtGcEPdtKSfeNcMf+ token: 7kZxgV92WcKPHpXSc1Cn695Lis_default: falseis_private: trueschema:@@ -9894,7 +9275,7 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: 4SxcHcYqoPne3UnSxaWTyemQ+ token: zTmZe61pQGipm76nbGax6Wiiis_default: falseis_private: trueschema:@@ -10009,7 +9390,7 @@ paths:variant:id: variant_gbHJdmfrXBproduct_id: prod_gbHJdmfrXB- sku: SKU-206+ sku: SKU-191options_text: ''track_inventory: truemedia_count: 0@@ -10357,11 +9738,11 @@ components:properties:item_id:type: string- description: Line item prefixed ID+ description: Line item IDexample: li_abc123variant_id:type: string- description: Variant prefixed ID+ description: Variant IDexample: variant_abc123quantity:type: integerdiff --git a/docs/docs.json b/docs/docs.jsonindex 318e5a386e..22e41a421d 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -500,6 +500,29 @@}]},+ {+ "item": "Admin API",+ "icon": "shield",+ "description": "REST API for pragmatically managing stores",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/admin-api/introduction",+ "api-reference/admin-api/authentication",+ "api-reference/admin-api/errors",+ "api-reference/admin-api/querying"+ ]+ },+ {+ "group": "Endpoints",+ "openapi": {+ "source": "api-reference/admin.yaml",+ "directory": "api-reference/admin-api"+ }+ }+ ]+ },{"item": "Webhooks","icon": "webhook",diff --git a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rbindex fac6495183..fda47cf260 100644--- a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb@@ -62,7 +62,7 @@ module Spree:name, :description, :slug, :status,:available_on, :discontinue_on, :make_active_at,:meta_title, :meta_description, :meta_keywords,- :tax_category_id, :shipping_category_id,+ :tax_category_id,:promotionable, :digital,# Master-variant convenience fields (forwarded to master variant):sku, :barcode, :price, :compare_at_price,diff --git a/spree/api/lib/spree/api/openapi/schema_helper.rb b/spree/api/lib/spree/api/openapi/schema_helper.rbindex 648142c693..3efc17325c 100644--- a/spree/api/lib/spree/api/openapi/schema_helper.rb+++ b/spree/api/lib/spree/api/openapi/schema_helper.rb@@ -130,8 +130,8 @@ module Spreetype: :object,description: 'An item within a fulfillment — which line item and how many units are in this fulfillment',properties: {- item_id: { type: :string, description: 'Line item prefixed ID', example: 'li_abc123' },- variant_id: { type: :string, description: 'Variant prefixed ID', example: 'variant_abc123' },+ item_id: { type: :string, description: 'Line item ID', example: 'li_abc123' },+ variant_id: { type: :string, description: 'Variant ID', example: 'variant_abc123' },quantity: { type: :integer, description: 'Quantity in this fulfillment', example: 2 }},required: %w[item_id variant_id quantity]diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rbindex 752c68d7b7..e9dbf19176 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb@@ -154,14 +154,13 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller dobefore { request.headers.merge!(headers) }let(:tax_category) { create(:tax_category) }- let(:shipping_category) { create(:shipping_category) }let(:taxonomy) { create(:taxonomy, store: store) }let(:category1) { create(:taxon, taxonomy: taxonomy) }let(:category2) { create(:taxon, taxonomy: taxonomy) }it 'creates a minimal product' doexpect {- post :create, params: { name: 'Simple Product', price: 19.99, shipping_category_id: shipping_category.id }, as: :json+ post :create, params: { name: 'Simple Product', price: 19.99 }, as: :json}.to change(Spree::Product, :count).by(1)expect(response).to have_http_status(:created)@@ -176,7 +175,6 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller dostatus: 'draft',cost_price: 8.50,sku: 'PREM-TEE',- shipping_category_id: shipping_category.id,tax_category_id: tax_category.prefixed_id,category_ids: [category1.prefixed_id, category2.prefixed_id],tags: ['premium', 'cotton', 'summer'],diff --git a/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rbindex fc4f3c6d05..e69de29bb2 100644--- a/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/auth_spec.rb@@ -1,129 +0,0 @@-# frozen_string_literal: true--require 'swagger_helper'--RSpec.describe 'Admin Authentication API', type: :request, swagger_doc: 'api-reference/admin.yaml' do- include_context 'API v3 Admin'-- let(:existing_admin) { create(:admin_user, password: 'password123', password_confirmation: 'password123') }-- path '/api/v3/admin/auth/login' do- post 'Login' do- tags 'Authentication'- consumes 'application/json'- produces 'application/json'- security [api_key: []]- description 'Authenticates an admin user with email/password and returns a JWT token'-- sdk_example <<~JS- const auth = await client.admin.auth.login({- email: '[email protected]',- password: 'password123',- })- JS-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- provider: { type: :string, example: 'email', description: 'Authentication provider (default: email)' },- email: { type: :string, format: 'email', example: '[email protected]' },- password: { type: :string, example: 'password123' }- },- required: %w[email password]- }-- response '200', 'login successful' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:body) { { email: existing_admin.email, password: 'password123' } }-- schema '$ref' => '#/components/schemas/AuthResponse'-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['token']).to be_present- expect(data['user']).to be_present- expect(data['user']['email']).to eq(existing_admin.email)- end- end-- response '401', 'invalid credentials' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:body) { { email: existing_admin.email, password: 'wrong_password' } }-- schema '$ref' => '#/components/schemas/ErrorResponse'-- run_test!- end-- response '401', 'user not found' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:body) { { email: '[email protected]', password: 'password123' } }-- schema '$ref' => '#/components/schemas/ErrorResponse'-- run_test!- end-- response '401', 'non-admin user' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:regular_user) { create(:user, password: 'password123', password_confirmation: 'password123') }- let(:body) { { email: regular_user.email, password: 'password123' } }-- schema '$ref' => '#/components/schemas/ErrorResponse'-- run_test!- end- end- end-- path '/api/v3/admin/auth/refresh' do- post 'Refresh token' do- tags 'Authentication'- consumes 'application/json'- produces 'application/json'- security [api_key: []]- description 'Rotates a refresh token and returns a new JWT access token'-- sdk_example <<~JS- const auth = await client.admin.auth.refresh({- refresh_token: 'rt_xxx',- })- JS-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- refresh_token: { type: :string, description: 'Refresh token obtained from login' }- },- required: %w[refresh_token]- }-- response '200', 'token refreshed' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:refresh_token) { Spree::RefreshToken.create_for(admin_user, request_env: { ip_address: '127.0.0.1', user_agent: 'test' }) }- let(:body) { { refresh_token: refresh_token.token } }-- schema '$ref' => '#/components/schemas/AuthResponse'-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['token']).to be_present- expect(data['refresh_token']).to be_present- expect(data['user']).to be_present- expect(data['user']['email']).to eq(admin_user.email)- end- end-- response '401', 'missing or invalid refresh token' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:body) { { refresh_token: 'invalid_token' } }-- schema '$ref' => '#/components/schemas/ErrorResponse'-- run_test!- end- end- end-enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/customers/addresses_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers/addresses_spec.rbindex f3edc786f1..70ffd37e15 100644--- a/spree/api/spec/integration/spree/api/v3/admin/customers/addresses_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/customers/addresses_spec.rb@@ -15,10 +15,15 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'apilet(:customer_id) { customer.prefixed_id }get 'List customer addresses' do- tags 'Customer Addresses'+ tags 'Customers'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns the customer\'s saved addresses.'+ admin_scope :read, :customers++ admin_sdk_example <<~JS+ const { data: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -35,11 +40,27 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'apiendpost 'Create a customer address' do- tags 'Customer Addresses'+ tags 'Customers'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Adds a new address to the customer\'s address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ const address = await client.customers.addresses.create('cus_UkLWZg9DAJ', {+ first_name: 'Jane',+ last_name: 'Doe',+ address1: '350 Fifth Avenue',+ city: 'New York',+ postal_code: '10118',+ country_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ label: 'Office',+ is_default_shipping: true,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -87,10 +108,20 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'apilet(:id) { address.prefixed_id }patch 'Update a customer address' do- tags 'Customer Addresses'+ tags 'Customers'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]+ description 'Updates a customer address.'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ const address = await client.customers.addresses.update(+ 'cus_UkLWZg9DAJ',+ 'addr_UkLWZg9DAJ',+ { city: 'Manhattan' },+ )+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -117,9 +148,14 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'apienddelete 'Delete a customer address' do- tags 'Customer Addresses'+ tags 'Customers'security [api_key: [], bearer_auth: []]description 'Deletes the address. If it was a default, the customer loses that default (no auto-promotion).'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: truediff --git a/spree/api/spec/integration/spree/api/v3/admin/customers/credit_cards_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers/credit_cards_spec.rbindex f0dec328b0..f4afac6841 100644--- a/spree/api/spec/integration/spree/api/v3/admin/customers/credit_cards_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/customers/credit_cards_spec.rb@@ -14,10 +14,15 @@ RSpec.describe 'Admin Customer Credit Cards API', type: :request, swagger_doc: 'let(:customer_id) { customer.prefixed_id }get 'List customer credit cards' do- tags 'Customer Credit Cards'+ tags 'Customers'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns the customer\'s saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.'+ admin_scope :read, :customers++ admin_sdk_example <<~JS+ const { data: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -39,9 +44,15 @@ RSpec.describe 'Admin Customer Credit Cards API', type: :request, swagger_doc: 'let(:id) { credit_card.prefixed_id }get 'Show a customer credit card' do- tags 'Customer Credit Cards'+ tags 'Customers'produces 'application/json'security [api_key: [], bearer_auth: []]+ description 'Returns a saved credit card by ID.'+ admin_scope :read, :customers++ admin_sdk_example <<~JS+ const card = await client.customers.creditCards.get('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -59,8 +70,14 @@ RSpec.describe 'Admin Customer Credit Cards API', type: :request, swagger_doc: 'enddelete 'Delete a customer credit card' do- tags 'Customer Credit Cards'+ tags 'Customers'security [api_key: [], bearer_auth: []]+ description 'Deletes a saved credit card.'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: truediff --git a/spree/api/spec/integration/spree/api/v3/admin/customers/store_credits_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers/store_credits_spec.rbindex 71496cd6f1..c91a5c8c4a 100644--- a/spree/api/spec/integration/spree/api/v3/admin/customers/store_credits_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/customers/store_credits_spec.rb@@ -14,9 +14,15 @@ RSpec.describe 'Admin Customer Store Credits API', type: :request, swagger_doc:let(:customer_id) { customer.prefixed_id }get 'List customer store credits' do- tags 'Customer Store Credits'+ tags 'Customers'produces 'application/json'security [api_key: [], bearer_auth: []]+ description 'Returns store credits issued to the customer.'+ admin_scope :read, :store_credits++ admin_sdk_example <<~JS+ const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -33,11 +39,21 @@ RSpec.describe 'Admin Customer Store Credits API', type: :request, swagger_doc:endpost 'Issue a store credit to a customer' do- tags 'Customer Store Credits'+ tags 'Customers'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description '`created_by` is set automatically from the authenticated admin.'+ admin_scope :write, :store_credits++ admin_sdk_example <<~JS+ const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {+ amount: 25.00,+ currency: 'USD',+ category_id: 1,+ memo: 'Goodwill credit',+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -71,11 +87,20 @@ RSpec.describe 'Admin Customer Store Credits API', type: :request, swagger_doc:let(:id) { store_credit.prefixed_id }patch 'Update a store credit' do- tags 'Customer Store Credits'+ tags 'Customers'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Update memo / category / amount. The amount can only be changed if `amount_used == 0`.'+ admin_scope :write, :store_credits++ admin_sdk_example <<~JS+ const credit = await client.customers.storeCredits.update(+ 'cus_UkLWZg9DAJ',+ 'sc_UkLWZg9DAJ',+ { memo: 'Reissued for damaged shipment' },+ )+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -101,9 +126,14 @@ RSpec.describe 'Admin Customer Store Credits API', type: :request, swagger_doc:enddelete 'Delete a store credit' do- tags 'Customer Store Credits'+ tags 'Customers'security [api_key: [], bearer_auth: []]description 'Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.'+ admin_scope :write, :store_credits++ admin_sdk_example <<~JS+ await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: truediff --git a/spree/api/spec/integration/spree/api/v3/admin/customers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers_spec.rbindex ccc60bc023..ad8597b431 100644--- a/spree/api/spec/integration/spree/api/v3/admin/customers_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/customers_spec.rb@@ -14,6 +14,15 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referencproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns a paginated list of customers. Supports Ransack search/filters.'+ admin_scope :read, :customers++ admin_sdk_example <<~JS+ const { data: customers } = await client.customers.list({+ search: 'jane',+ sort: '-created_at',+ limit: 25,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -39,6 +48,18 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referencproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Creates a customer. No welcome email is sent automatically.'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ const customer = await client.customers.create({+ email: '[email protected]',+ first_name: 'Jane',+ last_name: 'Doe',+ phone: '+1 212 555 1234',+ tags: ['wholesale'],+ accepts_email_marketing: true,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -77,11 +98,18 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referencproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).'+ admin_scope :read, :customers++ admin_sdk_example <<~JS+ const customer = await client.customers.get('cus_UkLWZg9DAJ', {+ expand: ['addresses', 'store_credits'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: trueparameter name: :id, in: :path, type: :string, required: true,- description: 'Customer prefixed ID'+ description: 'Customer ID'parameter name: :expand, in: :query, type: :string, required: false,description: 'Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address'@@ -102,6 +130,14 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referencproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates customer attributes. `tags` replaces the full set.'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ const customer = await client.customers.update('cus_UkLWZg9DAJ', {+ first_name: 'Updated',+ tags: ['wholesale', 'vip'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -135,6 +171,11 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referenctags 'Customers'security [api_key: [], bearer_auth: []]description 'Deletes a customer. Returns 422 if the customer has any orders.'+ admin_scope :write, :customers++ admin_sdk_example <<~JS+ await client.customers.delete('cus_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: truediff --git a/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/me_spec.rbindex 754e86c05d..e6b3be0d57 100644--- a/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb@@ -12,10 +12,10 @@ RSpec.describe 'Admin Me API', type: :request, swagger_doc: 'api-reference/adminsecurity [api_key: [], bearer_auth: []]description 'Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.'- sdk_example <<~JS- const me = await client.admin.me.show()+ admin_sdk_example <<~JS+ const me = await client.me.show()if (me.permissions.some((r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'))) {- // show create product button+ // show "Create product" button}JSdiff --git a/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rbindex c660329ab5..cf5f1ff022 100644--- a/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rb@@ -10,10 +10,15 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-referpath '/api/v3/admin/option_types' doget 'List option types' do- tags 'Option Types'+ tags 'Product Catalog'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns a paginated list of option types.'+ admin_scope :read, :products++ admin_sdk_example <<~JS+ const { data: optionTypes } = await client.optionTypes.list()+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -46,7 +51,7 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-referendpost 'Create an option type' do- tags 'Option Types'+ tags 'Product Catalog'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]@@ -55,6 +60,18 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-referOption values can be provided inline and will be created or updated by name.DESC+ admin_scope :write, :products++ admin_sdk_example <<~JS+ const optionType = await client.optionTypes.create({+ name: 'color',+ presentation: 'Color',+ option_values: [+ { name: 'red', presentation: 'Red' },+ { name: 'navy', presentation: 'Navy' },+ ],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -107,15 +124,20 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-referpath '/api/v3/admin/option_types/{id}' doget 'Get an option type' do- tags 'Option Types'+ tags 'Product Catalog'produces 'application/json'security [api_key: [], bearer_auth: []]- description 'Returns a single option type by prefixed ID, including its option values.'+ description 'Returns a single option type by ID, including its option values.'+ admin_scope :read, :products++ admin_sdk_example <<~JS+ const optionType = await client.optionTypes.get('ot_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :id, in: :path, type: :string, required: true, description: 'Option type prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Option type ID'response '200', 'option type found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -140,16 +162,26 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-referendpatch 'Update an option type' do- tags 'Option Types'+ tags 'Product Catalog'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates an option type. Supports updating nested option values.'+ admin_scope :write, :products++ admin_sdk_example <<~JS+ const optionType = await client.optionTypes.update('ot_UkLWZg9DAJ', {+ presentation: 'Updated Presentation',+ option_values: [+ { name: 'red', presentation: 'Crimson' },+ ],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :id, in: :path, type: :string, required: true, description: 'Option type prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Option type ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -197,14 +229,19 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-referenddelete 'Delete an option type' do- tags 'Option Types'+ tags 'Product Catalog'security [api_key: [], bearer_auth: []]description 'Deletes an option type.'+ admin_scope :write, :products++ admin_sdk_example <<~JS+ await client.optionTypes.delete('ot_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :id, in: :path, type: :string, required: true, description: 'Option type prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Option type ID'response '204', 'option type deleted' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rbdeleted file mode 100644index 218ff6f7d6..0000000000--- a/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb+++ /dev/null@@ -1,70 +0,0 @@-# frozen_string_literal: true--require 'swagger_helper'--# NOTE: This spec exercises the API but is excluded from the OpenAPI doc until 6.0-# typed adjustments split (TaxLine/Discount/Fee) is finalized.-# See docs/plans/6.0-split-adjustments.md.-RSpec.describe 'Admin Order Adjustments API', type: :request do- include_context 'API v3 Admin'-- let!(:order) { create(:order, store: store, state: 'cart') }- let!(:adjustment) { create(:adjustment, adjustable: order, order: order, amount: 5.00, label: 'Admin discount') }- let(:Authorization) { "Bearer #{admin_jwt_token}" }-- path '/api/v3/admin/orders/{order_id}/adjustments' do- let(:order_id) { order.prefixed_id }-- get 'List adjustments' do- tags 'Adjustments'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Returns all adjustments for an order. Read-only — adjustments are computed from promotions, taxes, and fees.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'-- response '200', 'adjustments found' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['data']).to be_an(Array)- expect(data['data'].length).to be >= 1- end- end- end- end-- path '/api/v3/admin/orders/{order_id}/adjustments/{id}' do- let(:order_id) { order.prefixed_id }- let(:id) { adjustment.prefixed_id }-- get 'Show an adjustment' do- tags 'Adjustments'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Returns details of a specific adjustment.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'- parameter name: :id, in: :path, type: :string, required: true,- description: 'Adjustment prefixed ID'-- response '200', 'adjustment found' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['id']).to eq(adjustment.prefixed_id)- end- end- end- end-enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rbindex 45c76ac6cf..cccf645f70 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb@@ -13,16 +13,21 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apilet(:order_id) { order.prefixed_id }get 'List fulfillments' do- tags 'Fulfillments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns all shipments for an order.'+ admin_scope :read, :fulfillments++ admin_sdk_example <<~JS+ const { data: fulfillments } = await client.orders.fulfillments.list('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'fulfillments found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -41,18 +46,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apilet(:id) { shipment.prefixed_id }get 'Show a shipment' do- tags 'Fulfillments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns details of a specific shipment.'+ admin_scope :read, :fulfillments++ admin_sdk_example <<~JS+ const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Fulfillment prefixed ID'+ description: 'Fulfillment ID'response '200', 'shipment found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -66,19 +76,26 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apiendpatch 'Update a shipment' do- tags 'Fulfillments'+ tags 'Orders'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates a shipment (tracking, shipping rate).'+ admin_scope :write, :fulfillments++ admin_sdk_example <<~JS+ const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {+ tracking: '1Z999AA10123456784',+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Fulfillment prefixed ID'+ description: 'Fulfillment ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -101,18 +118,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apipath '/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill' dopatch 'Fulfill a fulfillment' do- tags 'Fulfillments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Marks a fulfillment as fulfilled.'+ admin_scope :write, :fulfillments++ admin_sdk_example <<~JS+ const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Fulfillment prefixed ID'+ description: 'Fulfillment ID'response '200', 'fulfillment fulfilled' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -133,18 +155,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apipath '/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel' dopatch 'Cancel a fulfillment' do- tags 'Fulfillments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Cancels a fulfillment.'+ admin_scope :write, :fulfillments++ admin_sdk_example <<~JS+ const fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Fulfillment prefixed ID'+ description: 'Fulfillment ID'response '200', 'fulfillment canceled' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -161,18 +188,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apipath '/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume' dopatch 'Resume a fulfillment' do- tags 'Fulfillments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Resumes a canceled fulfillment.'+ admin_scope :write, :fulfillments++ admin_sdk_example <<~JS+ const fulfillment = await client.orders.fulfillments.resume('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Fulfillment prefixed ID'+ description: 'Fulfillment ID'response '200', 'fulfillment resumed' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -193,26 +225,33 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'apipath '/api/v3/admin/orders/{order_id}/fulfillments/{id}/split' dopatch 'Split a fulfillment' do- tags 'Fulfillments'+ tags 'Orders'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Transfers items from this shipment to a new shipment at a different stock location.'+ admin_scope :write, :fulfillments++ admin_sdk_example <<~JS+ const fulfillment = await client.orders.fulfillments.split('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {+ quantity: 1,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Fulfillment prefixed ID'+ description: 'Fulfillment ID'parameter name: :body, in: :body, schema: {type: :object,required: %w[variant_id quantity],properties: {- variant_id: { type: :string, description: 'Variant prefixed ID' },+ variant_id: { type: :string, description: 'Variant ID' },quantity: { type: :integer, example: 1 },- stock_location_id: { type: :string, description: 'Target stock location prefixed ID' }+ stock_location_id: { type: :string, description: 'Target stock location ID' }}}diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rbindex c65be28373..54ab9e2118 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/gift_cards_spec.rb@@ -14,17 +14,24 @@ RSpec.describe 'Admin Order Gift Cards API', type: :request, swagger_doc: 'api-rlet(:order_id) { order.prefixed_id }post 'Apply a gift card to an order' do- tags 'Order Gift Cards'+ tags 'Orders'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Applies a gift card by code to the order. Returns the gift card.'+ admin_scope :write, :gift_cards++ admin_sdk_example <<~JS+ await client.orders.giftCards.apply('or_UkLWZg9DAJ', {+ code: 'GIFT-XXXX-YYYY',+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :body, in: :body, schema: {type: :object,required: %w[code],@@ -50,17 +57,22 @@ RSpec.describe 'Admin Order Gift Cards API', type: :request, swagger_doc: 'api-rlet(:id) { gift_card.prefixed_id }delete 'Remove a gift card from an order' do- tags 'Order Gift Cards'+ tags 'Orders'security [api_key: [], bearer_auth: []]description 'Removes the gift card from the order.'+ admin_scope :write, :gift_cards++ admin_sdk_example <<~JS+ await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Gift card prefixed ID'+ description: 'Gift card ID'response '204', 'gift card removed' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rbindex 58cf3bf317..1369741846 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/items_spec.rb@@ -19,12 +19,17 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-rproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns all line items for an order.'+ admin_scope :read, :orders++ admin_sdk_example <<~JS+ const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'items found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -43,12 +48,20 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-rproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Adds a new line item to the order.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ const item = await client.orders.items.create('or_UkLWZg9DAJ', {+ variant_id: 'variant_k5nR8xLq',+ quantity: 2,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :body, in: :body, schema: {type: :object,required: %w[variant_id],@@ -80,14 +93,19 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-rproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns details of a specific line item.'+ admin_scope :read, :orders++ admin_sdk_example <<~JS+ const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Item prefixed ID'+ description: 'Item ID'response '200', 'item found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -105,14 +123,21 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-rproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates an order item quantity or metadata.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {+ quantity: 5,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Item prefixed ID'+ description: 'Item ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -135,14 +160,19 @@ RSpec.describe 'Admin Order Line Items API', type: :request, swagger_doc: 'api-rtags 'Orders'security [api_key: [], bearer_auth: []]description 'Removes an item from the order.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Item prefixed ID'+ description: 'Item ID'response '204', 'line item removed' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rbindex 97b744797b..33521b679b 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb@@ -13,16 +13,21 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-reflet(:order_id) { order.prefixed_id }get 'List payments' do- tags 'Payments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns all payments for an order.'+ admin_scope :read, :payments++ admin_sdk_example <<~JS+ const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'payments found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -36,24 +41,33 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-refendpost 'Create a payment' do- tags 'Payments'+ tags 'Orders'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Creates a new payment for the order.'+ admin_scope :write, :payments++ admin_sdk_example <<~JS+ const payment = await client.orders.payments.create('or_UkLWZg9DAJ', {+ payment_method_id: 'pm_UkLWZg9DAJ',+ amount: 99.99,+ source_id: 'cc_UkLWZg9DAJ',+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :body, in: :body, schema: {type: :object,required: %w[payment_method_id],properties: {- payment_method_id: { type: :string, description: 'Payment method prefixed ID' },+ payment_method_id: { type: :string, description: 'Payment method ID' },amount: { type: :number, example: 99.99 },- source_id: { type: :string, description: 'Payment source prefixed ID' }+ source_id: { type: :string, description: 'Payment source ID' }}}@@ -77,18 +91,23 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-reflet(:id) { payment.prefixed_id }get 'Show a payment' do- tags 'Payments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns details of a specific payment.'+ admin_scope :read, :payments++ admin_sdk_example <<~JS+ const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Payment prefixed ID'+ description: 'Payment ID'response '200', 'payment found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -103,18 +122,23 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-refpath '/api/v3/admin/orders/{order_id}/payments/{id}/capture' dopatch 'Capture a payment' do- tags 'Payments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Captures a pending payment.'+ admin_scope :write, :payments++ admin_sdk_example <<~JS+ const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Payment prefixed ID'+ description: 'Payment ID'response '200', 'payment captured' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -135,18 +159,23 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-refpath '/api/v3/admin/orders/{order_id}/payments/{id}/void' dopatch 'Void a payment' do- tags 'Payments'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Voids a payment.'+ admin_scope :write, :payments++ admin_sdk_example <<~JS+ const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :id, in: :path, type: :string, required: true,- description: 'Payment prefixed ID'+ description: 'Payment ID'response '200', 'payment voided' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rbindex 7e740e1bc4..a2b796fa9d 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb@@ -14,16 +14,21 @@ RSpec.describe 'Admin Order Refunds API', type: :request, swagger_doc: 'api-refelet(:order_id) { order.prefixed_id }get 'List refunds' do- tags 'Refunds'+ tags 'Orders'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns all refunds for an order.'+ admin_scope :read, :refunds++ admin_sdk_example <<~JS+ const { data: refunds } = await client.orders.refunds.list('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'refunds found' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -36,24 +41,33 @@ RSpec.describe 'Admin Order Refunds API', type: :request, swagger_doc: 'api-refeendpost 'Create a refund' do- tags 'Refunds'+ tags 'Orders'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.'+ admin_scope :write, :refunds++ admin_sdk_example <<~JS+ const refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {+ payment_id: 'pay_UkLWZg9DAJ',+ amount: 5.00,+ refund_reason_id: 'refrsn_UkLWZg9DAJ',+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :body, in: :body, schema: {type: :object,required: %w[payment_id amount],properties: {- payment_id: { type: :string, description: 'Payment prefixed ID' },+ payment_id: { type: :string, description: 'Payment ID' },amount: { type: :number, example: 10.00 },- refund_reason_id: { type: :string, description: 'Refund reason prefixed ID' }+ refund_reason_id: { type: :string, description: 'Refund reason ID' }}}diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rbindex 56c628925b..047b4a3461 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/store_credits_spec.rb@@ -15,18 +15,25 @@ RSpec.describe 'Admin Order Store Credits API', type: :request, swagger_doc: 'aplet(:order_id) { order.prefixed_id }post "Apply customer's store credit to an order" do- tags 'Order Store Credits'+ tags 'Orders'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Applies the order customer\'s available store credit. ' \'When `amount` is omitted, applies up to the order outstanding balance.'+ admin_scope :write, :store_credits++ admin_sdk_example <<~JS+ const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {+ amount: 25.00,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -46,15 +53,20 @@ RSpec.describe 'Admin Order Store Credits API', type: :request, swagger_doc: 'apenddelete "Remove store credit from an order" do- tags 'Order Store Credits'+ tags 'Orders'security [api_key: [], bearer_auth: []]description "Removes any applied store credit from the order."+ admin_scope :write, :store_credits++ admin_sdk_example <<~JS+ await client.orders.storeCredits.remove('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :order_id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '204', 'store credit removed' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rbindex 3d895916fa..0d63d98af8 100644--- a/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/orders_spec.rb@@ -14,6 +14,16 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns a paginated list of orders for the current store.'+ admin_scope :read, :orders++ admin_sdk_example <<~JS+ const { data: orders, meta } = await client.orders.list({+ status_eq: 'complete',+ completed_at_gt: '2026-01-01',+ sort: '-completed_at',+ limit: 25,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -56,6 +66,65 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aconsumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]++ admin_sdk_example <<~JS+ // One-shot order create: customer, items, addresses, market, notes,+ // metadata, and a coupon code in a single call. Everything except+ // `email` is optional.+ const order = await client.orders.create({+ email: '[email protected]',+ customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders+ use_customer_default_address: false, // true to copy the customer's saved addresses++ currency: 'USD',+ market_id: 'mkt_UkLWZg9DAJ',+ locale: 'en-US',++ customer_note: 'Please leave at the front desk.',+ internal_note: 'VIP customer — handle with care.',+ metadata: {+ external_reference: 'subscription_invoice_2026_04',+ source: 'recurring-engine',+ },++ // Items: each variant_id + quantity. Optional metadata per line.+ items: [+ { variant_id: 'variant_k5nR8xLq', quantity: 2 },+ { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },+ ],++ // Provide addresses inline OR by ID (existing customer addresses).+ shipping_address: {+ first_name: 'Jane',+ last_name: 'Doe',+ address1: '350 Fifth Avenue',+ address2: 'Floor 42',+ city: 'New York',+ postal_code: '10118',+ country_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ company: 'Acme Inc.',+ },+ // shipping_address_id: 'addr_UkLWZg9DAJ', // alternative to inline++ billing_address: {+ first_name: 'Jane',+ last_name: 'Doe',+ address1: '350 Fifth Avenue',+ city: 'New York',+ postal_code: '10118',+ country_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ },+ // billing_address_id: 'addr_UkLWZg9DAJ',++ // Optional. Invalid codes are non-fatal — the order is created either way.+ coupon_code: 'WELCOME10',+ })+ JS+description <<~DESCCreates a new draft order in one shot. Customer, items, addresses, currency,market, locale, notes, metadata, and a coupon code can all be provided inline.@@ -63,6 +132,7 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aInvalid coupon codes are non-fatal — the order is created and the failureis reported on the service result (not in the API response body for now).DESC+ admin_scope :write, :ordersparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -71,10 +141,10 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/atype: :object,properties: {email: { type: :string, example: '[email protected]' },- customer_id: { type: :string, description: 'Customer prefixed ID. Alias: user_id (legacy).' },+ customer_id: { type: :string, description: 'Customer ID. Alias: user_id (legacy).' },use_customer_default_address: { type: :boolean, description: "When true with customer_id, copies the customer's saved billing/shipping addresses onto the order." },currency: { type: :string, example: 'USD' },- market_id: { type: :string, description: 'Market prefixed ID' },+ market_id: { type: :string, description: 'Market ID' },locale: { type: :string, example: 'en-US' },customer_note: { type: :string, description: 'Public, customer-visible note' },internal_note: { type: :string, description: 'Staff-only note' },@@ -88,7 +158,7 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/astate_abbr: { type: :string }, phone: { type: :string }}},- shipping_address_id: { type: :string, description: 'Existing customer address prefixed ID' },+ shipping_address_id: { type: :string, description: 'Existing customer address ID' },billing_address: {type: :object,properties: {@@ -98,14 +168,14 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/astate_abbr: { type: :string }, phone: { type: :string }}},- billing_address_id: { type: :string, description: 'Existing customer address prefixed ID' },+ billing_address_id: { type: :string, description: 'Existing customer address ID' },items: {type: :array,items: {type: :object,required: %w[variant_id quantity],properties: {- variant_id: { type: :string, description: 'Variant prefixed ID' },+ variant_id: { type: :string, description: 'Variant ID' },quantity: { type: :integer, example: 1 },metadata: { type: :object }}@@ -135,12 +205,19 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns full order details including admin-only fields.'+ admin_scope :read, :orders++ admin_sdk_example <<~JS+ const order = await client.orders.get('or_UkLWZg9DAJ', {+ expand: ['items', 'fulfillments', 'payments', 'customer'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID (e.g., or_xxx)'+ description: 'Order ID (e.g., or_xxx)'parameter name: :expand, in: :query, type: :string, required: false,description: 'Comma-separated associations to expand (e.g., user)'@@ -169,12 +246,20 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates an order. Supports updating email, addresses, special instructions, and line items.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ const order = await client.orders.update('or_UkLWZg9DAJ', {+ email: '[email protected]',+ internal_note: 'VIP — gift wrap on next order',+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -213,7 +298,7 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/atype: :object,required: %w[variant_id],properties: {- variant_id: { type: :string, description: 'Variant prefixed ID' },+ variant_id: { type: :string, description: 'Variant ID' },quantity: { type: :integer, example: 1 },metadata: { type: :object }}@@ -237,12 +322,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/atags 'Orders'security [api_key: [], bearer_auth: []]description 'Deletes a draft order. Completed orders cannot be deleted.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ await client.orders.delete('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '204', 'order deleted' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -258,12 +348,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Cancels a completed order.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ const order = await client.orders.cancel('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'order canceled' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -281,12 +376,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Approves an order (e.g., for fraud review).'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ const order = await client.orders.approve('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'order approved' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -307,12 +407,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Resumes a previously canceled order.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ const order = await client.orders.resume('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'order resumed' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }@@ -334,12 +439,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/aproduces 'application/json'security [api_key: [], bearer_auth: []]description 'Publishes the order.completed event to trigger confirmation email delivery.'+ admin_scope :write, :orders++ admin_sdk_example <<~JS+ await client.orders.resendConfirmation('or_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'parameter name: :id, in: :path, type: :string, required: true,- description: 'Order prefixed ID'+ description: 'Order ID'response '200', 'confirmation resent' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/payment_methods_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/payment_methods_spec.rbindex 40d0a250f5..94c12cde27 100644--- a/spree/api/spec/integration/spree/api/v3/admin/payment_methods_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/payment_methods_spec.rb@@ -10,10 +10,15 @@ RSpec.describe 'Admin Payment Methods API', type: :request, swagger_doc: 'api-repath '/api/v3/admin/payment_methods' doget 'List payment methods' do- tags 'Payment Methods'+ tags 'Configuration'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns the store\'s configured payment methods. Use `source_required: true` to know which methods need a saved source.'+ admin_scope :read, :settings++ admin_sdk_example <<~JS+ const { data: paymentMethods } = await client.paymentMethods.list()+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true@@ -33,9 +38,15 @@ RSpec.describe 'Admin Payment Methods API', type: :request, swagger_doc: 'api-relet(:id) { payment_method.prefixed_id }get 'Show a payment method' do- tags 'Payment Methods'+ tags 'Configuration'produces 'application/json'security [api_key: [], bearer_auth: []]+ description 'Returns a payment method by ID.'+ admin_scope :read, :settings++ admin_sdk_example <<~JS+ const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: truediff --git a/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rbdeleted file mode 100644index 4145663fba..0000000000--- a/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb+++ /dev/null@@ -1,134 +0,0 @@-# frozen_string_literal: true--require 'swagger_helper'--# NOTE: This spec exercises the API but is excluded from the OpenAPI doc until 6.0-# product media rework is finalized. See docs/plans/5.4-6.0-product-media-system.md.-RSpec.describe 'Admin Product Media API', type: :request do- include_context 'API v3 Admin'-- let!(:product) { create(:product, stores: [store]) }- let!(:image) { create(:image, viewable: product.master) }- let(:Authorization) { "Bearer #{admin_jwt_token}" }-- path '/api/v3/admin/products/{product_id}/media' do- get 'List product media' do- tags 'Product Media'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Returns a paginated list of media (images, video) for a product.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'- parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'-- response '200', 'media found' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['data']).to be_an(Array)- end- end- end-- post 'Create a product media item' do- tags 'Product Media'- consumes 'application/json'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Creates a new media item (image, video) for a product.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- alt: { type: :string, example: 'Product front view' },- position: { type: :integer, example: 1 },- type: { type: :string, example: 'Spree::Image', description: 'Media type (defaults to Spree::Image)' },- url: { type: :string, example: 'https://example.com/image.jpg', description: 'External URL to import image from (async). Returns 202 Accepted.' }- }- }-- response '202', 'media import from URL enqueued' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:body) { { url: 'https://example.com/image.jpg', position: 1 } }-- run_test!- end-- response '422', 'validation error (attachment required)' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:body) { { alt: 'New product image', position: 1 } }-- schema '$ref' => '#/components/schemas/ErrorResponse'-- run_test!- end- end- end-- path '/api/v3/admin/products/{product_id}/media/{id}' do- patch 'Update a product media item' do- tags 'Product Media'- consumes 'application/json'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Updates a product media item. Only provided fields are updated.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- alt: { type: :string, example: 'Updated alt text' },- position: { type: :integer, example: 2 }- }- }-- response '200', 'media updated' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:id) { image.prefixed_id }- let(:body) { { alt: 'Updated alt text' } }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['alt']).to eq('Updated alt text')- end- end- end-- delete 'Delete a product media item' do- tags 'Product Media'- security [api_key: [], bearer_auth: []]- description 'Deletes a media item from a product.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'-- response '204', 'media deleted' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:id) { image.prefixed_id }-- run_test!- end- end- end-enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/products_spec.rbindex aef2da9bc5..dc10ed3089 100644--- a/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb@@ -6,15 +6,24 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceinclude_context 'API v3 Admin'let!(:product) { create(:product, stores: [store]) }- let(:shipping_category) { create(:shipping_category) }let(:Authorization) { "Bearer #{admin_jwt_token}" }path '/api/v3/admin/products' doget 'List products' do- tags 'Products'+ tags 'Product Catalog'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns a paginated list of products for the current store.'+ admin_scope :read, :products++ admin_sdk_example <<~JS+ const { data: products } = await client.products.list({+ name_cont: 'shirt',+ status_eq: 'active',+ sort: '-created_at',+ limit: 25,+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -53,7 +62,7 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceendpost 'Create a product' do- tags 'Products'+ tags 'Product Catalog'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]@@ -63,6 +72,43 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceOption types and values are auto-created if they don't exist.Prices are upserted by currency. Stock items are upserted by stock location.DESC+ admin_scope :write, :products++ admin_sdk_example <<~JS+ const product = await client.products.create({+ name: 'Premium T-Shirt',+ price: 29.99,+ description: 'Soft, organic cotton.',+ status: 'active',+ variants: [+ {+ sku: 'TSHIRT-S-NAVY',+ options: [+ { name: 'size', value: 'Small' },+ { name: 'color', value: 'navy' },+ ],+ prices: [+ { currency: 'USD', amount: 29.99 },+ { currency: 'EUR', amount: 27.99 },+ ],+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 50 },+ ],+ },+ {+ sku: 'TSHIRT-M-NAVY',+ options: [+ { name: 'size', value: 'Medium' },+ { name: 'color', value: 'navy' },+ ],+ prices: [{ currency: 'USD', amount: 29.99 }],+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 30 },+ ],+ },+ ],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,@@ -76,42 +122,64 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceslug: { type: :string },status: { type: :string, enum: %w[draft active archived] },sku: { type: :string },- shipping_category_id: { type: :string, description: 'Prefixed ID (e.g., sc_xxx) or integer' },- tax_category_id: { type: :string, description: 'Prefixed ID or integer' },- taxon_ids: { type: :array, items: { type: :string }, description: 'Array of prefixed taxon IDs' },+ tax_category_id: { type: :string, description: 'Tax category ID' },+ category_ids: { type: :array, items: { type: :string }, description: 'Array of category IDs' },tags: { type: :array, items: { type: :string }, example: %w[eco sale] },variants: {type: :array,+ description: 'Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).',items: {type: :object,properties: {sku: { type: :string },- price: { type: :number },- option_type: { type: :string, example: 'Size' },- option_value: { type: :string, example: 'Small' },- total_on_hand: { type: :integer },+ options: {+ type: :array,+ description: 'One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.',+ items: {+ type: :object,+ required: %w[name value],+ properties: {+ name: { type: :string, example: 'size' },+ value: { type: :string, example: 'Small' }+ }+ }+ },prices: {type: :array,+ description: 'Per-currency prices. Upserted by currency.',items: {type: :object,+ required: %w[currency amount],properties: {currency: { type: :string, example: 'USD' },amount: { type: :number, example: 29.99 },compare_at_amount: { type: :number, example: 39.99 }- },- required: %w[currency amount]+ }+ }+ },+ stock_items: {+ type: :array,+ description: 'Per-stock-location inventory. Upserted by stock_location_id.',+ items: {+ type: :object,+ required: %w[stock_location_id count_on_hand],+ properties: {+ stock_location_id: { type: :string, description: 'Stock location ID (e.g. sloc_xxx)' },+ count_on_hand: { type: :integer, example: 50 },+ backorderable: { type: :boolean }+ }}}}}}},- required: %w[name price shipping_category_id]+ required: %w[name price]}response '201', 'product created' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:body) { { name: 'New Product', price: 19.99, shipping_category_id: shipping_category.id } }+ let(:body) { { name: 'New Product', price: 19.99 } }schema '$ref' => '#/components/schemas/Product'@@ -134,15 +202,22 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referencepath '/api/v3/admin/products/{id}' doget 'Get a product' do- tags 'Products'+ tags 'Product Catalog'produces 'application/json'security [api_key: [], bearer_auth: []]- description 'Returns a single product by prefixed ID.'+ description 'Returns a single product by ID.'+ admin_scope :read, :products++ admin_sdk_example <<~JS+ const product = await client.products.get('prod_86Rf07xd4z', {+ expand: ['variants', 'option_types'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :id, in: :path, type: :string, required: true, description: 'Product prefixed ID (e.g., prod_xxx)'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Product ID (e.g., prod_xxx)'parameter name: :expand, in: :query, type: :string, required: false,description: 'Comma-separated associations to expand (e.g., variants)'@@ -169,16 +244,25 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceendpatch 'Update a product' do- tags 'Products'+ tags 'Product Catalog'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates a product. Only provided fields are updated.'+ admin_scope :write, :products++ admin_sdk_example <<~JS+ const product = await client.products.update('prod_86Rf07xd4z', {+ name: 'Updated Name',+ status: 'active',+ tags: ['eco', 'sale'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Product ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -188,30 +272,52 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceslug: { type: :string },status: { type: :string, enum: %w[draft active archived] },sku: { type: :string },- shipping_category_id: { type: :string, description: 'Prefixed ID (e.g., sc_xxx) or integer' },- tax_category_id: { type: :string, description: 'Prefixed ID or integer' },- taxon_ids: { type: :array, items: { type: :string }, description: 'Array of prefixed taxon IDs' },+ tax_category_id: { type: :string, description: 'Tax category ID' },+ category_ids: { type: :array, items: { type: :string }, description: 'Array of category IDs' },tags: { type: :array, items: { type: :string }, example: %w[eco sale] },variants: {type: :array,+ description: 'Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).',items: {type: :object,properties: {sku: { type: :string },- price: { type: :number },- option_type: { type: :string, example: 'Size' },- option_value: { type: :string, example: 'Small' },- total_on_hand: { type: :integer },+ options: {+ type: :array,+ description: 'One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.',+ items: {+ type: :object,+ required: %w[name value],+ properties: {+ name: { type: :string, example: 'size' },+ value: { type: :string, example: 'Small' }+ }+ }+ },prices: {type: :array,+ description: 'Per-currency prices. Upserted by currency.',items: {type: :object,+ required: %w[currency amount],properties: {currency: { type: :string, example: 'USD' },amount: { type: :number, example: 29.99 },compare_at_amount: { type: :number, example: 39.99 }- },- required: %w[currency amount]+ }+ }+ },+ stock_items: {+ type: :array,+ description: 'Per-stock-location inventory. Upserted by stock_location_id.',+ items: {+ type: :object,+ required: %w[stock_location_id count_on_hand],+ properties: {+ stock_location_id: { type: :string, description: 'Stock location ID (e.g. sloc_xxx)' },+ count_on_hand: { type: :integer, example: 50 },+ backorderable: { type: :boolean }+ }}}}@@ -245,14 +351,19 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-referenceenddelete 'Delete a product' do- tags 'Products'+ tags 'Product Catalog'security [api_key: [], bearer_auth: []]description 'Soft-deletes a product.'+ admin_scope :write, :products++ admin_sdk_example <<~JS+ await client.products.delete('prod_86Rf07xd4z')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Product ID'response '204', 'product deleted' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/integration/spree/api/v3/admin/tags_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/tags_spec.rbindex 1865aa3afe..05116d8677 100644--- a/spree/api/spec/integration/spree/api/v3/admin/tags_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/tags_spec.rb@@ -9,11 +9,18 @@ RSpec.describe 'Admin Tags API', type: :request, swagger_doc: 'api-reference/admpath '/api/v3/admin/tags' doget 'List tags' do- tags 'Tags'+ tags 'Configuration'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.'+ admin_sdk_example <<~JS+ const { data: tags } = await client.tags.list({+ taggable_type: 'Spree::User',+ q: 'vip',+ })+ JS+parameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: trueparameter name: :taggable_type, in: :query, type: :string, required: true,diff --git a/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rbdeleted file mode 100644index 5a4f4ba1dd..0000000000--- a/spree/api/spec/integration/spree/api/v3/admin/variant_media_spec.rb+++ /dev/null@@ -1,146 +0,0 @@-# frozen_string_literal: true--require 'swagger_helper'--# NOTE: This spec exercises the API but is excluded from the OpenAPI doc until 6.0-# variant media rework is finalized. See docs/plans/5.4-6.0-product-media-system.md.-RSpec.describe 'Admin Variant Media API', type: :request do- include_context 'API v3 Admin'-- let!(:product) { create(:product, stores: [store]) }- let!(:variant) { create(:variant, product: product) }- let!(:variant_image) { create(:image, viewable: variant) }- let(:Authorization) { "Bearer #{admin_jwt_token}" }-- path '/api/v3/admin/products/{product_id}/variants/{variant_id}/media' do- get 'List variant media' do- tags 'Variant Media'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Returns a paginated list of media (images, video) for a variant.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :variant_id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'- parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'- parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'-- response '200', 'variant media found' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:variant_id) { variant.prefixed_id }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['data']).to be_an(Array)- ids = data['data'].map { |a| a['id'] }- expect(ids).to include(variant_image.prefixed_id)- end- end- end-- post 'Create a variant media item' do- tags 'Variant Media'- consumes 'application/json'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Creates a new media item (image, video) for a variant.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :variant_id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- alt: { type: :string, example: 'Variant image' },- position: { type: :integer, example: 1 },- type: { type: :string, example: 'Spree::Image', description: 'Media type (defaults to Spree::Image)' },- url: { type: :string, example: 'https://example.com/image.jpg', description: 'External URL to import image from (async). Returns 202 Accepted.' }- }- }-- response '202', 'variant media import from URL enqueued' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:variant_id) { variant.prefixed_id }- let(:body) { { url: 'https://example.com/variant.jpg', position: 1 } }-- run_test!- end-- response '422', 'validation error (attachment required)' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:variant_id) { variant.prefixed_id }- let(:body) { { alt: 'New variant image', position: 1 } }-- schema '$ref' => '#/components/schemas/ErrorResponse'-- run_test!- end- end- end-- path '/api/v3/admin/products/{product_id}/variants/{variant_id}/media/{id}' do- patch 'Update a variant media item' do- tags 'Variant Media'- consumes 'application/json'- produces 'application/json'- security [api_key: [], bearer_auth: []]- description 'Updates a variant media item. Only provided fields are updated.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :variant_id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- alt: { type: :string, example: 'Updated variant image' },- position: { type: :integer, example: 2 }- }- }-- response '200', 'variant media updated' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:variant_id) { variant.prefixed_id }- let(:id) { variant_image.prefixed_id }- let(:body) { { alt: 'Updated variant image' } }-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['alt']).to eq('Updated variant image')- end- end- end-- delete 'Delete a variant media item' do- tags 'Variant Media'- security [api_key: [], bearer_auth: []]- description 'Deletes a media item from a variant.'-- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true- parameter name: :Authorization, in: :header, type: :string, required: true,- description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :variant_id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Media prefixed ID'-- response '204', 'variant media deleted' do- let(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:product_id) { product.prefixed_id }- let(:variant_id) { variant.prefixed_id }- let(:id) { variant_image.prefixed_id }-- run_test!- end- end- end-enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rbindex ee4b1c47f4..275cd9a061 100644--- a/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb@@ -11,15 +11,22 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referencepath '/api/v3/admin/products/{product_id}/variants' doget 'List product variants' do- tags 'Variants'+ tags 'Product Catalog'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Returns a paginated list of variants for a product, including the master variant.'+ admin_scope :read, :products++ admin_sdk_example <<~JS+ const { data: variants } = await client.products.variants.list('prod_86Rf07xd4z', {+ expand: ['prices', 'stock_items'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product ID'parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'parameter name: :expand, in: :query, type: :string, required: false,@@ -37,7 +44,7 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referenceendpost 'Create a variant' do- tags 'Variants'+ tags 'Product Catalog'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]@@ -47,11 +54,29 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referenceOption types and values are auto-created if they don't exist.Prices are upserted by currency. Stock items are upserted by stock location.DESC+ admin_scope :write, :products++ admin_sdk_example <<~JS+ const variant = await client.products.variants.create('prod_86Rf07xd4z', {+ sku: 'TSHIRT-L-NAVY',+ options: [+ { name: 'size', value: 'Large' },+ { name: 'color', value: 'navy' },+ ],+ prices: [+ { currency: 'USD', amount: 29.99, compare_at_amount: 34.99 },+ { currency: 'EUR', amount: 27.99 },+ ],+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 25 },+ ],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -70,38 +95,40 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referencetax_category_id: { type: :string },options: {type: :array,- description: 'Option types and values (auto-created if needed)',+ description: 'One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.',items: {type: :object,+ required: %w[name value],properties: {- name: { type: :string, example: 'Size' },- value: { type: :string, example: 'Large' }- },- required: %w[name value]+ name: { type: :string, example: 'size' },+ value: { type: :string, example: 'Small' }+ }}},- total_on_hand: { type: :integer, example: 100 },position: { type: :integer },barcode: { type: :string },prices: {type: :array,+ description: 'Per-currency prices. Upserted by currency.',items: {type: :object,+ required: %w[currency amount],properties: {currency: { type: :string, example: 'USD' },amount: { type: :number, example: 29.99 },compare_at_amount: { type: :number, example: 39.99 }- },- required: %w[currency amount]+ }}},stock_items: {type: :array,+ description: 'Per-stock-location inventory. Upserted by stock_location_id.',items: {type: :object,+ required: %w[stock_location_id count_on_hand],properties: {- stock_location_id: { type: :string },- count_on_hand: { type: :integer },+ stock_location_id: { type: :string, description: 'Stock location ID (e.g. sloc_xxx)' },+ count_on_hand: { type: :integer, example: 50 },backorderable: { type: :boolean }}}@@ -134,16 +161,23 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referencepath '/api/v3/admin/products/{product_id}/variants/{id}' doget 'Get a variant' do- tags 'Variants'+ tags 'Product Catalog'produces 'application/json'security [api_key: [], bearer_auth: []]- description 'Returns a single variant by prefixed ID.'+ description 'Returns a single variant by ID.'+ admin_scope :read, :products++ admin_sdk_example <<~JS+ const variant = await client.products.variants.get('prod_86Rf07xd4z', 'variant_k5nR8xLq', {+ expand: ['prices', 'stock_items'],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Variant ID'parameter name: :expand, in: :query, type: :string, required: false,description: 'Comma-separated associations to expand (e.g., images, prices, stock_items)'@@ -170,17 +204,27 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referenceendpatch 'Update a variant' do- tags 'Variants'+ tags 'Product Catalog'consumes 'application/json'produces 'application/json'security [api_key: [], bearer_auth: []]description 'Updates a variant. Only provided fields are updated.'+ admin_scope :write, :products++ admin_sdk_example <<~JS+ const variant = await client.products.variants.update('prod_86Rf07xd4z', 'variant_k5nR8xLq', {+ sku: 'UPDATED-SKU',+ stock_items: [+ { stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 75 },+ ],+ })+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Variant ID'parameter name: :body, in: :body, schema: {type: :object,properties: {@@ -250,15 +294,20 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-referenceenddelete 'Delete a variant' do- tags 'Variants'+ tags 'Product Catalog'security [api_key: [], bearer_auth: []]description 'Soft-deletes a variant.'+ admin_scope :write, :products++ admin_sdk_example <<~JS+ await client.products.variants.delete('prod_86Rf07xd4z', 'variant_k5nR8xLq')+ JSparameter name: 'x-spree-api-key', in: :header, type: :string, required: trueparameter name: :Authorization, in: :header, type: :string, required: true,description: 'Bearer token for admin authentication'- parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'- parameter name: :id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Variant ID'response '204', 'variant deleted' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }diff --git a/spree/api/spec/support/code_samples_helper.rb b/spree/api/spec/support/code_samples_helper.rbindex b76316249a..e883f75230 100644--- a/spree/api/spec/support/code_samples_helper.rb+++ b/spree/api/spec/support/code_samples_helper.rb@@ -10,6 +10,15 @@ module CodeSamplesHelper})JS+ ADMIN_SDK_CLIENT_INIT = <<~JS.strip+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })+ JS+def code_samples(*samples)metadata[:operation][:'x-codeSamples'] = samples.map do |sample|{ lang: sample[:lang], label: sample[:label], source: sample[:source].strip }@@ -25,6 +34,28 @@ module CodeSamplesHelper})end++ def admin_sdk_example(source)+ code_samples(+ {+ lang: 'javascript',+ label: 'Spree Admin SDK',+ source: "#{ADMIN_SDK_CLIENT_INIT}\n\n#{source.strip}\n"+ }+ )+ end++ # Appends a `**Required scope:**` line to the operation description.+ # Use in admin integration specs to surface scope requirements in the+ # rendered Mintlify docs without inventing a custom OpenAPI extension.+ #+ # admin_scope :read, :orders+ # admin_scope :write, :customers+ def admin_scope(action, resource)+ line = "**Required scope:** `#{action}_#{resource}` (for API-key authentication)."+ existing = metadata[:operation][:description].to_s+ metadata[:operation][:description] = existing.empty? ? line : "#{existing}\n\n#{line}"+ endendRSpec.configure do |config|diff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rbindex dc35ead24f..e30336562f 100644--- a/spree/api/spec/swagger_helper.rb+++ b/spree/api/spec/swagger_helper.rb@@ -131,10 +131,11 @@ RSpec.configure do |config|All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.Single resource endpoints return a flat JSON object.- ## Prefixed IDs+ ## Resource IDs- All resources use Stripe-style prefixed IDs (e.g., `prod_86Rf07xd4z`, `variant_k5nR8xLq`).- These IDs must be used in all API requests.+ Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,+ `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,+ request bodies, and Ransack filters all accept them directly.## Error Handling@@ -164,30 +165,17 @@ RSpec.configure do |config|],tags: [{ name: 'Authentication', description: 'Admin user authentication' },- { name: 'Products', description: 'Product management' },- { name: 'Variants', description: 'Product variant management' },- { name: 'Option Types', description: 'Option type and value management' },- { name: 'Prices', description: 'Variant price management' },- { name: 'Orders', description: 'Order management — list, create, update, items, complete, cancel, approve' },- { name: 'Payments', description: 'Order payment management — capture, void, off-session charges' },- { name: 'Refunds', description: 'Order refund management' },- { name: 'Fulfillments', description: 'Order fulfillment management — ship, cancel, split' },- { name: 'Order Gift Cards', description: 'Apply / remove gift cards on an order' },- { name: 'Order Store Credits', description: 'Apply / remove customer store credit on an order' },- { name: 'Customers', description: 'Customer management — profile, tags, marketing consent, notes' },- { name: 'Customer Addresses', description: "Saved address book per customer with default billing/shipping flags" },- { name: 'Customer Store Credits', description: "Per-customer store credit balances issued by admin" },- { name: 'Customer Credit Cards', description: "Customer's saved credit cards (read-only)" },- { name: 'Payment Methods', description: 'Store-configured payment methods (read-only)' },- { name: 'Tags', description: 'Tag autocomplete for product/order/customer tag inputs' }+ { name: 'Product Catalog', description: 'Products, variants, and option types' },+ { name: 'Orders', description: 'Order management — orders, items, payments, fulfillments, refunds, gift cards, store credits' },+ { name: 'Customers', description: 'Customer management — profiles, addresses, store credits, credit cards' },+ { name: 'Configuration', description: 'Store configuration — payment methods, tag autocomplete' }],'x-tagGroups': [{ name: 'Authentication', tags: ['Authentication'] },- { name: 'Catalog', tags: %w[Products Variants Prices] },- { name: 'Options', tags: ['Option Types'] },- { name: 'Orders', tags: ['Orders', 'Payments', 'Refunds', 'Fulfillments', 'Order Gift Cards', 'Order Store Credits'] },- { name: 'Customers', tags: ['Customers', 'Customer Addresses', 'Customer Store Credits', 'Customer Credit Cards'] },- { name: 'Configuration', tags: ['Payment Methods', 'Tags'] }+ { name: 'Product Catalog', tags: ['Product Catalog'] },+ { name: 'Orders', tags: ['Orders'] },+ { name: 'Customers', tags: ['Customers'] },+ { name: 'Configuration', tags: ['Configuration'] }],components: {securitySchemes: {