Skip to content

armgit / spree

Public Imported from GitHub
0

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

Added Admin API documentation

Damian Legawiec710f1a77141a
diff --git a/docs/api-reference/admin-api/authentication.mdx b/docs/api-reference/admin-api/authentication.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.yaml
index 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: v3
paths:
- "/api/v3/admin/auth/login":
- post:
- summary: Login
+ "/api/v3/admin/customers/{customer_id}/addresses":
+ get:
+ summary: List customer addresses
tags:
- - Authentication
+ - Customers
security:
- 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
- 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
- password:
- type: string
- example: password123
- required:
- - email
- - 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 SDK
source: |-
- 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
- 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-key
in: header
@@ -232,8 +105,8 @@ paths:
is_default_shipping: false
state_name: New York
label:
- 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_UkLWZg9DAJ
metadata:
meta:
@@ -249,13 +122,37 @@ paths:
post:
summary: Create a customer address
tags:
- - Customer Addresses
+ - Customers
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.'
+ 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-key
in: header
@@ -297,8 +194,8 @@ paths:
is_default_shipping: false
state_name: New York
label: 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_UkLWZg9DAJ
metadata:
requestBody:
@@ -339,10 +236,30 @@ paths:
patch:
summary: Update a customer address
tags:
- - Customer Addresses
+ - Customers
security:
- 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-key
in: header
@@ -389,8 +306,8 @@ paths:
is_default_shipping: false
state_name: New York
label:
- 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_UkLWZg9DAJ
metadata:
requestBody:
@@ -408,12 +325,26 @@ paths:
delete:
summary: Delete a customer address
tags:
- - Customer Addresses
+ - Customers
security:
- 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-key
in: header
@@ -442,12 +373,26 @@ paths:
get:
summary: List customer credit cards
tags:
- - Customer Credit Cards
+ - Customers
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 }`.
+ 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-key
in: header
@@ -481,8 +426,8 @@ paths:
gateway_payment_profile_id:
customer_id: cus_UkLWZg9DAJ
payment_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: 1
limit: 25
@@ -497,10 +442,26 @@ paths:
get:
summary: Show a customer credit card
tags:
- - Customer Credit Cards
+ - Customers
security:
- 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-key
in: header
@@ -538,15 +499,31 @@ paths:
gateway_payment_profile_id:
customer_id: cus_UkLWZg9DAJ
payment_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 card
tags:
- - Customer Credit Cards
+ - Customers
security:
- 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-key
in: header
@@ -575,10 +552,26 @@ paths:
get:
summary: List customer store credits
tags:
- - Customer Store Credits
+ - Customers
security:
- 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-key
in: 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_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
metadata:
@@ -628,11 +621,31 @@ paths:
post:
summary: Issue a store credit to a customer
tags:
- - Customer Store Credits
+ - Customers
security:
- 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-key
in: 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_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
metadata:
@@ -693,12 +706,30 @@ paths:
patch:
summary: Update a store credit
tags:
- - Customer Store Credits
+ - Customers
security:
- 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-key
in: 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_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
metadata:
@@ -754,12 +785,26 @@ paths:
delete:
summary: Delete a store credit
tags:
- - Customer Store Credits
+ - Customers
security:
- 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-key
in: 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-key
in: header
@@ -840,8 +904,8 @@ paths:
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: 0
failed_attempts: 0
last_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-key
in: 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: 0
failed_attempts: 0
last_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-key
in: header
@@ -968,7 +1070,7 @@ paths:
- name: id
in: path
required: true
- description: Customer prefixed ID
+ description: Customer ID
schema:
type: string
- name: expand
@@ -996,8 +1098,8 @@ paths:
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: 0
failed_attempts: 0
last_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-key
in: header
@@ -1053,8 +1173,8 @@ paths:
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: 0
failed_attempts: 0
last_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-key
in: 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 SDK
source: |-
- 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
- first_name: Tanna
- last_name: Langosh
- created_at: '2026-04-29T15:59:29.836Z'
- updated_at: '2026-04-29T15:59:29.836Z'
+ first_name: Trudie
+ last_name: Braun
+ created_at: '2026-04-29T20:30:19.014Z'
+ updated_at: '2026-04-29T20:30:19.014Z'
permissions:
- allow: true
actions:
@@ -1237,11 +1372,26 @@ paths:
get:
summary: List option types
tags:
- - Option Types
+ - Product Catalog
security:
- 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-key
in: header
@@ -1284,8 +1434,8 @@ paths:
label: Size
position: 1
kind: 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 type
tags:
- - Option Types
+ - Product Catalog
security:
- 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-key
in: header
@@ -1353,8 +1525,8 @@ paths:
label: Material
position: 2
kind: 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 type
tags:
- - Option Types
+ - Product Catalog
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.
+
+ **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-key
in: header
@@ -1432,7 +1618,7 @@ paths:
- name: id
in: path
required: true
- description: Option type prefixed ID
+ description: Option type ID
schema:
type: string
responses:
@@ -1446,8 +1632,8 @@ paths:
label: Size
position: 1
kind: 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 type
tags:
- - Option Types
+ - Product Catalog
security:
- 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-key
in: header
@@ -1484,7 +1690,7 @@ paths:
- name: id
in: path
required: true
- description: Option type prefixed ID
+ description: Option type ID
schema:
type: string
responses:
@@ -1498,8 +1704,8 @@ paths:
label: Updated Presentation
position: 1
kind: 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 type
tags:
- - Option Types
+ - Product Catalog
security:
- 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-key
in: header
@@ -1573,7 +1794,7 @@ paths:
- name: id
in: path
required: true
- description: Option type prefixed ID
+ description: Option type ID
schema:
type: string
responses:
@@ -1583,11 +1804,26 @@ paths:
get:
summary: List fulfillments
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -1603,7 +1839,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -1614,7 +1850,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H14880110860
+ number: H58964048011
tracking: U10000
tracking_url:
cost: '10.0'
@@ -1638,8 +1874,8 @@ paths:
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -1657,11 +1893,26 @@ paths:
get:
summary: Show a shipment
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -1677,13 +1928,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment prefixed ID
+ description: Fulfillment ID
schema:
type: string
responses:
@@ -1693,7 +1944,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H46462677784
+ number: H22756559934
tracking: U10000
tracking_url:
cost: '10.0'
@@ -1717,19 +1968,36 @@ paths:
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
summary: Update a shipment
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -1745,13 +2013,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment prefixed ID
+ description: Fulfillment ID
schema:
type: string
responses:
@@ -1761,7 +2029,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H29909540755
+ number: H99332454701
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -1785,8 +2053,8 @@ paths:
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -1805,11 +2073,26 @@ paths:
patch:
summary: Fulfill a fulfillment
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -1825,13 +2108,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment prefixed ID
+ description: Fulfillment ID
schema:
type: string
responses:
@@ -1841,7 +2124,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H49727928395
+ number: H38654634498
tracking: U10000
tracking_url:
cost: '10.0'
@@ -1858,15 +2141,15 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-04-29T15:59:36Z'
+ fulfilled_at: '2026-04-29T20:30:24Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -1874,11 +2157,26 @@ paths:
patch:
summary: Cancel a fulfillment
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -1894,13 +2192,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment prefixed ID
+ description: Fulfillment ID
schema:
type: string
responses:
@@ -1910,7 +2208,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H74143874830
+ number: H94038749002
tracking: U10000
tracking_url:
cost: '10.0'
@@ -1934,8 +2232,8 @@ paths:
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -1943,11 +2241,26 @@ paths:
patch:
summary: Resume a fulfillment
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -1963,13 +2276,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment prefixed ID
+ description: Fulfillment ID
schema:
type: string
responses:
@@ -1979,7 +2292,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H62532514472
+ number: H93270023954
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2003,8 +2316,8 @@ paths:
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
@@ -2012,12 +2325,28 @@ paths:
patch:
summary: Split a fulfillment
tags:
- - Fulfillments
+ - Orders
security:
- 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-key
in: header
@@ -2033,13 +2362,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment prefixed ID
+ description: Fulfillment ID
schema:
type: string
responses:
@@ -2050,7 +2379,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H36302623231
+ number: H19670751184
tracking:
tracking_url:
cost: '10.0'
@@ -2074,8 +2403,8 @@ paths:
quantity: 1
adjustment_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_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
@@ -2090,22 +2419,39 @@ paths:
properties:
variant_id:
type: string
- description: Variant prefixed ID
+ description: Variant ID
quantity:
type: integer
example: 1
stock_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 order
tags:
- - Order Gift Cards
+ - Orders
security:
- 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-key
in: header
@@ -2121,7 +2467,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -2131,7 +2477,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: A95638B047300283
+ code: DC3C210CF25AFB8B
status: active
currency: USD
amount: '10.0'
@@ -2145,8 +2491,8 @@ paths:
redeemed_at:
expired: false
active: 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 order
tags:
- - Order Gift Cards
+ - Orders
security:
- 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-key
in: header
@@ -2183,13 +2544,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Gift card prefixed ID
+ description: Gift card ID
schema:
type: string
responses:
@@ -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-key
in: header
@@ -2219,7 +2595,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -2233,8 +2609,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 108448
- slug: product-108448
+ name: Product 105279
+ slug: product-105279
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -2265,11 +2641,11 @@ paths:
option_type_name: foo-size-10
option_type_label: Size
image_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-key
in: header
@@ -2306,7 +2700,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -2319,8 +2713,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 125274
- slug: product-125274
+ name: Product 125508
+ slug: product-125508
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -2351,11 +2745,11 @@ paths:
option_type_name: foo-size-12
option_type_label: Size
image_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-key
in: header
@@ -2397,13 +2806,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Item prefixed ID
+ description: Item ID
schema:
type: string
responses:
@@ -2416,8 +2825,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 131748
- slug: product-131748
+ name: Product 132818
+ slug: product-132818
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -2448,11 +2857,11 @@ paths:
option_type_name: foo-size-13
option_type_label: Size
image_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-key
in: header
@@ -2479,13 +2905,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Item prefixed ID
+ description: Item ID
schema:
type: string
responses:
@@ -2498,8 +2924,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 149920
- slug: product-149920
+ name: Product 141614
+ slug: product-141614
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -2530,11 +2956,11 @@ paths:
option_type_name: foo-size-14
option_type_label: Size
image_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-key
in: header
@@ -2569,13 +3010,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Item prefixed ID
+ description: Item ID
schema:
type: string
responses:
@@ -2585,11 +3026,26 @@ paths:
get:
summary: List payments
tags:
- - Payments
+ - Orders
security:
- 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-key
in: header
@@ -2605,7 +3061,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -2617,8 +3073,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-54a70c52b21d
- number: PLAV8NZY
+ response_code: BGS-cd10ecf5ca24
+ number: P2ASUUCU
amount: '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 payment
tags:
- - Payments
+ - Orders
security:
- 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-key
in: header
@@ -2678,7 +3153,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -2690,7 +3165,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: PTVQ79F2
+ number: PBXFIEHJ
amount: '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 ID
amount:
type: number
example: 99.99
source_id:
type: string
- description: Payment source prefixed ID
+ description: Payment source ID
"/api/v3/admin/orders/{order_id}/payments/{id}":
get:
summary: Show a payment
tags:
- - Payments
+ - Orders
security:
- 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-key
in: header
@@ -2746,13 +3236,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Payment prefixed ID
+ description: Payment ID
schema:
type: string
responses:
@@ -2763,8 +3253,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-836f5fa9863f
- number: P86A9S9N
+ response_code: BGS-c35e9c968ee9
+ number: PN5BGX24
amount: '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 payment
tags:
- - Payments
+ - Orders
security:
- 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-key
in: header
@@ -2815,13 +3320,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Payment prefixed ID
+ description: Payment ID
schema:
type: string
responses:
@@ -2832,8 +3337,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-43f1ba4bb781
- number: PZSM7VMD
+ response_code: BGS-83fa93309f40
+ number: PLRGMP0U
amount: '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 payment
tags:
- - Payments
+ - Orders
security:
- 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-key
in: header
@@ -2884,13 +3404,13 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Payment prefixed ID
+ description: Payment ID
schema:
type: string
responses:
@@ -2901,8 +3421,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-c568f8768169
- number: PMY7I4KL
+ response_code: void-BGS-be7e856c9089
+ number: P02ZEG5M
amount: '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 refunds
tags:
- - Refunds
+ - Orders
security:
- 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-key
in: header
@@ -2953,7 +3488,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -2976,12 +3511,30 @@ paths:
post:
summary: Create a refund
tags:
- - Refunds
+ - Orders
security:
- 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-key
in: header
@@ -2997,7 +3550,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -3007,13 +3560,13 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-b4d7d858bbe3
+ transaction_id: BGS-6814308937da
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_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 ID
amount:
type: number
example: 10.0
refund_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 order
tags:
- - Order Store Credits
+ - Orders
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.
+ 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-key
in: header
@@ -3057,7 +3626,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -3068,8 +3637,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R313817073
+ number: R524252096
customer_note:
currency: USD
locale: 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 order
tags:
- - Order Store Credits
+ - Orders
security:
- 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-key
in: header
@@ -3153,7 +3737,7 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -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-key
in: header
@@ -3232,8 +3836,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R488598395
+ number: R822015417
customer_note:
currency: USD
locale: 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 failure
is 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-key
in: header
@@ -3337,7 +4010,7 @@ paths:
example:
id: or_gbHJdmfrXB
market_id:
- number: R032689850
+ number: R287865458
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:
customer_id:
type: string
- description: 'Customer prefixed ID. Alias: user_id (legacy).'
+ description: 'Customer ID. Alias: user_id (legacy).'
use_customer_default_address:
type: boolean
description: When true with customer_id, copies the customer's saved
@@ -3410,7 +4083,7 @@ paths:
example: USD
market_id:
type: string
- description: Market prefixed ID
+ description: Market ID
locale:
type: string
example: en-US
@@ -3444,7 +4117,7 @@ paths:
type: string
shipping_address_id:
type: string
- description: Existing customer address prefixed ID
+ description: Existing customer address ID
billing_address:
type: object
properties:
@@ -3466,7 +4139,7 @@ paths:
type: string
billing_address_id:
type: string
- description: Existing customer address prefixed ID
+ description: Existing customer address ID
items:
type: array
items:
@@ -3477,7 +4150,7 @@ paths:
properties:
variant_id:
type: string
- description: Variant prefixed ID
+ description: Variant ID
quantity:
type: integer
example: 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-key
in: header
@@ -3511,7 +4201,7 @@ paths:
- name: id
in: path
required: 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_UkLWZg9DAJ
market_id:
- number: R785858912
+ number: R049254058
customer_note:
currency: USD
locale: 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-key
in: header
@@ -3614,7 +4321,7 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -3625,7 +4332,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R277507018
+ number: R515145022
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 ID
quantity:
type: integer
example: 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-key
in: header
@@ -3765,7 +4487,7 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -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-key
in: header
@@ -3795,7 +4532,7 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -3806,8 +4543,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R094301972
+ number: R756472256
customer_note:
currency: USD
locale: en
@@ -3834,7 +4571,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_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-key
in: header
@@ -3882,7 +4634,7 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -3893,8 +4645,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R143148128
+ number: R788972238
customer_note:
currency: USD
locale: 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-key
in: header
@@ -3969,7 +4736,7 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -3980,8 +4747,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R889473296
+ number: R436308444
customer_note:
currency: USD
locale: en
@@ -4008,7 +4775,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_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-key
in: header
@@ -4057,7 +4838,7 @@ paths:
- name: id
in: path
required: true
- description: Order prefixed ID
+ description: Order ID
schema:
type: string
responses:
@@ -4068,8 +4849,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R880168377
+ number: R732371039
customer_note:
currency: USD
locale: 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 methods
tags:
- - Payment Methods
+ - Configuration
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.'
+ 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-key
in: header
@@ -4156,8 +4951,8 @@ paths:
source_required: false
active: true
auto_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: 1
limit: 25
@@ -4172,10 +4967,26 @@ paths:
get:
summary: Show a payment method
tags:
- - Payment Methods
+ - Configuration
security:
- 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-key
in: header
@@ -4206,17 +5017,37 @@ paths:
source_required: false
active: true
auto_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 products
tags:
- - Products
+ - Product Catalog
security:
- 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-key
in: header
@@ -4273,35 +5104,25 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 351940
- slug: product-351940
+ name: Product 309712
+ slug: product-309712
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-29T15:59:59.242Z'
+ available_on: '2025-04-29T20:30:44.214Z'
purchasable: true
in_stock: false
backorderable: true
available: 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_UkLWZg9DAJ
thumbnail_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: USD
meta:
@@ -4362,15 +5183,62 @@ paths:
post:
summary: Create a product
tags:
- - Products
+ - Product Catalog
security:
- 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-key
in: 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: draft
make_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: USD
schema:
@@ -4466,17 +5334,14 @@ paths:
- 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:
+ description: Tax category ID
+ category_ids:
type: array
items:
type: string
- description: Array of prefixed taxon IDs
+ description: Array of category IDs
tags:
type: array
items:
@@ -4486,25 +5351,39 @@ paths:
- 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:
+ - 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:
+ - currency
+ - amount
properties:
currency:
type: string
@@ -4515,22 +5394,52 @@ paths:
compare_at_amount:
type: number
example: 39.99
+ stock_items:
+ type: array
+ description: Per-stock-location inventory. Upserted by stock_location_id.
+ items:
+ type: object
required:
- - 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: boolean
required:
- name
- price
- - shipping_category_id
"/api/v3/admin/products/{id}":
get:
summary: Get a product
tags:
- - Products
+ - Product Catalog
security:
- 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-key
in: header
@@ -4546,7 +5455,7 @@ paths:
- name: id
in: path
required: 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-344148
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-29T16:00:00.337Z'
+ available_on: '2025-04-29T20:30:45.252Z'
purchasable: true
in_stock: false
backorderable: true
available: 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_UkLWZg9DAJ
thumbnail_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: USD
schema:
@@ -4631,11 +5540,30 @@ paths:
patch:
summary: Update a product
tags:
- - Products
+ - Product Catalog
security:
- 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-key
in: header
@@ -4651,7 +5579,7 @@ paths:
- name: id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
responses:
@@ -4662,35 +5590,21 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-416925
+ slug: product-364026
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-29T16:00:00.997Z'
+ available_on: '2025-04-29T20:30:45.885Z'
purchasable: true
in_stock: false
backorderable: true
available: 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_UkLWZg9DAJ
thumbnail_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: USD
schema:
@@ -4755,17 +5669,14 @@ paths:
- 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:
+ description: Tax category ID
+ category_ids:
type: array
items:
type: string
- description: Array of prefixed taxon IDs
+ description: Array of category IDs
tags:
type: array
items:
@@ -4775,25 +5686,39 @@ paths:
- 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:
+ - 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:
+ - currency
+ - amount
properties:
currency:
type: string
@@ -4804,17 +5729,46 @@ paths:
compare_at_amount:
type: number
example: 39.99
+ stock_items:
+ type: array
+ description: Per-stock-location inventory. Upserted by stock_location_id.
+ items:
+ type: object
required:
- - 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: boolean
delete:
summary: Delete a product
tags:
- - Products
+ - Product Catalog
security:
- 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-key
in: header
@@ -4830,7 +5784,7 @@ paths:
- name: id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
responses:
@@ -4840,12 +5794,27 @@ paths:
get:
summary: List tags
tags:
- - Tags
+ - Configuration
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.
+ 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-key
in: header
@@ -4891,12 +5860,28 @@ paths:
get:
summary: List product variants
tags:
- - Variants
+ - Product Catalog
security:
- 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-key
in: header
@@ -4912,7 +5897,7 @@ paths:
- name: product_id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
- name: page
@@ -4943,7 +5928,7 @@ paths:
data:
- id: variant_UkLWZg9DAJ
product_id: prod_UkLWZg9DAJ
- sku: SKU-60
+ sku: SKU-45
options_text: ''
track_inventory: true
media_count: 0
@@ -4973,13 +5958,13 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_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 391443
display_price: "$0.00"
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-61
+ sku: SKU-46
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -4987,10 +5972,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 36.72
- height: 157.38
- width: 112.26
- depth: 120.53
+ weight: 16.32
+ height: 118.82
+ width: 185.67
+ depth: 98.8
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -5005,24 +5990,24 @@ paths:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
- name: size-12
+ name: size-7
label: S
position: 1
color_code:
- option_type_name: foo-size-21
+ option_type_name: foo-size-16
option_type_label: Size
image_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: 2
total_on_hand: 0
tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
deleted_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 391443
display_price: "$19.99"
meta:
page: 1
@@ -5037,15 +6022,43 @@ paths:
post:
summary: Create a variant
tags:
- - Variants
+ - Product Catalog
security:
- 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-key
in: header
@@ -5061,7 +6074,7 @@ paths:
- name: product_id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
responses:
@@ -5105,17 +6118,17 @@ paths:
option_type_name: size
option_type_label: Size
image_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: 3
total_on_hand: 0
tax_category_id: 1
cost_price:
cost_currency: USD
deleted_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 407587
display_price: "$24.99"
'422':
description: validation error
@@ -5169,30 +6182,33 @@ paths:
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:
+ - name
+ - value
properties:
name:
type: string
- example: Size
+ example: size
value:
type: string
- example: Large
- required:
- - name
- - value
- total_on_hand:
- type: integer
- example: 100
+ example: Small
position:
type: integer
barcode:
type: string
prices:
type: array
+ description: Per-currency prices. Upserted by currency.
items:
type: object
+ required:
+ - currency
+ - amount
properties:
currency:
type: string
@@ -5203,29 +6219,49 @@ paths:
compare_at_amount:
type: number
example: 39.99
- required:
- - currency
- - amount
stock_items:
type: array
+ description: Per-stock-location inventory. Upserted by stock_location_id.
items:
type: object
+ required:
+ - 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
"/api/v3/admin/products/{product_id}/variants/{id}":
get:
summary: Get a variant
tags:
- - Variants
+ - Product Catalog
security:
- 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-key
in: header
@@ -5241,13 +6277,13 @@ paths:
- name: product_id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
- name: id
in: path
required: true
- description: Variant prefixed ID
+ description: Variant ID
schema:
type: string
- name: expand
@@ -5265,7 +6301,7 @@ paths:
example:
id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-67
+ sku: SKU-52
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -5273,10 +6309,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 112.88
- height: 74.83
- width: 191.92
- depth: 80.98
+ weight: 154.41
+ height: 111.4
+ width: 196.4
+ depth: 182.8
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -5291,24 +6327,24 @@ paths:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
- name: size-15
+ name: size-10
label: S
position: 1
color_code:
- option_type_name: foo-size-24
+ option_type_name: foo-size-19
option_type_label: Size
image_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: 2
total_on_hand: 0
tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
deleted_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 421832
display_price: "$19.99"
'404':
description: variant not found
@@ -5323,11 +6359,31 @@ paths:
patch:
summary: Update a variant
tags:
- - Variants
+ - Product Catalog
security:
- 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-key
in: header
@@ -5343,13 +6399,13 @@ paths:
- name: product_id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
- name: id
in: path
required: true
- description: Variant prefixed ID
+ description: Variant ID
schema:
type: string
responses:
@@ -5368,10 +6424,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 130.34
- height: 106.5
- width: 7.87
- depth: 181.87
+ weight: 114.3
+ height: 134.7
+ width: 53.11
+ depth: 92.26
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -5386,24 +6442,24 @@ paths:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
- name: size-17
+ name: size-12
label: S
position: 1
color_code:
- option_type_name: foo-size-26
+ option_type_name: foo-size-21
option_type_label: Size
image_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: 2
total_on_hand: 0
tax_category_id: 1
cost_price: '17.0'
cost_currency: USD
deleted_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 446460
display_price: "$19.99"
requestBody:
content:
@@ -5491,11 +6547,26 @@ paths:
delete:
summary: Delete a variant
tags:
- - Variants
+ - Product Catalog
security:
- 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-key
in: header
@@ -5511,13 +6582,13 @@ paths:
- name: product_id
in: path
required: true
- description: Product prefixed ID
+ description: Product ID
schema:
type: string
- name: id
in: path
required: true
- description: Variant prefixed ID
+ description: Variant ID
schema:
type: string
responses:
@@ -5531,68 +6602,31 @@ servers:
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: 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 autocomplete
x-tagGroups:
- name: Authentication
tags:
- Authentication
-- name: Catalog
- tags:
- - Products
- - Variants
- - Prices
-- name: Options
+- name: Product Catalog
tags:
- - Option Types
+ - Product Catalog
- 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
+ - Configuration
components:
securitySchemes:
api_key:
@@ -5795,11 +6829,11 @@ components:
properties:
item_id:
type: string
- description: Line item prefixed ID
+ description: Line item ID
example: li_abc123
variant_id:
type: string
- description: Variant prefixed ID
+ description: Variant ID
example: variant_abc123
quantity:
type: integer
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index d347eaf18d..fe5bad1acb 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -40,624 +40,6 @@ info:
```
version: v3
paths:
- "/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: John
last_name: Doe
full_name: John Doe
- address1: 67 Lovely Street
+ address1: 65 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -738,7 +120,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 66 Lovely Street
+ address1: 64 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -756,7 +138,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 65 Lovely Street
+ address1: 63 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1005,7 +387,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 79 Lovely Street
+ address1: 77 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1080,7 +462,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 85 Lovely Street
+ address1: 83 Lovely Street
address2: Northwest
postal_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: XPJQbpb99u3n8mfatXsiPygL
user:
id: cus_UkLWZg9DAJ
- first_name: Brent
- last_name: Howell
+ first_name: Mathew
+ last_name: Bayer
phone:
accepts_email_marketing: false
- full_name: Brent Howell
+ full_name: Mathew Bayer
available_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: VzP8jvcXUsAmMAXyYLGxjqde
user:
id: cus_UkLWZg9DAJ
- first_name: Bernadine
- last_name: Doyle
+ first_name: Ahmad
+ last_name: Grady
phone:
accepts_email_marketing: false
- full_name: Bernadine Doyle
+ full_name: Ahmad Grady
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -1463,9 +845,9 @@ paths:
data:
- id: cart_gbHJdmfrXB
market_id:
- number: R496917299
- token: 14v8s9wyYvneSSMd6DD5r2LtMDguAnDm9u6
+ number: R182881602
+ token: 7xmFzBupB64Eqt1AJrjxAZshQ6hpfxqeukX
customer_note:
currency: USD
locale: en
@@ -1507,8 +889,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 579733
- slug: product-579733
+ name: Product 477312
+ slug: product-477312
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1533,7 +915,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H64308445398
+ number: H50238594154
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1562,7 +944,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Shanel Schaefer
+ name: Rashida Ward
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1594,7 +976,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 100 Lovely Street
+ address1: 98 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1613,7 +995,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 101 Lovely Street
+ address1: 99 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1632,9 +1014,9 @@ paths:
market:
- id: cart_UkLWZg9DAJ
market_id:
- number: R384180305
- token: QBU9FrPXCFJzmaRRAjyZBy9Kz4fd2FdpYt5
+ number: R180174120
+ token: M8LpDgv8esPyaFgerorVBCzTNxbbRBiBcH6
customer_note:
currency: USD
locale: en
@@ -1676,8 +1058,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 566791
- slug: product-566791
+ name: Product 466677
+ slug: product-466677
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1702,7 +1084,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H91469194561
+ number: H72269460516
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1731,7 +1113,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Shanel Schaefer
+ name: Rashida Ward
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1763,7 +1145,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 98 Lovely Street
+ address1: 96 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1782,7 +1164,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 99 Lovely Street
+ address1: 97 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -1874,8 +1256,8 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R691642289
- token: W1AjJm3NKZSMmctV9Tda2rfwcLhQZcmem8Y
+ number: R019335701
+ token: gt4CxjNxUGXa3c8guMYCXPvRMWBbpKPSDCy
email:
customer_note:
currency: USD
@@ -2030,9 +1412,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R511540545
- token: NMTe7trEmwcBD9EW6mWjsFPYsLZKUD3NKhk
+ number: R136520724
+ token: RDTgrgyzKwVcNA6uExX2tPfK9FiT5RiXg5X
customer_note:
currency: USD
locale: 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 out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
store_credit_total: '0.0'
@@ -2084,7 +1466,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 108 Lovely Street
+ address1: 106 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2103,7 +1485,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 109 Lovely Street
+ address1: 107 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2201,9 +1583,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R101821028
- token: auf9jP48vgoAgv6dDF5pocrdj2xRFmaC79Y
+ number: R589446831
+ token: 5jpsbFd46zdFZnxX83WMCjoaVuRUz5NjNCv
customer_note: Leave at door
currency: USD
locale: en
@@ -2247,8 +1629,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 628443
- slug: product-628443
+ name: Product 52369
+ slug: product-52369
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2273,7 +1655,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H07153056867
+ number: H91438962756
tracking:
tracking_url:
cost: '10.0'
@@ -2302,7 +1684,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Kendrick Nienow
+ name: Ike Schumm
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2334,7 +1716,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 112 Lovely Street
+ address1: 110 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2353,7 +1735,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 113 Lovely Street
+ address1: 111 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2539,9 +1921,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R496488366
- token: QyG1CoSmhsREvUj68UV6mdCjbK6B588iEDX
+ number: R265003786
+ token: aFhxuJ1gwfZ9RxSPHFyEdgDesj1URBDnDwg
customer_note:
currency: USD
locale: en
@@ -2583,8 +1965,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 643922
- slug: product-643922
+ name: Product 545852
+ slug: product-545852
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2609,7 +1991,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H01312263235
+ number: H27932063184
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2638,7 +2020,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Kyra Jast
+ name: Hiram Schmidt
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2670,7 +2052,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 118 Lovely Street
+ address1: 116 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2689,7 +2071,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 119 Lovely Street
+ address1: 117 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2772,8 +2154,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R661978413
+ number: R600375601
customer_note:
currency: USD
locale: en
@@ -2800,7 +2182,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: backorder
payment_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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 662849
- slug: product-662849
+ name: Product 566923
+ slug: product-566923
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2836,7 +2218,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H95827918638
+ number: H21719438891
tracking:
tracking_url:
cost: '10.0'
@@ -2865,7 +2247,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Carola Lueilwitz
+ name: Zella Flatley
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2894,8 +2276,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-def49f44c66f
- number: P97I9JEM
+ response_code: BGS-3cd8d54d3a63
+ number: P5SEJH2N
amount: '29.99'
display_amount: "$29.99"
status: completed
@@ -2922,7 +2304,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 126 Lovely Street
+ address1: 124 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -2941,7 +2323,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 127 Lovely Street
+ address1: 125 Lovely Street
address2: Northwest
postal_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: NYmxCAw5u8FtKDzarLk2VB1A
user:
id: cus_UkLWZg9DAJ
- first_name: Gayla
- last_name: Witting
+ first_name: Katlyn
+ last_name: Kuhn
phone:
accepts_email_marketing: false
- full_name: Gayla Witting
+ full_name: Katlyn Kuhn
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -3930,8 +3312,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R832819108
+ number: R270430768
customer_note:
currency: USD
locale: 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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 755263
- slug: product-755263
+ name: Product 653038
+ slug: product-653038
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3994,7 +3376,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H44154252716
+ number: H02369830101
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4023,7 +3405,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Alane Hegmann
+ name: Shayla Gerlach
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4055,7 +3437,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 146 Lovely Street
+ address1: 144 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4074,7 +3456,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 147 Lovely Street
+ address1: 145 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4185,8 +3567,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R624689755
+ number: R634795563
customer_note:
currency: USD
locale: 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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 772121
- slug: product-772121
+ name: Product 673736
+ slug: product-673736
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4249,7 +3631,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H33308593214
+ number: H68508572865
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4278,7 +3660,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Valery Conn
+ name: Rivka Harvey
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4310,7 +3692,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 152 Lovely Street
+ address1: 150 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4329,7 +3711,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 153 Lovely Street
+ address1: 151 Lovely Street
address2: Northwest
postal_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: 2AobsjUHtC2zLJjrBGx7jc5z
user:
id: cus_UkLWZg9DAJ
@@ -4513,12 +3895,12 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Jonah
- last_name: Rutherford
+ first_name: Manuela
+ last_name: O'Kon
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Jonah Rutherford
+ full_name: Manuela O'Kon
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -4526,7 +3908,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 159 Lovely Street
+ address1: 157 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4544,7 +3926,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 158 Lovely Street
+ address1: 156 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4563,7 +3945,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 159 Lovely Street
+ address1: 157 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4582,7 +3964,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 158 Lovely Street
+ address1: 156 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4652,7 +4034,7 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -4665,7 +4047,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 161 Lovely Street
+ address1: 159 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4683,7 +4065,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 160 Lovely Street
+ address1: 158 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4702,7 +4084,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 161 Lovely Street
+ address1: 159 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4721,7 +4103,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 160 Lovely Street
+ address1: 158 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4892,9 +4274,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R684238326
- token: u6ecSSHe1CGhDripbUftdK41Jsec1LqM4bc
+ number: R686751507
+ token: PfLkSHCKhzw3ZFoT3Evj6bX72KEAePEERfW
customer_note:
currency: USD
locale: en
@@ -4943,8 +4325,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 855536
- slug: product-855536
+ name: Product 755782
+ slug: product-755782
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4969,7 +4351,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H53375671698
+ number: H81703772553
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4998,7 +4380,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Camila McCullough
+ name: Larita Lakin
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5030,7 +4412,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 178 Lovely Street
+ address1: 176 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5049,7 +4431,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 179 Lovely Street
+ address1: 177 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5152,9 +4534,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R636351307
- token: ZuEsV7CieZAFaG4m17MPKposzN9bASB18Gg
+ number: R666419309
+ token: nc7Dy8DuA7PFHd5sn1zM2b8gpHDPfgEp1tt
customer_note:
currency: USD
locale: en
@@ -5196,8 +4578,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 878882
- slug: product-878882
+ name: Product 772017
+ slug: product-772017
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5222,7 +4604,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H40345253216
+ number: H42154252733
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5251,7 +4633,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Shane DuBuque
+ name: Margarett Hoeger
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5283,7 +4665,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 186 Lovely Street
+ address1: 184 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5302,7 +4684,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 187 Lovely Street
+ address1: 185 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5394,9 +4776,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R682532547
- token: cJ71DWMVgw44QB3afABkDchQ8VC76qvjNjp
+ number: R679060655
+ token: gePNeiWirzf2J7y37iBdarBX4qVLfs3eEgi
customer_note:
currency: USD
locale: en
@@ -5440,8 +4822,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 89648
- slug: product-89648
+ name: Product 796254
+ slug: product-796254
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5466,7 +4848,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H83618197901
+ number: H02184977229
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5495,7 +4877,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Yer Cassin
+ name: Bridget Heller
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5527,7 +4909,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 194 Lovely Street
+ address1: 192 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5546,7 +4928,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 195 Lovely Street
+ address1: 193 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5652,9 +5034,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R134509356
- token: Pc31yhLMexVeuwqP7x3aKHw8r1v9n8X1PHk
+ number: R134922089
+ token: v2NsykGGYJxbRhYHnN1wb62cK4Q7KNoBxYx
customer_note:
currency: USD
locale: en
@@ -5693,8 +5075,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 919205
- slug: product-919205
+ name: Product 813626
+ slug: product-813626
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5719,7 +5101,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H44860419830
+ number: H20006652345
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5748,7 +5130,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Lue Windler
+ name: Taisha Koch
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5777,8 +5159,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260429160039175123
- number: P1F24VXD
+ response_code: 1-SC-20260429203120465620
+ number: PYZM56EO
amount: '50.0'
display_amount: "$50.00"
status: checkout
@@ -5805,7 +5187,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 202 Lovely Street
+ address1: 200 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5824,7 +5206,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 203 Lovely Street
+ address1: 201 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5957,9 +5339,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R058228208
- token: vKMtw8bFJNKEKCDEo6wkcCGjagCReoeQ5hT
+ number: R739841957
+ token: Zsmwu1S5EBR4ua9KCtREh1LboGrdYxeCjXh
customer_note:
currency: USD
locale: en
@@ -6001,8 +5383,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 955154
- slug: product-955154
+ name: Product 856826
+ slug: product-856826
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6027,7 +5409,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H82159045492
+ number: H08780625784
tracking: U10000
tracking_url:
cost: '100.0'
@@ -6056,7 +5438,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Arleen Bartell
+ name: Lynsey Bode
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6085,8 +5467,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260429160041706187
- number: PB0HE5QW
+ response_code: 1-SC-20260429203123363868
+ number: P605ZYX4
amount: '50.0'
display_amount: "$50.00"
status: invalid
@@ -6113,7 +5495,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 218 Lovely Street
+ address1: 216 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6132,7 +5514,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 219 Lovely Street
+ address1: 217 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6210,7 +5592,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 2FE4341082F198C4
+ code: 49492AAAF001FBB7
status: active
currency: USD
amount: '10.0'
@@ -6306,7 +5688,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: ED365F485FE3776A
+ code: 7C8C28BE6FE5ECDE
status: active
currency: USD
amount: '10.0'
@@ -6397,9 +5779,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R775361233
- token: W1EWaRx5iBZnn83Vn66BSjeqUq9jQjy438s
+ number: R160774453
+ token: VshV5k2uUhjKTJj8apmDPv31xd5qkh3sh5Y
customer_note:
currency: USD
locale: en
@@ -6447,8 +5829,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 984707
- slug: product-984707
+ name: Product 888823
+ slug: product-888823
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6475,8 +5857,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 99985
- slug: product-99985
+ name: Product 895490
+ slug: product-895490
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -6506,7 +5888,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 233 Lovely Street
+ address1: 231 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6619,9 +6001,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R042592274
- token: uJnik897i8sPndA2u7koP8pUgbZW9rte8gs
+ number: R417441624
+ token: 6fGMJoT6FeteiGKiWb7Awm5ZSeEZGUYFXPT
customer_note:
currency: USD
locale: en
@@ -6666,8 +6048,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 102651
- slug: product-102651
+ name: Product 925658
+ slug: product-925658
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6697,7 +6079,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 242 Lovely Street
+ address1: 240 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6790,9 +6172,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R910961026
- token: uEZu67z8eF6jkqokHhX5ZG5oj3hk4gparTn
+ number: R327511489
+ token: vz6NujDsYszBfSh8snFmiUjv4XN8jV22n8D
customer_note:
currency: USD
locale: en
@@ -6843,7 +6225,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 245 Lovely Street
+ address1: 243 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7393,7 +6775,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R404436615
+ number: R773500111
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_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 106449
- slug: product-106449
+ name: Product 966442
+ slug: product-966442
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7457,7 +6839,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H83574844550
+ number: H86313255182
tracking: U10000
tracking_url:
cost: '100.0'
@@ -7486,7 +6868,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Nora Mueller
+ name: Tandra Weber
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7518,7 +6900,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 253 Lovely Street
+ address1: 251 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7537,7 +6919,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 254 Lovely Street
+ address1: 252 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7631,9 +7013,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_7c95fb2319657ba994cc2207
+ external_id: bogus_5be4f6882cb65c798b36044b
external_data:
- client_secret: bogus_secret_1dccd1a9fa1716cf
+ client_secret: bogus_secret_83acefba58c748fa
customer_external_id:
expires_at:
amount: '110.0'
@@ -7731,7 +7113,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_ccc13a869ffecd10dffe7812
+ external_id: bogus_eea6b836764131d01d8930c3
external_data:
client_secret: secret_123
customer_external_id:
@@ -7793,7 +7175,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_554e57fdc224df25d5e22aa4
+ external_id: bogus_c42d7bb8c46ce77865501174
external_data:
client_secret: secret_123
customer_external_id:
@@ -7895,7 +7277,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_b2779ff1fd23789a717fc8b5
+ external_id: bogus_da9af71a978676085b99ce61
external_data:
client_secret: secret_123
customer_external_id:
@@ -7980,8 +7362,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_18928969f2502cd4c2c1ce32
- external_client_secret: bogus_seti_secret_64707f0d54f29d38
+ external_id: bogus_seti_69d0c0fba541cf751511c029
+ external_client_secret: bogus_seti_secret_e91402dff84ebb58
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -8080,8 +7462,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_95227153d866b2994ca7ca92
- external_client_secret: seti_secret_17c2c2cef27524e368875fb0
+ external_id: seti_test_c9f7f791cdf7b9c36dea5ae9
+ external_client_secret: seti_secret_e7cca325c5d0792f378adc51
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8157,8 +7539,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_7dba83629f90b18f1b1e43fa
- external_client_secret: seti_secret_f0f84f9147db743c3bd09176
+ external_id: seti_test_73a3566842a3d01db9a800e0
+ external_client_secret: seti_secret_2f94274fab6af1dfb46b5b39
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8252,7 +7634,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: PT31KFV5
+ number: PHAY8LI4
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -8348,7 +7730,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-ea963688-a324-427f-98ef-cb1454aa0b36
+ slug: privacy-policy-24a44547-bd29-493a-9028-25e30b0c6417
body: 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-1066950
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-04-29T16:01:00.580Z'
+ available_on: '2025-04-29T20:31:41.571Z'
purchasable: true
in_stock: false
backorderable: 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-1078704
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-04-29T16:01:00.655Z'
+ available_on: '2025-04-29T20:31:41.632Z'
purchasable: true
in_stock: false
backorderable: true
available: 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_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -8755,12 +8136,12 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1446790
- slug: product-1446790
+ name: Product 1341741
+ slug: product-1341741
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-04-29T16:01:02.256Z'
+ available_on: '2025-04-29T20:31:43.333Z'
purchasable: true
in_stock: false
backorderable: true
@@ -8787,7 +8168,7 @@ paths:
amount_in_cents: 999
currency: USD
display_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_UkLWZg9DAJ
market_id:
- number: R021918322
- token: SAUJRQh1TveULkP81cF4ixpTswBACZZcF6F
+ number: R702444710
+ token: KKKKz15uUX3wLs3WeMci3aiDUn8NLgjRMRd
customer_note:
currency: USD
locale: en
@@ -9203,8 +8584,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1643340
- slug: product-1643340
+ name: Product 1546874
+ slug: product-1546874
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -9229,7 +8610,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H00294560922
+ number: H03249355163
tracking: U10000
tracking_url:
cost: '100.0'
@@ -9258,7 +8639,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Silva Hills
+ name: Nada Hettinger
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -9287,8 +8668,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260429160107728556
- number: PE5SHORE
+ response_code: 1-SC-20260429203148434892
+ number: POQWOLDS
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -9315,7 +8696,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 317 Lovely Street
+ address1: 315 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9334,7 +8715,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 318 Lovely Street
+ address1: 316 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9431,9 +8812,9 @@ paths:
example:
id: cart_UkLWZg9DAJ
market_id:
- number: R685003154
- token: 2HqSo4dFnwipJUsBxSm53XA3SC7q9auGjkx
+ number: R968281647
+ token: vyW18bBrgGcr9BHW4DWLGKxUtYnnhyyRGVG
customer_note:
currency: USD
locale: en
@@ -9475,8 +8856,8 @@ paths:
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1662543
- slug: product-1662543
+ name: Product 1567335
+ slug: product-1567335
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -9501,7 +8882,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H00399261907
+ number: H34150382243
tracking: U10000
tracking_url:
cost: '100.0'
@@ -9530,7 +8911,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Ermelinda Trantow
+ name: Kylee Jones
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -9562,7 +8943,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 325 Lovely Street
+ address1: 323 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9581,7 +8962,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 326 Lovely Street
+ address1: 324 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9660,7 +9041,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: qKXFEJg674GQFMJdhX4aP21s
+ token: NtdmeixQzCBf9oTPYdxpf9Sv
is_default: false
is_private: true
meta:
@@ -9736,7 +9117,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: L23Wwbu1VdwURuQb3d9QhNo3
+ token: 8cXeJyppojDAcyKGtrqEhahv
is_default: false
is_private: true
schema:
@@ -9832,7 +9213,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: vnMGJpfADtGcEPdtKSfeNcMf
+ token: 7kZxgV92WcKPHpXSc1Cn695L
is_default: false
is_private: true
schema:
@@ -9894,7 +9275,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: 4SxcHcYqoPne3UnSxaWTyemQ
+ token: zTmZe61pQGipm76nbGax6Wii
is_default: false
is_private: true
schema:
@@ -10009,7 +9390,7 @@ paths:
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-206
+ sku: SKU-191
options_text: ''
track_inventory: true
media_count: 0
@@ -10357,11 +9738,11 @@ components:
properties:
item_id:
type: string
- description: Line item prefixed ID
+ description: Line item ID
example: li_abc123
variant_id:
type: string
- description: Variant prefixed ID
+ description: Variant ID
example: variant_abc123
quantity:
type: integer
diff --git a/docs/docs.json b/docs/docs.json
index 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.rb
index 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.rb
index 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 Spree
type: :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.rb
index 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 do
before { 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' do
expect {
- 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 do
status: '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.rb
index 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
-end
diff --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.rb
index 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: 'api
let(: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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -35,11 +40,27 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'api
end
post '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,
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -87,10 +108,20 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'api
let(: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' },
+ )
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -117,9 +148,14 @@ RSpec.describe 'Admin Customer Addresses API', type: :request, swagger_doc: 'api
end
delete '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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/customers/credit_cards_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers/credit_cards_spec.rb
index 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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter 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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -59,8 +70,14 @@ RSpec.describe 'Admin Customer Credit Cards API', type: :request, swagger_doc: '
end
delete '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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/customers/store_credits_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers/store_credits_spec.rb
index 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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -33,11 +39,21 @@ RSpec.describe 'Admin Customer Store Credits API', type: :request, swagger_doc:
end
post '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',
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter 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' },
+ )
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -101,9 +126,14 @@ RSpec.describe 'Admin Customer Store Credits API', type: :request, swagger_doc:
end
delete '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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/customers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers_spec.rb
index 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-referenc
produces '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,
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -39,6 +48,18 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referenc
produces '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,
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -77,11 +98,18 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referenc
produces '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'],
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
parameter 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-referenc
produces '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'],
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -135,6 +171,11 @@ RSpec.describe 'Admin Customers API', type: :request, swagger_doc: 'api-referenc
tags '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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/me_spec.rb
index 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/admin
security [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
}
JS
diff --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.rb
index 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-refer
path '/api/v3/admin/option_types' do
get '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()
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -46,7 +51,7 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-refer
end
post '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-refer
Option 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' },
+ ],
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -107,15 +124,20 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-refer
path '/api/v3/admin/option_types/{id}' do
get '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')
+ JS
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: :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' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -140,16 +162,26 @@ RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-refer
end
patch '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' },
+ ],
+ })
+ JS
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: :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-refer
end
delete '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')
+ JS
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: :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' do
let(:'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.rb
deleted file mode 100644
index 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
-end
diff --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.rb
index 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: 'api
let(: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')
+ JS
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'
+ description: 'Order ID'
response '200', 'fulfillments found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -41,18 +46,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
let(: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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Fulfillment prefixed ID'
+ description: 'Fulfillment ID'
response '200', 'shipment found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -66,19 +76,26 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
end
patch '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',
+ })
+ JS
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'
+ 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: 'api
path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill' do
patch '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Fulfillment prefixed ID'
+ description: 'Fulfillment ID'
response '200', 'fulfillment fulfilled' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -133,18 +155,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel' do
patch '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Fulfillment prefixed ID'
+ description: 'Fulfillment ID'
response '200', 'fulfillment canceled' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -161,18 +188,23 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume' do
patch '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Fulfillment prefixed ID'
+ description: 'Fulfillment ID'
response '200', 'fulfillment resumed' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -193,26 +225,33 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/split' do
patch '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,
+ })
+ JS
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'
+ 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.rb
index 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-r
let(: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',
+ })
+ JS
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'
+ 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-r
let(: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')
+ JS
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'
+ 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' do
let(:'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.rb
index 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-r
produces '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')
+ JS
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'
+ description: 'Order ID'
response '200', 'items found' do
let(:'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-r
produces '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,
+ })
+ JS
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'
+ 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-r
produces '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Item prefixed ID'
+ description: 'Item ID'
response '200', 'item found' do
let(:'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-r
produces '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,
+ })
+ JS
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'
+ 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-r
tags '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Item prefixed ID'
+ description: 'Item ID'
response '204', 'line item removed' do
let(:'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.rb
index 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-ref
let(: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')
+ JS
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'
+ description: 'Order ID'
response '200', 'payments found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -36,24 +41,33 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-ref
end
post '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',
+ })
+ JS
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'
+ 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-ref
let(: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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Payment prefixed ID'
+ description: 'Payment ID'
response '200', 'payment found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -103,18 +122,23 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-ref
path '/api/v3/admin/orders/{order_id}/payments/{id}/capture' do
patch '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Payment prefixed ID'
+ description: 'Payment ID'
response '200', 'payment captured' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -135,18 +159,23 @@ RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-ref
path '/api/v3/admin/orders/{order_id}/payments/{id}/void' do
patch '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')
+ JS
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'
+ description: 'Order ID'
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Payment prefixed ID'
+ description: 'Payment ID'
response '200', 'payment voided' do
let(:'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.rb
index 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-refe
let(: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')
+ JS
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'
+ description: 'Order ID'
response '200', 'refunds found' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -36,24 +41,33 @@ RSpec.describe 'Admin Order Refunds API', type: :request, swagger_doc: 'api-refe
end
post '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',
+ })
+ JS
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'
+ 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.rb
index 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: 'ap
let(: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,
+ })
+ JS
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'
+ 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: 'ap
end
delete "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')
+ JS
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'
+ description: 'Order ID'
response '204', 'store credit removed' do
let(:'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.rb
index 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/a
produces '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,
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -56,6 +66,65 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
consumes '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 <<~DESC
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.
@@ -63,6 +132,7 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
Invalid coupon codes are non-fatal — the order is created and the failure
is reported on the service result (not in the API response body for now).
DESC
+ admin_scope :write, :orders
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -71,10 +141,10 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
type: :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/a
state_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/a
state_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/a
produces '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'],
+ })
+ JS
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: :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/a
produces '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',
+ })
+ JS
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: :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/a
type: :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/a
tags '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')
+ JS
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: :id, in: :path, type: :string, required: true,
- description: 'Order prefixed ID'
+ description: 'Order ID'
response '204', 'order deleted' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -258,12 +348,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
produces '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')
+ JS
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: :id, in: :path, type: :string, required: true,
- description: 'Order prefixed ID'
+ description: 'Order ID'
response '200', 'order canceled' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -281,12 +376,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
produces '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')
+ JS
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: :id, in: :path, type: :string, required: true,
- description: 'Order prefixed ID'
+ description: 'Order ID'
response '200', 'order approved' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -307,12 +407,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
produces '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')
+ JS
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: :id, in: :path, type: :string, required: true,
- description: 'Order prefixed ID'
+ description: 'Order ID'
response '200', 'order resumed' do
let(:'x-spree-api-key') { secret_api_key.plaintext_token }
@@ -334,12 +439,17 @@ RSpec.describe 'Admin Orders API', type: :request, swagger_doc: 'api-reference/a
produces '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')
+ JS
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: :id, in: :path, type: :string, required: true,
- description: 'Order prefixed ID'
+ description: 'Order ID'
response '200', 'confirmation resent' do
let(:'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.rb
index 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-re
path '/api/v3/admin/payment_methods' do
get '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()
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
@@ -33,9 +38,15 @@ RSpec.describe 'Admin Payment Methods API', type: :request, swagger_doc: 'api-re
let(: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')
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true
diff --git a/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/product_media_spec.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb
index 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-reference
include_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' do
get '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,
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -53,7 +62,7 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-reference
end
post '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-reference
Option 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 },
+ ],
+ },
+ ],
+ })
+ JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :Authorization, in: :header, type: :string, required: true,
@@ -76,42 +122,64 @@ RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-reference
slug: { 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' do
let(:'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-reference
path '/api/v3/admin/products/{id}' do
get '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'],
+ })
+ JS
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: :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-reference
end
patch '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'],
+ })
+ JS
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: :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-reference
slug: { 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-reference
end
delete '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')
+ JS
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: :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' do
let(:'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.rb
index 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/adm
path '/api/v3/admin/tags' do
get '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: true
parameter name: :Authorization, in: :header, type: :string, required: true
parameter 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.rb
deleted file mode 100644
index 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
-end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb
index 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-reference
path '/api/v3/admin/products/{product_id}/variants' do
get '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'],
+ })
+ JS
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: :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-reference
end
post '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-reference
Option 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 },
+ ],
+ })
+ JS
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: :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-reference
tax_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-reference
path '/api/v3/admin/products/{product_id}/variants/{id}' do
get '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'],
+ })
+ JS
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: '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-reference
end
patch '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 },
+ ],
+ })
+ JS
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: '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-reference
end
delete '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')
+ JS
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: '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' do
let(:'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.rb
index 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}"
+ end
end
RSpec.configure do |config|
diff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rb
index 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: {