Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
openapi: 3.0.3
info:
title: Admin API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: [email protected]
description: |
Spree Admin API v3 - Administrative API for managing products, orders, and store settings.
## Authentication
The Admin API requires a secret API key passed in the `x-spree-api-key` header.
Secret API keys can be generated in the Spree admin dashboard.
## Response Format
All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.
Single resource endpoints return a flat JSON object.
## Resource IDs
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
Errors return a consistent format:
```json
{
"error": {
"code": "validation_error",
"message": "Validation failed",
"details": { "name": ["can't be blank"] }
}
}
```
version: v3
paths:
"/api/v3/admin/auth/login":
post:
summary: Login
tags:
- Authentication
security:
- api_key: []
description: |
Authenticates an admin user and returns a short-lived JWT access token.
The rotatable refresh token is set in an HttpOnly cookie — it is not
included in the response body.
The `provider` field selects the authentication method. When omitted it
defaults to `email`, the built-in email/password login.
To authenticate against a third-party identity provider (Okta, Azure AD,
Google Workspace SSO, a custom JWT issuer, SAML, etc.), send
`{ "provider": "<your_key>", ... }` with the fields that provider
requires. The endpoint returns the same JWT regardless of which provider
authenticated the request. See
[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
for the list of configured providers and their required fields.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
// The refresh token is set as an HttpOnly cookie; only `token` and `user` come back in the body.
const auth = await client.auth.login({
email: '[email protected]',
password: 'password123',
})
- lang: bash
label: Spree CLI
source: spree api post /auth/login -d '{"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.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE3NmVlN2M3LWJkYzktNGM1MS1hMzFiLTEwMDYxOTc3NGZmNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.t4Ntas5E8dwfI8wxMdwcC-XVFXWzaFSAFL8_Mv4HnlU
user:
id: adm_UkLWZg9DAJ
email: [email protected]
first_name: Gavin
last_name: Swift
full_name: Gavin Swift
selected_locale:
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at: '2026-01-15T12:00:00Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: Spree Test Store
code: spree_1
schema:
"$ref": "#/components/schemas/AuthResponse"
'401':
description: invalid credentials
content:
application/json:
example:
error:
code: authentication_failed
message: Invalid email or password
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
oneOf:
- title: EmailPasswordLogin
description: Built-in email/password authentication (default when
`provider` is omitted).
type: object
properties:
provider:
type: string
enum:
- email
default: email
email:
type: string
format: email
example: [email protected]
password:
type: string
example: password123
required:
- email
- password
- title: ProviderLogin
description: |
Provider-dispatched login. The `provider` key selects a configured
authentication provider; the remaining fields are forwarded to it.
Required fields depend on the provider — see
[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
type: object
properties:
provider:
type: string
example: okta
description: Registered provider key (anything other than `email`).
not:
enum:
- email
required:
- provider
additionalProperties: true
"/api/v3/admin/auth/refresh":
post:
summary: Refresh token
tags:
- Authentication
security:
- api_key: []
description: |
Exchanges the HttpOnly refresh-token cookie for a new access JWT and a
rotated refresh token cookie. No request body or Authorization header
is required — the cookie alone authenticates the call.
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',
})
// Driven entirely by the HttpOnly refresh-token cookie + CSRF header (set by the SDK).
const auth = await client.auth.refresh()
- lang: bash
label: Spree CLI
source: spree api post /auth/refresh
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: refresh successful
content:
application/json:
example:
token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImFiN2M4YjAxLTY0MGYtNDJhZi1hZTY1LTQxY2NmOTk1YmVlMCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.oXS2FwkI2rK4WOX4QUNW4oTPu7gzMmB9Y9oqsJpW7SY
user:
id: adm_UkLWZg9DAJ
email: [email protected]
first_name: Clarine
last_name: Jenkins
full_name: Clarine Jenkins
selected_locale:
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at: '2026-01-15T12:00:00Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: Spree Test Store
code: spree_1
schema:
"$ref": "#/components/schemas/AuthResponse"
'401':
description: missing or invalid refresh-token cookie
content:
application/json:
example:
error:
code: invalid_refresh_token
message: Refresh token cookie missing
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/auth/logout":
post:
summary: Logout
tags:
- Authentication
security:
- api_key: []
description: Revokes the refresh-token cookie, effectively logging the admin
out.
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.auth.logout()
- lang: bash
label: Spree CLI
source: spree api post /auth/logout
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
responses:
'204':
description: logout successful
"/api/v3/admin/auth/invitations/{id}/accept":
parameters:
- name: id
in: path
description: Invitation ID from the emailed link
required: true
schema:
type: string
post:
summary: Accept an invitation
tags:
- Authentication
description: |
Accepts a staff invitation and returns a signed-in admin session, so the
new member lands in the dashboard rather than on a login form.
Unauthenticated — the ID and token in the emailed link are the
credential. The email is never taken from the request; it always comes
from the invitation.
`password` is required when no account exists for the invited address,
in which case it sets one. When an account already exists, the same
field is how the person proves the account is theirs — unless the
request carries that account's own access token, which proves it
already.
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',
})
// The invitation ID and token come from the link in the invitation email.
// An invitee without an account sets a password here; one with an account
// signs in with theirs. The refresh token is set as an HttpOnly cookie.
const auth = await client.auth.acceptInvitation('inv_UkLWZg9DAJ', 'xK3pQ9vLmT2wRz8N', {
password: 'password123',
password_confirmation: 'password123',
first_name: 'Robin',
last_name: 'Ellis',
})
- lang: bash
label: Spree CLI
source: spree api post /auth/invitations/{id}/accept -d '{"password":"password123","password_confirmation":"password123","first_name":"Robin","last_name":"Ellis"}'
parameters:
- name: token
in: query
required: true
description: The token from the emailed link
schema:
type: string
responses:
'200':
description: invitation accepted, session issued
content:
application/json:
example:
token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjQ2MzZlMDBiLTdmZGMtNDk1Mi1hNzhhLTI4YmEyMTVjNDk0MSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.AwpPaRCvRIV36C8k4nChul5s7yq_yWFTSy_TyVlrbXA
user:
id: adm_gbHJdmfrXB
email: [email protected]
first_name: Robin
last_name: Ellis
full_name: Robin Ellis
selected_locale:
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at: '2026-01-15T12:00:00Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: Spree Test Store
code: spree_1
schema:
"$ref": "#/components/schemas/AuthResponse"
'404':
description: wrong token, or an invitation that can no longer be accepted
content:
application/json:
example:
error:
code: record_not_found
message: Invitation not found, expired, or already accepted
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/InvitationAcceptParams"
required: true
"/api/v3/admin/me":
get:
summary: Get current admin user and permissions
tags:
- Authentication
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.
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 me = await client.me.get()
if (
me.permissions.some(
(r) => r.allow && r.actions.includes('manage') && r.subjects.includes('product'),
)
) {
// show "Create product" button
}
- lang: bash
label: Spree CLI
source: spree api get /me
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
responses:
'200':
description: current admin user and permissions
content:
application/json:
example:
user:
id: adm_UkLWZg9DAJ
email: [email protected]
first_name: Zenobia
last_name: Sanford
full_name: Zenobia Sanford
selected_locale:
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at:
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: Spree Test Store
code: spree_1
permissions:
- allow: true
actions:
- manage
subjects:
- all
has_conditions: false
permission_keys:
- read_dashboard
- read_reports
- write_reports
- read_orders
- write_orders
- read_payments
- write_payments
- read_fulfillments
- write_fulfillments
- read_refunds
- write_refunds
- read_products
- write_products
- read_product_types
- write_product_types
- read_publishing
- write_publishing
- read_media
- write_media
- read_categories
- write_categories
- read_collections
- write_collections
- read_stock
- write_stock
- read_purchasing
- write_purchasing
- read_customers
- write_customers
- read_sellers
- write_sellers
- read_commissions
- write_commissions
- read_payouts
- write_payouts
- read_gift_cards
- write_gift_cards
- read_store_credits
- write_store_credits
- read_promotions
- write_promotions
- read_settings
- write_settings
- read_delivery_methods
- write_delivery_methods
- read_package_types
- write_package_types
- read_webhooks
- write_webhooks
- read_email_templates
- write_email_templates
- read_integrations
- write_integrations
- read_maintenance_tasks
- write_maintenance_tasks
- read_api_keys
- write_api_keys
- read_oauth_applications
- write_oauth_applications
- read_staff
- write_staff
schema:
"$ref": "#/components/schemas/MeResponse"
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update the current admin profile
tags:
- Authentication
security:
- api_key: []
bearer_auth: []
description: Self-service update of the signed-in admin's own profile, such
as their admin UI display language (`selected_locale`).
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',
})
// Set the signed-in admin's own UI display language.
const me = await client.me.update({
selected_locale: 'de',
})
- lang: bash
label: Spree CLI
source: spree api patch /me -d '{"selected_locale":"de"}'
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
responses:
'200':
description: profile updated
content:
application/json:
example:
user:
id: adm_UkLWZg9DAJ
email: [email protected]
first_name: See
last_name: Kuhlman
full_name: See Kuhlman
selected_locale: de
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at:
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: Spree Test Store
code: spree_1
permissions:
- allow: true
actions:
- manage
subjects:
- all
has_conditions: false
permission_keys:
- read_dashboard
- read_reports
- write_reports
- read_orders
- write_orders
- read_payments
- write_payments
- read_fulfillments
- write_fulfillments
- read_refunds
- write_refunds
- read_products
- write_products
- read_product_types
- write_product_types
- read_publishing
- write_publishing
- read_media
- write_media
- read_categories
- write_categories
- read_collections
- write_collections
- read_stock
- write_stock
- read_purchasing
- write_purchasing
- read_customers
- write_customers
- read_sellers
- write_sellers
- read_commissions
- write_commissions
- read_payouts
- write_payouts
- read_gift_cards
- write_gift_cards
- read_store_credits
- write_store_credits
- read_promotions
- write_promotions
- read_settings
- write_settings
- read_delivery_methods
- write_delivery_methods
- read_package_types
- write_package_types
- read_webhooks
- write_webhooks
- read_email_templates
- write_email_templates
- read_integrations
- write_integrations
- read_maintenance_tasks
- write_maintenance_tasks
- read_api_keys
- write_api_keys
- read_oauth_applications
- write_oauth_applications
- read_staff
- write_staff
schema:
"$ref": "#/components/schemas/MeResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/MeUpdateParams"
required: true
"/api/v3/admin/auth/password_resets":
post:
summary: Request password reset
tags:
- Authentication
security:
- api_key: []
description: |
Requests a password reset email for an admin user. Always returns `202`
whether or not the email matches an account, to prevent enumeration.
`redirect_url` is where the emailed link should point (the reset token
is appended as a `token` query param). It is honoured only on the
dashboard's origin and for an account that is staff of the store —
otherwise it is silently ignored and the link opens the dashboard's
reset page. The email is delivered by Spree itself via the
`admin_user.password_reset_requested` event; this event is never
forwarded to webhook endpoints.
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',
})
// Always resolves (202) whether or not the email exists — no account enumeration.
// The emailed link points at redirect_url with the reset token appended as ?token=.
await client.auth.requestPasswordReset({
email: '[email protected]',
redirect_url: 'https://admin.your-store.com/reset-password',
})
- lang: bash
label: Spree CLI
source: spree api post /auth/password_resets -d '{"email":"[email protected]","redirect_url":"https://admin.your-store.com/reset-password"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
responses:
'202':
description: reset requested
content:
application/json:
example:
message: If an account exists for that email, password reset instructions
have been sent.
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PasswordResetRequestParams"
required: true
"/api/v3/admin/auth/password_resets/{id}":
patch:
summary: Reset password
tags:
- Authentication
security:
- api_key: []
description: |
Consumes a password reset token (the `token` query param from the
emailed link), sets the new password, and signs the admin in: the
response carries a JWT access token and the rotatable refresh token is
set in an HttpOnly cookie. The token is single-use — it invalidates as
soon as the password changes.
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',
})
// The token comes from the emailed link's ?token= param. On success the admin
// is signed in: a JWT comes back and the refresh token is set as an HttpOnly cookie.
const auth = await client.auth.resetPassword('reset-token-from-email', {
password: 'new-password-123',
password_confirmation: 'new-password-123',
})
- lang: bash
label: Spree CLI
source: spree api patch /auth/password_resets/{id} -d '{"password":"new-password-123","password_confirmation":"new-password-123"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: id
in: path
description: The reset token from the emailed link
required: true
schema:
type: string
responses:
'200':
description: password reset
content:
application/json:
example:
token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBiZTdhM2RmLWEyYzYtNDZkOC1hNTZiLWE4NDg4MGIyZGZiNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Vo2RzprqsH2XBa8DaSQ6awyXqlBA5QDFA5R7ygTezXY
user:
id: adm_UkLWZg9DAJ
email: [email protected]
first_name: Olga
last_name: Schneider
full_name: Olga Schneider
selected_locale:
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at: '2026-01-15T12:00:00Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: Spree Test Store
code: spree_1
schema:
"$ref": "#/components/schemas/AuthResponse"
'422':
description: invalid or expired token
content:
application/json:
example:
error:
code: password_reset_token_invalid
message: Password reset token is invalid or has expired.
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PasswordResetParams"
required: true
"/api/v3/admin/auth/setup":
get:
summary: Check first-run setup availability
tags:
- Authentication
description: |
Reports whether first-run setup is still available — true only while
the installation has no admin user. Unauthenticated; the dashboard
login page uses it to offer the setup screen.
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',
})
// True only until the installation has its first admin user.
const { setup_required } = await client.auth.setupStatus()
- lang: bash
label: Spree CLI
source: spree api get /auth/setup
responses:
'200':
description: setup status
content:
application/json:
example:
setup_required: true
post:
summary: Complete first-run setup
tags:
- Authentication
description: |
Creates the first admin account and adopts the seeded store, authorized
by the one-time setup token printed at install time (rotate it with
`bin/rails spree:setup:token`). Issues a JWT access token and a
refresh-token cookie exactly like login. Returns 404 once any admin
user exists — the flow is closed permanently after setup.
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',
})
// The setup token is printed when Spree is installed. The refresh token is
// set as an HttpOnly cookie; only `token` and `user` come back in the body.
const auth = await client.auth.completeSetup({
setup_token: 'st_9f2c4e7a1b8d',
email: '[email protected]',
password: 'Secret123!',
password_confirmation: 'Secret123!',
first_name: 'Olivia',
last_name: 'Owner',
store_name: 'My Store',
country_code: 'US',
})
- lang: bash
label: Spree CLI
source: spree api post /auth/setup -d '{"setup_token":"st_9f2c4e7a1b8d","email":"[email protected]","password":"Secret123!","password_confirmation":"Secret123!","first_name":"Olivia","last_name":"Owner","store_name":"My
Store","country_code":"US"}'
parameters: []
responses:
'200':
description: setup completed
content:
application/json:
example:
token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZjMjg1ODk5LTExMzUtNDBhMi1hNDBiLTE4NjNiODcwZDRjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.Go2eUEiXf7rVD5mwtNMqkWqUGcBfhxk3b7JT8dw8uiE
user:
id: adm_UkLWZg9DAJ
email: [email protected]
first_name: Olivia
last_name: Owner
full_name: Olivia Owner
selected_locale:
status: active
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
last_active_at: '2026-01-15T12:00:00Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
name: admin
stores:
- id: store_UkLWZg9DAJ
name: My Store
code: spree_1
'404':
description: setup not available
content:
application/json:
example:
error:
code: record_not_found
message: Setup is not available
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/SetupParams"
required: true
"/api/v3/admin/auth/setup/countries":
get:
summary: List countries for first-run setup
tags:
- Authentication
description: |
Countries the store can be set up in, each with the currency and
official languages derived from it. Unauthenticated, because the setup
screen runs before any credential exists. Returns 404 once any admin
user exists.
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',
})
// Each country comes with the currency and languages the store would start with.
const { countries } = await client.auth.setupCountries()
- lang: bash
label: Spree CLI
source: spree api get /auth/setup/countries
responses:
'200':
description: countries
content:
application/json:
example:
countries:
- code: AD
currency: EUR
locales:
- ca
- code: AE
currency: AED
locales:
- ar
- code: AF
currency: AFN
locales:
- ps
- uz
- tk
- code: AG
currency: XCD
locales:
- en
- code: AI
currency: XCD
locales:
- en
- code: AL
currency: ALL
locales:
- sq
- code: AM
currency: AMD
locales:
- hy
- code: AO
currency: AOA
locales:
- pt
- code: AR
currency: ARS
locales:
- es
- gn
- code: AS
currency: USD
locales:
- en
- sm
- code: AT
currency: EUR
locales:
- de
- code: AU
currency: AUD
locales:
- en
- code: AW
currency: AWG
locales:
- nl
- code: AZ
currency: AZN
locales:
- az
- hy
- code: BA
currency: BAM
locales:
- bs
- hr
- sr
- code: BB
currency: BBD
locales:
- en
- code: BD
currency: BDT
locales:
- bn
- code: BE
currency: EUR
locales:
- nl
- fr
- de
- code: BF
currency: XOF
locales:
- fr
- ff
- code: BG
currency: EUR
locales:
- bg
- code: BH
currency: BHD
locales:
- ar
- code: BI
currency: BIF
locales:
- fr
- rn
- code: BJ
currency: XOF
locales:
- fr
- code: BL
currency: EUR
locales:
- fr
- code: BM
currency: BMD
locales:
- en
- code: BN
currency: BND
locales:
- ms
- code: BO
currency: BOB
locales:
- es
- ay
- qu
- code: BQ
currency: USD
locales:
- nl
- en
- code: BR
currency: BRL
locales:
- pt
- code: BS
currency: BSD
locales:
- en
- code: BT
currency: BTN
locales:
- dz
- code: BW
currency: BWP
locales:
- en
- tn
- code: BY
currency: BYN
locales:
- be
- ru
- code: BZ
currency: BZD
locales:
- en
- es
- code: CA
currency: CAD
locales:
- en
- fr
- code: CC
currency: AUD
locales:
- en
- code: CD
currency: CDF
locales:
- fr
- ln
- kg
- sw
- lu
- code: CF
currency: XAF
locales:
- fr
- sg
- code: CG
currency: XAF
locales:
- fr
- ln
- code: CH
currency: CHF
locales:
- de
- fr
- it
- rm
- code: CI
currency: XOF
locales:
- fr
- code: CK
currency: NZD
locales:
- en
- code: CL
currency: CLP
locales:
- es
- code: CM
currency: XAF
locales:
- en
- fr
- code: CN
currency: CNY
locales:
- zh-CN
- code: CO
currency: COP
locales:
- es
- code: CR
currency: CRC
locales:
- es
- code: CU
currency: CUP
locales:
- es
- code: CV
currency: CVE
locales:
- pt
- code: CW
currency: XCG
locales:
- nl
- code: CX
currency: AUD
locales:
- en
- zh-CN
- ms
- code: CY
currency: EUR
locales:
- el
- tr
- hy
- code: CZ
currency: CZK
locales:
- cs
- code: DE
currency: EUR
locales:
- de
- code: DJ
currency: DJF
locales:
- ar
- fr
- code: DK
currency: DKK
locales:
- da
- code: DM
currency: XCD
locales:
- en
- code: DO
currency: DOP
locales:
- es
- code: DZ
currency: DZD
locales:
- ar
- code: EC
currency: USD
locales:
- es
- code: EE
currency: EUR
locales:
- et
- code: EG
currency: EGP
locales:
- ar
- code: ER
currency: ERN
locales:
- en
- ar
- ti
- code: ES
currency: EUR
locales:
- es
- code: ET
currency: ETB
locales:
- am
- code: FI
currency: EUR
locales:
- fi
- sv
- code: FJ
currency: FJD
locales:
- en
- fj
- hi
- code: FK
currency: FKP
locales:
- en
- code: FM
currency: USD
locales:
- en
- code: FO
currency: DKK
locales:
- fo
- code: FR
currency: EUR
locales:
- fr
- code: GA
currency: XAF
locales:
- fr
- code: GB
currency: GBP
locales:
- en
- code: GD
currency: XCD
locales:
- en
- code: GE
currency: GEL
locales:
- ka
- code: GF
currency: EUR
locales:
- fr
- code: GG
currency: GBP
locales:
- en
- fr
- code: GH
currency: GHS
locales:
- en
- code: GI
currency: GIP
locales:
- en
- code: GL
currency: DKK
locales:
- kl
- code: GM
currency: GMD
locales:
- en
- code: GN
currency: GNF
locales:
- fr
- ff
- code: GP
currency: EUR
locales:
- fr
- code: GQ
currency: XAF
locales:
- es
- fr
- code: GR
currency: EUR
locales:
- el
- code: GT
currency: GTQ
locales:
- es
- code: GU
currency: USD
locales:
- en
- ch
- es
- code: GW
currency: XOF
locales:
- pt
- code: GY
currency: GYD
locales:
- en
- code: HK
currency: HKD
locales:
- en
- zh-CN
- code: HN
currency: HNL
locales:
- es
- code: HR
currency: EUR
locales:
- hr
- code: HT
currency: HTG
locales:
- fr
- ht
- code: HU
currency: HUF
locales:
- hu
- code: ID
currency: IDR
locales:
- id
- code: IE
currency: EUR
locales:
- en
- ga
- code: IL
currency: ILS
locales:
- he
- ar
- code: IM
currency: GBP
locales:
- en
- gv
- code: IN
currency: INR
locales:
- hi
- en
- code: IQ
currency: IQD
locales:
- ar
- code: IR
currency: IRR
locales:
- fa
- code: IS
currency: ISK
locales:
- is
- code: IT
currency: EUR
locales:
- it
- code: JE
currency: GBP
locales:
- en
- fr
- code: JM
currency: JMD
locales:
- en
- code: JO
currency: JOD
locales:
- ar
- code: JP
currency: JPY
locales:
- ja
- code: KE
currency: KES
locales:
- en
- sw
- code: KG
currency: KGS
locales:
- ky
- ru
- code: KH
currency: KHR
locales:
- km
- code: KI
currency: AUD
locales:
- en
- code: KM
currency: KMF
locales:
- ar
- fr
- code: KN
currency: XCD
locales:
- en
- code: KP
currency: KPW
locales:
- ko
- code: KR
currency: KRW
locales:
- ko
- code: KW
currency: KWD
locales:
- ar
- code: KY
currency: KYD
locales:
- en
- code: KZ
currency: KZT
locales:
- kk
- ru
- code: LA
currency: LAK
locales:
- lo
- code: LB
currency: LBP
locales:
- ar
- fr
- code: LC
currency: XCD
locales:
- en
- code: LI
currency: CHF
locales:
- de
- code: LK
currency: LKR
locales:
- si
- ta
- code: LR
currency: LRD
locales:
- en
- code: LS
currency: LSL
locales:
- en
- st
- code: LT
currency: EUR
locales:
- lt
- code: LU
currency: EUR
locales:
- fr
- de
- lb
- code: LV
currency: EUR
locales:
- lv
- code: LY
currency: LYD
locales:
- ar
- code: MA
currency: MAD
locales:
- ar
- code: MC
currency: EUR
locales:
- fr
- code: MD
currency: MDL
locales:
- ro
- code: ME
currency: EUR
locales:
- sr
- bs
- sq
- hr
- code: MF
currency: EUR
locales:
- en
- fr
- nl
- code: MG
currency: MGA
locales:
- fr
- mg
- code: MH
currency: USD
locales:
- en
- mh
- code: MK
currency: MKD
locales:
- mk
- code: ML
currency: XOF
locales:
- fr
- code: MM
currency: MMK
locales:
- my
- code: MN
currency: MNT
locales:
- mn
- code: MO
currency: MOP
locales:
- zh-CN
- pt
- code: MP
currency: USD
locales:
- en
- ch
- code: MQ
currency: EUR
locales:
- fr
- code: MR
currency: MRU
locales:
- ar
- fr
- code: MS
currency: XCD
locales:
- en
- code: MT
currency: EUR
locales:
- mt
- en
- code: MU
currency: MUR
locales:
- en
- code: MV
currency: MVR
locales:
- dv
- code: MW
currency: MWK
locales:
- en
- ny
- code: MX
currency: MXN
locales:
- es
- code: MY
currency: MYR
locales:
- ms
- en
- code: MZ
currency: MZN
locales:
- pt
- code: NA
currency: NAD
locales:
- en
- af
- code: NC
currency: XPF
locales:
- fr
- code: NE
currency: XOF
locales:
- fr
- code: NF
currency: AUD
locales:
- en
- code: NG
currency: NGN
locales:
- en
- code: NI
currency: NIO
locales:
- es
- code: NL
currency: EUR
locales:
- nl
- code: 'NO'
currency: NOK
locales:
- nb
- nn
- code: NP
currency: NPR
locales:
- ne
- code: NR
currency: AUD
locales:
- en
- na
- code: NU
currency: NZD
locales:
- en
- code: NZ
currency: NZD
locales:
- en
- code: OM
currency: OMR
locales:
- ar
- code: PA
currency: PAB
locales:
- es
- code: PE
currency: PEN
locales:
- es
- code: PF
currency: XPF
locales:
- fr
- code: PG
currency: PGK
locales:
- en
- code: PH
currency: PHP
locales:
- tl
- en
- code: PK
currency: PKR
locales:
- en
- ur
- code: PL
currency: PLN
locales:
- pl
- code: PM
currency: EUR
locales:
- fr
- code: PN
currency: NZD
locales:
- en
- code: PR
currency: USD
locales:
- es
- en
- code: PS
currency: ILS
locales:
- ar
- he
- en
- code: PT
currency: EUR
locales:
- pt
- code: PW
currency: USD
locales:
- en
- code: PY
currency: PYG
locales:
- es
- gn
- code: QA
currency: QAR
locales:
- ar
- code: RE
currency: EUR
locales:
- fr
- code: RO
currency: RON
locales:
- ro
- code: RS
currency: RSD
locales:
- sr
- code: RU
currency: RUB
locales:
- ru
- code: RW
currency: RWF
locales:
- rw
- en
- fr
- code: SA
currency: SAR
locales:
- ar
- code: SB
currency: SBD
locales:
- en
- code: SC
currency: SCR
locales:
- fr
- en
- code: SD
currency: SDG
locales:
- ar
- en
- code: SE
currency: SEK
locales:
- sv
- code: SG
currency: SGD
locales:
- en
- ms
- ta
- code: SH
currency: SHP
locales:
- en
- code: SI
currency: EUR
locales:
- sl
- code: SJ
currency: NOK
locales:
- 'no'
- code: SK
currency: EUR
locales:
- sk
- code: SL
currency: SLE
locales:
- en
- code: SM
currency: EUR
locales:
- it
- code: SN
currency: XOF
locales:
- fr
- code: SO
currency: SOS
locales:
- so
- ar
- code: SR
currency: SRD
locales:
- nl
- code: SS
currency: SSP
locales:
- ar
- en
- code: ST
currency: STN
locales:
- pt
- code: SV
currency: USD
locales:
- es
- code: SX
currency: XCG
locales:
- nl
- en
- code: SY
currency: SYP
locales:
- ar
- code: SZ
currency: SZL
locales:
- en
- ss
- code: TC
currency: USD
locales:
- en
- code: TD
currency: XAF
locales:
- ar
- fr
- code: TG
currency: XOF
locales:
- fr
- code: TH
currency: THB
locales:
- th
- code: TJ
currency: TJS
locales:
- tg
- ru
- code: TK
currency: NZD
locales:
- en
- code: TL
currency: IDR
locales:
- pt
- code: TM
currency: TMT
locales:
- tk
- code: TN
currency: TND
locales:
- ar
- fr
- code: TO
currency: TOP
locales:
- en
- to
- code: TR
currency: TRY
locales:
- tr
- code: TT
currency: TTD
locales:
- en
- code: TV
currency: AUD
locales:
- en
- code: TW
currency: TWD
locales:
- zh-CN
- code: TZ
currency: TZS
locales:
- sw
- en
- code: UA
currency: UAH
locales:
- uk
- code: UG
currency: UGX
locales:
- en
- sw
- code: US
currency: USD
locales:
- en
- code: UY
currency: UYU
locales:
- es
- code: UZ
currency: UZS
locales:
- uz
- code: VA
currency: EUR
locales:
- it
- la
- code: VC
currency: XCD
locales:
- en
- code: VE
currency: VES
locales:
- es
- code: VG
currency: USD
locales:
- en
- code: VI
currency: USD
locales:
- en
- code: VN
currency: VND
locales:
- vi
- code: VU
currency: VUV
locales:
- bi
- en
- fr
- code: WF
currency: XPF
locales:
- fr
- code: WS
currency: WST
locales:
- sm
- en
- code: YE
currency: YER
locales:
- ar
- code: YT
currency: EUR
locales:
- fr
- code: ZA
currency: ZAR
locales:
- af
- en
- nr
- st
- ss
- tn
- ts
- ve
- xh
- zu
- code: ZM
currency: ZMW
locales:
- en
- code: ZW
currency: USD
locales:
- en
- sn
- nd
"/api/v3/admin/allowed_origins":
get:
summary: List allowed origins
tags:
- Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
Returns the CORS allowlist for the current store. Each entry is a
bare `scheme://host[:port]` permitted to call the admin API from a
browser. Backs the `Rack::Cors` allowlist and the CSRF boundary of
the admin cookie session (see
`docs/plans/5.5-admin-auth-cookie-refresh.md`).
**Required scope:** `read_api_keys` (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: origins } = await client.allowedOrigins.list()
- lang: bash
label: Spree CLI
source: spree api get /allowed_origins
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: q[search]
in: query
required: false
schema:
type: string
description: Matches any of origin (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[origin_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `origin`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: AllowedOrigin
sortable:
- created_at
- id
- origin
- updated_at
responses:
'200':
description: allowed origins found
content:
application/json:
example:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/AllowedOrigin"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create an allowed origin
tags:
- Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
Adds an origin to the admin CORS allowlist. The value must be a bare
`scheme://host[:port]` (no path, query, or fragment) and use `http` or
`https`.
**Required scope:** `write_api_keys` (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 origin = await client.allowedOrigins.create({
origin: 'https://admin.example.com',
})
- lang: bash
label: Spree CLI
source: spree api post /allowed_origins -d '{"origin":"https://admin.example.com"}'
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
responses:
'201':
description: allowed origin created
content:
application/json:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Origin is invalid
details:
origin:
- code: invalid
message: is invalid
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/AllowedOriginCreateParams"
required: true
"/api/v3/admin/allowed_origins/{id}":
parameters:
- name: id
in: path
required: true
description: Allowed origin ID
schema:
type: string
get:
summary: Get an allowed origin
tags:
- Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single allowed origin by prefixed ID.
**Required scope:** `read_api_keys` (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 origin = await client.allowedOrigins.get('ao_xxx')
- lang: bash
label: Spree CLI
source: spree api get /allowed_origins/{id}
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: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
description: allowed origin found
content:
application/json:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
description: allowed origin not found
content:
application/json:
example:
error:
code: record_not_found
message: Allowed origin not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update an allowed origin
tags:
- Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
Updates an existing allowed origin.
**Required scope:** `write_api_keys` (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 origin = await client.allowedOrigins.update('ao_xxx', {
origin: 'https://www.example.com',
})
- lang: bash
label: Spree CLI
source: spree api patch /allowed_origins/{id} -d '{"origin":"https://www.example.com"}'
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
responses:
'200':
description: allowed origin updated
content:
application/json:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Origin must be an origin (scheme and host) without path,
query, or fragment
details:
origin:
- code: must_be_origin_only
message: must be an origin (scheme and host) without path, query,
or fragment
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/AllowedOriginUpdateParams"
required: true
delete:
summary: Delete an allowed origin
tags:
- Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
Removes an origin from the admin CORS allowlist. After deletion the
admin SPA running at that origin will no longer be able to call the
admin API from a browser.
**Required scope:** `write_api_keys` (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.allowedOrigins.delete('ao_xxx')
- lang: bash
label: Spree CLI
source: spree api delete /allowed_origins/{id}
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
responses:
'204':
description: allowed origin deleted
"/api/v3/admin/api_keys":
get:
summary: List API keys
tags:
- API Keys
security:
- api_key: []
bearer_auth: []
description: |-
Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.
**Required scope:** `read_api_keys` (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: keys } = await client.apiKeys.list()
- lang: bash
label: Spree CLI
source: spree api get /api_keys
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: ApiKey
sortable:
- created_at
- id
- name
- updated_at
responses:
'200':
description: API keys found
content:
application/json:
example:
data:
- id: key_UkLWZg9DAJ
name: Storefront key
key_type: publishable
token_prefix:
scopes: []
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token: pk_K6zNkaVogFy735ukK6E7Qs1F
created_by_email:
created_by_type:
created_by_label:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
token_prefix: sk_JiXS5S1gJ
scopes:
- write_all
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
created_by_type:
created_by_label:
- id: key_EfhxLZ9ck8
name: API key 13
key_type: secret
token_prefix: sk_vihKVmP6r
scopes:
- write_all
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
created_by_type:
created_by_label:
meta:
page: 1
limit: 25
count: 3
pages: 1
from: 1
to: 3
in: 3
previous:
next:
post:
summary: Create an API key
tags:
- API Keys
security:
- api_key: []
bearer_auth: []
description: |-
Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.
**Required scope:** `write_api_keys` (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 key = await client.apiKeys.create({
name: 'Backend integration',
key_type: 'secret',
scopes: ['read_orders', 'write_orders'],
})
// `key.plaintext_token` is available only on this response.
- lang: bash
label: Spree CLI
source: spree api post /api_keys -d '{"name":"Backend integration","key_type":"secret","scopes":["read_orders","write_orders"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: secret key created — plaintext token returned once
content:
application/json:
example:
id: key_VqXmZF31wY
name: CI key
key_type: secret
token_prefix: sk_kCkDUvba1
scopes:
- read_orders
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token: sk_kCkDUvba1Z9gf8HAy29ih1Bj
created_by_email: [email protected]
created_by_type: admin_user
created_by_label: Mana Cremin
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank and Scopes can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
scopes:
- code: blank
message: can't be blank
specific: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ApiKeyCreateParams"
required: true
"/api/v3/admin/api_keys/{id}":
get:
summary: Show an API key
tags:
- API Keys
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `read_api_keys` (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 key = await client.apiKeys.get('key_xxx')
- lang: bash
label: Spree CLI
source: spree api get /api_keys/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: API key found
content:
application/json:
example:
id: key_UkLWZg9DAJ
name: Storefront key
key_type: publishable
token_prefix:
scopes: []
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token: pk_XyZ9qSxtdtD6Uewb3GXYKkoV
created_by_email:
created_by_type:
created_by_label:
patch:
summary: Update an API key
tags:
- API Keys
security:
- api_key: []
bearer_auth: []
description: |-
Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.
**Required scope:** `write_api_keys` (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',
})
// Only `name` is editable — scopes and key_type are fixed at creation.
const key = await client.apiKeys.update('key_xxx', { name: 'CI key (renamed)' })
- lang: bash
label: Spree CLI
source: spree api patch /api_keys/{id} -d '{"name":"CI key (renamed)"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: API key renamed
content:
application/json:
example:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
token_prefix: sk_ZPBGFa2TH
scopes:
- write_all
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
created_by_type:
created_by_label:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ApiKeyUpdateParams"
required: true
delete:
summary: Delete an API key
tags:
- API Keys
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_api_keys` (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.apiKeys.delete('key_xxx')
- lang: bash
label: Spree CLI
source: spree api delete /api_keys/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: API key deleted
"/api/v3/admin/api_keys/current":
get:
summary: Describe the current API key
tags:
- API Keys
security:
- api_key: []
description: |-
Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.
**Required scope:** none — any key can describe itself (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',
})
// Describes the key you authenticated with, including its live scopes.
const key = await client.apiKeys.current()
- lang: bash
label: Spree CLI
source: spree api get /api_keys/current
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: current API key
content:
application/json:
example:
id: key_EfhxLZ9ck8
name: API key 19
key_type: secret
token_prefix: sk_L5LVfygvH
scopes:
- write_all
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
created_by_type:
created_by_label:
"/api/v3/admin/api_keys/{id}/revoke":
patch:
summary: Revoke an API key
tags:
- API Keys
security:
- api_key: []
bearer_auth: []
description: |-
Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.
**Required scope:** `write_api_keys` (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 key = await client.apiKeys.revoke('key_xxx')
- lang: bash
label: Spree CLI
source: spree api patch /api_keys/{id}/revoke -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: API key revoked
content:
application/json:
example:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
token_prefix: sk_11yGX4rad
scopes:
- write_all
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
revoked_at: '2026-01-15T12:00:00.000Z'
last_used_at:
channel_id:
plaintext_token:
created_by_email:
created_by_type:
created_by_label:
"/api/v3/admin/categories":
get:
summary: List categories
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).
**Required scope:** `read_categories` (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: categories } = await client.categories.list({
name_cont: 'Shirts',
limit: 25,
})
- lang: bash
label: Spree CLI
source: spree api get /categories -d '{"name_cont":"Shirts","limit":25}'
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: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name and pretty name (partial, case-insensitive).
- 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
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., children, parent,
ancestors).
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `children_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `depth` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `pretty_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[parent_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
</Accordion>
**Sort by:** `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Category
sortable:
- automatic
- children_count
- created_at
- depth
- id
- name
- parent_id
- permalink
- position
- pretty_name
- products_count
- updated_at
responses:
'200':
description: categories found
content:
application/json:
example:
data:
- id: ctg_UkLWZg9DAJ
name: Clothing
permalink: clothing
position: 0
depth: 0
meta_title:
meta_description:
meta_keywords:
children_count: 0
parent_id:
description: ''
description_html: ''
image_url:
square_image_url:
is_root: true
is_child: false
is_leaf: true
external_references: {}
metadata: {}
pretty_name: Clothing
lft: 1
rgt: 2
products_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Category"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.
**Required scope:** `write_categories` (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 category = await client.categories.create({
name: 'Shirts',
parent_id: 'ctg_UkLWZg9DAJ',
description: '<p>Casual and dress shirts.</p>',
})
- lang: bash
label: Spree CLI
source: spree api post /categories -d '{"name":"Shirts","parent_id":"ctg_UkLWZg9DAJ","description":"<p>Casual
and dress shirts.</p>"}'
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
responses:
'201':
description: category created
content:
application/json:
example:
id: ctg_gbHJdmfrXB
name: Shirts
permalink: clothing/shirts
position: 0
depth: 1
meta_title:
meta_description:
meta_keywords:
children_count: 0
parent_id: ctg_UkLWZg9DAJ
description: ''
description_html: ''
image_url:
square_image_url:
is_root: false
is_child: true
is_leaf: true
external_references: {}
metadata: {}
pretty_name: Clothing -> Shirts
lft: 2
rgt: 3
products_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Category"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CategoryCreateParams"
required: true
"/api/v3/admin/categories/{id}":
get:
summary: Get a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single category by ID.
**Required scope:** `read_categories` (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 category = await client.categories.get('ctg_UkLWZg9DAJ', {
expand: ['children', 'ancestors'],
})
- lang: bash
label: Spree CLI
source: spree api get /categories/{id} -d '{"expand":["children","ancestors"]}'
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: id
in: path
required: true
description: Category ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., children, parent,
ancestors).
schema:
type: string
responses:
'200':
description: category found
content:
application/json:
example:
id: ctg_UkLWZg9DAJ
name: Clothing
permalink: clothing
position: 0
depth: 0
meta_title:
meta_description:
meta_keywords:
children_count: 0
parent_id:
description: ''
description_html: ''
image_url:
square_image_url:
is_root: true
is_child: false
is_leaf: true
external_references: {}
metadata: {}
pretty_name: Clothing
lft: 1
rgt: 2
products_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Category"
'404':
description: category not found
content:
application/json:
example:
error:
code: record_not_found
message: Category not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Updates a category.
**Required scope:** `write_categories` (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 category = await client.categories.update('ctg_UkLWZg9DAJ', {
name: 'Apparel',
meta_title: 'Apparel for every season',
})
- lang: bash
label: Spree CLI
source: spree api patch /categories/{id} -d '{"name":"Apparel","meta_title":"Apparel
for every season"}'
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: id
in: path
required: true
description: Category ID
schema:
type: string
responses:
'200':
description: category updated
content:
application/json:
example:
id: ctg_UkLWZg9DAJ
name: Apparel
permalink: clothing
position: 0
depth: 0
meta_title:
meta_description:
meta_keywords:
children_count: 0
parent_id:
description: ''
description_html: ''
image_url:
square_image_url:
is_root: true
is_child: false
is_leaf: true
external_references: {}
metadata: {}
pretty_name: Apparel
lft: 1
rgt: 2
products_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CategoryUpdateParams"
required: true
delete:
summary: Delete a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Deletes a category and its descendants.
**Required scope:** `write_categories` (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.categories.delete('ctg_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /categories/{id}
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: id
in: path
required: true
description: Category ID
schema:
type: string
responses:
'204':
description: category deleted
"/api/v3/admin/categories/{id}/reposition":
patch:
summary: Reposition a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Moves a category to a new parent and/or index within the tree.
**Required scope:** `write_categories` (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',
})
// Moves the category under a new parent, as its first child.
const category = await client.categories.reposition('ctg_gbHJdmfrXB', {
new_parent_id: 'ctg_UkLWZg9DAJ',
new_position: 0,
})
- lang: bash
label: Spree CLI
source: spree api patch /categories/{id}/reposition -d '{"new_parent_id":"ctg_UkLWZg9DAJ","new_position":0}'
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: id
in: path
required: true
description: Category ID
schema:
type: string
responses:
'200':
description: category repositioned
content:
application/json:
example:
id: ctg_gbHJdmfrXB
name: Footwear
permalink: clothing/footwear
position: 0
depth: 1
meta_title:
meta_description:
meta_keywords:
children_count: 0
parent_id: ctg_UkLWZg9DAJ
description: ''
description_html: ''
image_url:
square_image_url:
is_root: false
is_child: true
is_leaf: true
external_references: {}
metadata: {}
pretty_name: Clothing -> Footwear
lft: 2
rgt: 3
products_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CategoryRepositionParams"
required: true
"/api/v3/admin/categories/{category_id}/products":
get:
summary: List category products
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Products classified under the category, ordered by their classification position.
**Required scope:** `read_categories` (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.categories.products.list('ctg_UkLWZg9DAJ', {
limit: 25,
})
- lang: bash
label: Spree CLI
source: spree api get /categories/{category_id}/products -d '{"limit":25}'
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: category_id
in: path
required: true
description: Category ID
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches product name or variant SKU (partial, case-insensitive),
and the store's searchable custom fields.
- name: q[ascend_by_price]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `ascend_by_price`.
- name: q[descend_by_price]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `descend_by_price`.
- name: q[in_categories][]
in: query
required: false
schema:
type: array
items:
type: string
description: Applies `in_categories` to the given value.
- name: q[in_category]
in: query
required: false
schema:
type: string
description: Applies `in_category` to the given value.
- name: q[in_collection]
in: query
required: false
schema:
type: string
description: Applies `in_collection` to the given value.
- name: q[in_stock]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `in_stock`.
- name: q[in_taxon]
in: query
required: false
schema:
type: string
description: Applies `in_taxon` to the given value.
- name: q[not_discontinued]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `not_discontinued`.
- name: q[out_of_stock]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `out_of_stock`.
- name: q[price_between][]
in: query
required: false
schema:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: Applies `price_between` to the given value.
- name: q[price_gte]
in: query
required: false
schema:
type: number
description: Applies `price_gte` to the given value.
- name: q[price_lte]
in: query
required: false
schema:
type: number
description: Applies `price_lte` to the given value.
- name: q[search_by_name]
in: query
required: false
schema:
type: string
description: Applies `search_by_name` to the given value.
- name: q[with_option_value_ids][]
in: query
required: false
schema:
type: array
items:
type: string
description: Applies `with_option_value_ids` to the given value.
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
| `labels_` | `created_at`, `id`, `name`, `updated_at` |
| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
| `product_type_` | `created_at`, `id`, `name`, `updated_at` |
| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `store_` | `created_at`, `id`, `name`, `updated_at` |
| `tags_` | `created_at`, `id`, `name`, `updated_at` |
| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
</Accordion>
**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Product
sortable:
- available_on
- created_at
- description
- discontinue_on
- id
- name
- price
- seller_id
- slug
- status
- updated_at
responses:
'200':
description: products found
content:
application/json:
example:
data: []
meta:
page: 1
limit: 25
count: 0
pages: 1
from: 0
to: 0
in: 0
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Product"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Add products to a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.
**Required scope:** `write_categories` (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 { added_count } = await client.categories.products.create('ctg_UkLWZg9DAJ', [
'prod_UkLWZg9DAJ',
'prod_9XbR2kQwLm',
])
- lang: bash
label: Spree CLI
source: spree api post /categories/{category_id}/products -d '{ ... }'
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: category_id
in: path
required: true
description: Category ID
schema:
type: string
responses:
'201':
description: products added
content:
application/json:
example:
added_count: 1
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductMembershipParams"
required: true
delete:
summary: Remove products from a category
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.
**Required scope:** `write_categories` (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 { removed_count } = await client.categories.products.delete('ctg_UkLWZg9DAJ', [
'prod_UkLWZg9DAJ',
])
- lang: bash
label: Spree CLI
source: spree api delete /categories/{category_id}/products
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: category_id
in: path
required: true
description: Category ID
schema:
type: string
responses:
'200':
description: products removed
content:
application/json:
example:
removed_count: 1
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductMembershipParams"
required: true
"/api/v3/admin/categories/{category_id}/products/{id}/reposition":
patch:
summary: Reposition a category product
tags:
- Categories
operationId: categories_reposition_product
security:
- api_key: []
bearer_auth: []
description: |-
Moves a product to a new index among the category's products.
**Required scope:** `write_categories` (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',
})
// Moves the product to the top of the category; positions are 0-based.
await client.categories.products.reposition('ctg_UkLWZg9DAJ', 'prod_UkLWZg9DAJ', {
new_position: 0,
})
- lang: bash
label: Spree CLI
source: spree api patch /categories/{category_id}/products/{id}/reposition
-d '{"new_position":0}'
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: category_id
in: path
required: true
description: Category ID
schema:
type: string
- name: id
in: path
required: true
description: Product ID
schema:
type: string
responses:
'204':
description: product repositioned
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductMembershipRepositionParams"
required: true
"/api/v3/admin/categories/{category_id}/custom_fields":
get:
summary: List category custom fields
tags:
- Categories
security:
- api_key: []
bearer_auth: []
description: |-
Returns the category's custom field values.
**Required scope:** `read_categories` (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: customFields } = await client.categories.customFields.list('ctg_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /categories/{category_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: category_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomField"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/channels":
get:
summary: List channels
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Returns the channels configured for the current store.
**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: channels } = await client.channels.list()
- lang: bash
label: Spree CLI
source: spree api get /channels
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name (partial, case-insensitive).
- name: page
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Channel
sortable:
- active
- code
- created_at
- default
- id
- name
- store_id
- updated_at
responses:
'200':
description: channels found
content:
application/json:
example:
data:
- id: ch_UkLWZg9DAJ
name: Online Store
code: online
active: true
default: true
storefront_access:
guest_checkout:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
order_routing_strategy:
stock_location_ids: []
default_catalog_id:
- id: ch_gbHJdmfrXB
name: Wholesale
code: wholesale
active: true
default: false
storefront_access:
guest_checkout:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
order_routing_strategy:
stock_location_ids: []
default_catalog_id:
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Channel"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Creates a new channel on the current store. `code` is normalized to a
URL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's
derived from `name`.
**Required scope:** `write_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',
})
// `code` is optional — when omitted it's derived from `name`
// ("Point of Sale" → "point-of-sale").
const channel = await client.channels.create({
name: 'Point of Sale',
code: 'pos',
active: true,
})
- lang: bash
label: Spree CLI
source: spree api post /channels -d '{"name":"Point of Sale","code":"pos","active":true}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: channel created
content:
application/json:
example:
id: ch_EfhxLZ9ck8
name: Marketplace
code: marketplace
active: true
default: false
storefront_access:
guest_checkout:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
order_routing_strategy:
stock_location_ids: []
default_catalog_id:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ChannelCreateParams"
required: true
"/api/v3/admin/channels/{id}":
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
summary: Get a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: "**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 channel = await client.channels.get('channel_xxx')
- lang: bash
label: Spree CLI
source: spree api get /channels/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: channel found
content:
application/json:
example:
id: ch_gbHJdmfrXB
name: Wholesale
code: wholesale
active: true
default: false
storefront_access:
guest_checkout:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
order_routing_strategy:
stock_location_ids: []
default_catalog_id:
patch:
summary: Update a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_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 channel = await client.channels.update('channel_xxx', {
name: 'Wholesale (Updated)',
active: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /channels/{id} -d '{"name":"Wholesale (Updated)","active":false}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: channel updated
content:
application/json:
example:
id: ch_gbHJdmfrXB
name: Wholesale (Updated)
code: wholesale
active: true
default: false
storefront_access: login_required
guest_checkout: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
order_routing_strategy:
stock_location_ids: []
default_catalog_id:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ChannelUpdateParams"
required: true
delete:
summary: Delete a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_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',
})
await client.channels.delete('channel_xxx')
- lang: bash
label: Spree CLI
source: spree api delete /channels/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: channel deleted
"/api/v3/admin/channels/{id}/add_products":
parameters:
- name: id
in: path
required: true
schema:
type: string
post:
summary: Publish products on a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Publishes the listed products on this channel. Idempotent — re-publishing
an already-published product updates its publication window. Products from
sibling stores are silently dropped.
**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',
})
// Idempotent — re-publishing an already-published product updates its
// publication window. `published_at`/`unpublished_at` are optional:
// `null` (or omitted) means live immediately and never come down.
const { product_count } = await client.channels.addProducts('channel_xxx', {
product_ids: ['prod_xxx', 'prod_yyy'],
published_at: '2026-07-01T00:00:00Z',
})
- lang: bash
label: Spree CLI
source: spree api post /channels/{id}/add_products -d '{"product_ids":["prod_xxx","prod_yyy"],"published_at":"2026-07-01T00:00:00Z"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products published
content:
application/json:
example:
product_count: 1
schema:
type: object
properties:
product_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ChannelAddProductsParams"
required: true
"/api/v3/admin/channels/{id}/remove_products":
parameters:
- name: id
in: path
required: true
schema:
type: string
post:
summary: Unpublish products from a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Unpublishes the listed products from this channel.
**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_count } = await client.channels.removeProducts('channel_xxx', {
product_ids: ['prod_xxx', 'prod_yyy'],
})
- lang: bash
label: Spree CLI
source: spree api post /channels/{id}/remove_products -d '{"product_ids":["prod_xxx","prod_yyy"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products unpublished
content:
application/json:
example:
product_count: 1
schema:
type: object
properties:
product_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ChannelRemoveProductsParams"
required: true
"/api/v3/admin/channels/{channel_id}/order_routing_rules":
parameters:
- name: channel_id
in: path
required: true
schema:
type: string
get:
summary: List order routing rules for a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.
**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: rules } = await client.channels.orderRoutingRules.list('ch_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /channels/{channel_id}/order_routing_rules
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[active_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `channel_id`, `created_at`, `id`, `position`, `store_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: OrderRoutingRule
sortable:
- active
- channel_id
- created_at
- id
- position
- store_id
- type
- updated_at
responses:
'200':
description: rules found
content:
application/json:
example:
data:
- id: orule_UkLWZg9DAJ
position: 1
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
- id: orule_gbHJdmfrXB
position: 2
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: minimize_splits
channel_id: ch_UkLWZg9DAJ
preferences: {}
- id: orule_EfhxLZ9ck8
position: 3
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
meta:
page: 1
limit: 25
count: 3
pages: 1
from: 1
to: 3
in: 3
previous:
next:
post:
summary: Create an order routing rule on a channel
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.
**Required scope:** `write_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 rule = await client.channels.orderRoutingRules.create('ch_UkLWZg9DAJ', {
type: 'preferred_location',
})
- lang: bash
label: Spree CLI
source: spree api post /channels/{channel_id}/order_routing_rules -d '{"type":"preferred_location"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: rule created
content:
application/json:
example:
id: orule_VqXmZF31wY
position: 3
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
'422':
description: unknown rule type
content:
application/json:
example:
error:
code: unknown_order_routing_rule_type
message: Unknown type
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OrderRoutingRuleCreateParams"
required: true
"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":
parameters:
- name: channel_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
patch:
summary: Update an order routing rule
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.
**Required scope:** `write_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 rule = await client.channels.orderRoutingRules.update('ch_UkLWZg9DAJ', 'orule_k5nR8xLq', {
active: false,
position: 2,
})
- lang: bash
label: Spree CLI
source: spree api patch /channels/{channel_id}/order_routing_rules/{id} -d
'{"active":false,"position":2}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: rule updated
content:
application/json:
example:
id: orule_UkLWZg9DAJ
position: 2
active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OrderRoutingRuleUpdateParams"
required: true
delete:
summary: Delete an order routing rule
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_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',
})
await client.channels.orderRoutingRules.delete('ch_UkLWZg9DAJ', 'orule_k5nR8xLq')
- lang: bash
label: Spree CLI
source: spree api delete /channels/{channel_id}/order_routing_rules/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: rule deleted
"/api/v3/admin/order_routing_rules/types":
get:
summary: List available order routing rule types
tags:
- Channels
security:
- api_key: []
bearer_auth: []
description: |-
Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the "Add rule" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.
**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: ruleTypes } = await client.orderRoutingRules.types()
- lang: bash
label: Spree CLI
source: spree api get /order_routing_rules/types
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: types found
content:
application/json:
example:
data:
- type: default_location
label: Default location
description: Prefer the stock location marked as default
schema:
type: object
properties: {}
additionalProperties: false
- type: minimize_splits
label: Minimize splits
description: Prefer the location that can fulfill the most items
on its own, avoiding split shipments
schema:
type: object
properties: {}
additionalProperties: false
- type: preferred_location
label: Preferred location
description: Fulfill from the location pinned on the order, when
one is set
schema:
type: object
properties: {}
additionalProperties: false
"/api/v3/admin/custom_field_definitions":
get:
summary: List custom field definitions
tags:
- Custom Fields
security:
- api_key: []
bearer_auth: []
description: |-
Returns all defined custom fields. Filter by `?q[resource_type_eq]=product` to narrow to one parent type.
**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: definitions } = await client.customFieldDefinitions.list({
resource_type_eq: 'product',
})
- lang: bash
label: Spree CLI
source: spree api get /custom_field_definitions -d '{"resource_type_eq":"product"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of namespace, key, and label (partial, case-insensitive).
- name: expand
in: query
required: false
description: Comma-separated associations to expand. Use dot notation for
nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,label,field_type).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[key_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `field_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `key` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `namespace` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `resource_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `searchable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `sortable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `field_type`, `id`, `key`, `label`, `namespace`, `resource_type`, `searchable`, `sortable`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomFieldDefinition
sortable:
- created_at
- field_type
- id
- key
- label
- namespace
- resource_type
- searchable
- sortable
- storefront_visible
- updated_at
responses:
'200':
description: definitions returned
content:
application/json:
example:
data:
- id: cfdef_UkLWZg9DAJ
namespace: specs
key: fabric
label: Title
field_type: short_text
storefront_visible: true
searchable: false
sortable: false
filter_key: cf_specs_fabric
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
resource_type: product
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
label: Order Notes
field_type: short_text
storefront_visible: true
searchable: false
sortable: false
filter_key: cf_custom_order_notes
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
resource_type: order
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous:
next:
post:
summary: Create a custom field definition
tags:
- Custom Fields
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_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 definition = await client.customFieldDefinitions.create({
namespace: 'specs',
key: 'origin',
label: 'Country of Origin',
field_type: 'short_text',
resource_type: 'product',
storefront_visible: true,
})
- lang: bash
label: Spree CLI
source: spree api post /custom_field_definitions -d '{"namespace":"specs","key":"origin","label":"Country
of Origin","field_type":"short_text","resource_type":"product","storefront_visible":true}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: definition created
content:
application/json:
example:
id: cfdef_EfhxLZ9ck8
namespace: specs
key: origin
label: Country of Origin
field_type: short_text
storefront_visible: true
searchable: false
sortable: false
filter_key: cf_specs_origin
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
resource_type: product
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomFieldDefinitionCreateParams"
required: true
"/api/v3/admin/custom_field_definitions/{id}":
get:
summary: Show a custom field definition
tags:
- Custom Fields
security:
- api_key: []
bearer_auth: []
description: "**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 definition = await client.customFieldDefinitions.get('cfd_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /custom_field_definitions/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand. Use dot notation for
nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,label,field_type).
id is always included.
schema:
type: string
responses:
'200':
description: definition found
content:
application/json:
example:
id: cfdef_UkLWZg9DAJ
namespace: specs
key: fabric
label: Title
field_type: short_text
storefront_visible: true
searchable: false
sortable: false
filter_key: cf_specs_fabric
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
resource_type: product
patch:
summary: Update a custom field definition
tags:
- Custom Fields
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_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 definition = await client.customFieldDefinitions.update('cfd_UkLWZg9DAJ', {
label: 'Country of Origin',
storefront_visible: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /custom_field_definitions/{id} -d '{"label":"Country
of Origin","storefront_visible":false}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: definition updated
content:
application/json:
example:
id: cfdef_UkLWZg9DAJ
namespace: specs
key: fabric
label: Fabric Composition
field_type: short_text
storefront_visible: false
searchable: false
sortable: false
filter_key: cf_specs_fabric
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
resource_type: product
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomFieldDefinitionUpdateParams"
required: true
delete:
summary: Delete a custom field definition
tags:
- Custom Fields
security:
- api_key: []
bearer_auth: []
description: |-
Deletes the definition and cascades to all custom field values referencing it.
**Required scope:** `write_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',
})
await client.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /custom_field_definitions/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: definition deleted
"/api/v3/admin/customer_groups":
get:
summary: List customer groups
tags:
- Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
Returns the customer groups configured for the current store. Groups
segment customers for targeted promotions (see the `customer_group`
promotion rule) and reporting. The list endpoint never embeds the
member list — fetch a single group with `?expand=customers` if you
need them inline, or query `/admin/customers?customer_group_id_in=…`
for paginated membership.
**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: groups } = await client.customerGroups.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
source: spree api get /customer_groups -d '{"page":1,"limit":25}'
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: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomerGroup
sortable:
- created_at
- id
- name
- updated_at
responses:
'200':
description: customer groups found
content:
application/json:
example:
data:
- id: cg_UkLWZg9DAJ
name: VIPs
description: Top spenders
customers_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomerGroup"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a customer group
tags:
- Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
Creates a customer group in the current store. `customer_ids` is
optional; when present, customers are attached at create time.
Pass prefixed IDs (e.g. `cus_…`) — the server decodes them
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 group = await client.customerGroups.create({
name: 'VIP customers',
description: 'Top spenders, eligible for early access',
customer_ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
})
- lang: bash
label: Spree CLI
source: spree api post /customer_groups -d '{"name":"VIP customers","description":"Top
spenders, eligible for early access","customer_ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: customer group created
content:
application/json:
example:
id: cg_EfhxLZ9ck8
name: Wholesale 2
description: B2B accounts
customers_count: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerGroupCreateParams"
required: true
"/api/v3/admin/customer_groups/{id}":
parameters:
- name: id
in: path
required: true
description: Customer group prefixed ID
schema:
type: string
get:
summary: Get a customer group
tags:
- Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single customer group. Pass `?expand=customers` to embed
the full member list inline (recommended only for single-record
reads — embed cost scales with membership size).
**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',
})
// Pass `expand: ['customers']` to embed the group's customers in the response
// — omit it for the much smaller index-payload shape.
const group = await client.customerGroups.get('cg_UkLWZg9DAJ', { expand: ['customers'] })
- lang: bash
label: Spree CLI
source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: expand
in: query
required: false
description: 'Comma-separated associations to embed. Supported: `customers`.'
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
description: customer group with embedded customers
content:
application/json:
example:
id: cg_UkLWZg9DAJ
name: VIPs
description: Top spenders
customers_count: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customers:
- id: cust_UkLWZg9DAJ
email: [email protected]
first_name: Dan
last_name: Ebert
phone:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Dan Ebert
available_store_credit_total: '0.00'
failed_attempts: 0
metadata: {}
email_marketing_consent_source: unknown
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
anonymized_at:
anonymized: false
tags: []
internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
total_spent: '0.00'
last_order_completed_at:
customer_group_ids:
- cg_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/CustomerGroup"
'404':
description: customer group not found
content:
application/json:
example:
error:
code: record_not_found
message: Customer group not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a customer group
tags:
- Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
Updates name, description, or membership. `customer_ids` is a
full-set replacement — the server reconciles the membership to
match the array, adding new IDs and removing ones not present.
Send `customer_ids: []` to clear all members.
**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',
})
// `customer_ids` is a full-set update — the model reconciles the membership
// to match the array (adds new IDs, removes ones not present).
const group = await client.customerGroups.update('cg_UkLWZg9DAJ', {
name: 'VIP customers (Q1)',
customer_ids: ['cus_UkLWZg9DAJ'],
})
- lang: bash
label: Spree CLI
source: spree api patch /customer_groups/{id} -d '{"name":"VIP customers (Q1)","customer_ids":["cus_UkLWZg9DAJ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: customer group updated
content:
application/json:
example:
id: cg_UkLWZg9DAJ
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerGroupUpdateParams"
required: true
delete:
summary: Delete a customer group
tags:
- Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.
**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.customerGroups.delete('cg_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /customer_groups/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: customer group deleted
"/api/v3/admin/customers/{customer_id}/custom_fields":
get:
summary: List customer custom fields
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Returns the customer's custom field values.
**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: customFields } = await client.customers.customFields.list('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /customers/{customer_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomField"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/customers/{id}/export":
get:
summary: Export a customer's personal data
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Returns everything the store holds about this customer, for answering a
GDPR right-of-access request (Art. 15) that reached the merchant
directly.
**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',
})
// Everything the store holds about the customer, to answer a GDPR access request:
const customerData = await client.customers.export('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /customers/{id}/export
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: customer data
content:
application/json:
example:
account:
id: cust_UkLWZg9DAJ
email: [email protected]
first_name: Jane
last_name: Doe
phone:
selected_locale:
tags: []
metadata:
internal_note:
created_at: '2026-01-15T12:00:00Z'
anonymized_at:
marketing_consent:
accepts_email_marketing: false
consent_updated_at: '2026-01-15T12:00:00Z'
consent_source: unknown
newsletter_subscriptions: []
consent_records: []
addresses: []
orders: []
draft_orders: []
order_groups: []
carts: []
payment_sources: []
connected_logins: []
store_credits: []
gift_cards: []
wishlists: []
custom_fields: []
companies: []
tax_identifiers: []
exported_at: '2026-01-15T12:00:00Z'
schema:
type: object
properties:
account:
type: object
marketing_consent:
type: object
consent_records:
type: array
items:
type: object
addresses:
type: array
items:
type: object
orders:
type: array
items:
type: object
exported_at:
type: string
'404':
description: not found
content:
application/json:
example:
error:
code: record_not_found
message: Customer not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/customers/{id}/anonymize":
post:
x-spree-agent: false
x-spree-agent-reason: Irreversible erasure of a person's data under GDPR Art.
17, which is not something to offer a model behind one confirmation prompt.
summary: Erase a customer's personal data
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Carries out a GDPR right-to-erasure request (Art. 17). Personal data is
replaced across the account, its addresses, the address snapshots on
past orders, saved cards, connected identities and live sessions.
Orders, payments and tax records are kept — they carry their own
retention obligation — with the personal details removed. The country,
state and a truncated postal code survive on order addresses so the tax
jurisdiction of a past sale stays provable.
Irreversible.
**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',
})
// Irreversible: personal data is erased, orders and payments are kept.
const customer = await client.customers.anonymize('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api post /customers/{id}/anonymize -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: customer anonymized
content:
application/json:
example:
id: cust_UkLWZg9DAJ
email: anonymized-87c6bfa6-4803-420c-a5e2-b1c962f0f40a@invalid
first_name: Redacted
last_name: Redacted
phone:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Redacted Redacted
available_store_credit_total: '0.00'
failed_attempts: 0
metadata: {}
email_marketing_consent_source: anonymization
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
anonymized_at: '2026-01-15T12:00:00Z'
anonymized: true
tags: []
internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
total_spent: '0.00'
last_order_completed_at:
customer_group_ids: []
schema:
type: object
properties:
id:
type: string
email:
type: string
anonymized:
type: boolean
anonymized_at:
type: string
nullable: true
"/api/v3/admin/consent_records":
get:
summary: List consent records
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Returns the consents customers gave or withdrew, newest first, as evidence of what each one agreed to and when.
**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: consentRecords } = await client.consentRecords.list({
email_eq: '[email protected]',
sort: '-recorded_at',
})
- lang: bash
label: Spree CLI
source: spree api get /consent_records -d '{"email_eq":"[email protected]","sort":"-recorded_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `accepted` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `purpose` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `recorded_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `source` | One of `checkout`, `registration`, `account`, `admin`, `newsletter`, `anonymization`, `unknown`, `import`, `storefront` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `accepted`, `created_at`, `email`, `id`, `purpose`, `recorded_at`, `source`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: ConsentRecord
sortable:
- accepted
- created_at
- email
- id
- purpose
- recorded_at
- source
- updated_at
responses:
'200':
description: consent records found
content:
application/json:
example:
data:
- id: consent_UkLWZg9DAJ
purpose: terms_of_service
source: registration
accepted: true
email: [email protected]
ip_address:
created_at: '2026-01-15T12:00:00.000Z'
recorded_at: '2026-01-15T12:00:00Z'
documents: []
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/ConsentRecord"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/data_requests":
get:
summary: List data requests
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Returns the requests customers made to export or erase their personal data, newest first.
**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: dataRequests } = await client.dataRequests.list({
kind_eq: 'erasure',
sort: '-requested_at',
})
- lang: bash
label: Spree CLI
source: spree api get /data_requests -d '{"kind_eq":"erasure","sort":"-requested_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[access]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `access`.
- name: q[erasure]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `erasure`.
- name: q[in_progress]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `in_progress`.
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `kind` | One of `access`, `erasure` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `requested_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `status` | One of `awaiting_confirmation`, `pending`, `processing`, `completed`, `failed`, `lapsed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `completed_at`, `created_at`, `email`, `id`, `kind`, `number`, `requested_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: DataRequest
sortable:
- completed_at
- created_at
- email
- id
- kind
- number
- requested_at
- status
- updated_at
responses:
'200':
description: data requests found
content:
application/json:
example:
data:
- id: dsr_UkLWZg9DAJ
number: DSR1001
kind: access
status: pending
requested_at: '2026-01-15T12:00:00Z'
completed_at:
expires_at:
email: [email protected]
error_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id: cust_UkLWZg9DAJ
requested_by_id:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/DataRequest"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Record a data request
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Records a request a customer made to the merchant directly, to export
or erase their personal data, and starts answering it. A request of the
same kind already in progress for the customer is returned instead of a
second one.
**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 dataRequest = await client.dataRequests.create({
customer_id: 'cus_UkLWZg9DAJ',
kind: 'access',
})
- lang: bash
label: Spree CLI
source: spree api post /data_requests -d '{"customer_id":"cus_UkLWZg9DAJ","kind":"access"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'202':
description: data request recorded
content:
application/json:
example:
id: dsr_UkLWZg9DAJ
number: DSR1001
kind: access
status: pending
requested_at: '2026-01-15T12:00:00Z'
completed_at:
expires_at:
email: [email protected]
error_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id: cust_UkLWZg9DAJ
requested_by_id: adm_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/DataRequest"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/DataRequestCreateParams"
required: true
"/api/v3/admin/customers/{customer_id}/addresses":
get:
summary: List customer addresses
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Returns the customer's saved addresses.
**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: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /customers/{customer_id}/addresses
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., country, state).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., first_name,last_name,address1,city).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[address1_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `country_code` | One of the `CountryCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Address
sortable:
- address1
- address2
- city
- company
- country_code
- created_at
- first_name
- id
- last_name
- phone
- postal_code
- state_code
- updated_at
responses:
'200':
description: addresses found
content:
application/json:
example:
data:
- id: addr_UkLWZg9DAJ
label:
first_name: John
last_name: Doe
full_name: John Doe
address1: 27 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
phone: 555-555-0199
company: Company
country_name: United States
country_code: US
state_text: NY
state_code: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
state_name: New York
owner:
id: cust_UkLWZg9DAJ
type: customer
name:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
latitude:
longitude:
customer_id: cust_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create a customer address
tags:
- 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.
**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_code: 'US',
state_code: 'NY',
phone: '+1 212 555 1234',
label: 'Office',
is_default_shipping: true,
})
- lang: bash
label: Spree CLI
source: spree api post /customers/{customer_id}/addresses -d '{"first_name":"Jane","last_name":"Doe","address1":"350
Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
212 555 1234","label":"Office","is_default_shipping":true}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
responses:
'201':
description: address created
content:
application/json:
example:
id: addr_gbHJdmfrXB
label: Office
first_name: Jane
last_name: Doe
full_name: Jane Doe
address1: 350 Fifth Avenue
address2:
postal_code: '10118'
city: New York
phone: "+12125551234"
company:
country_name: United States
country_code: US
state_text: NY
state_code: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
state_name: New York
owner:
id: cust_UkLWZg9DAJ
type: customer
name:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
latitude:
longitude:
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerAddressCreateParams"
required: true
"/api/v3/admin/customers/{customer_id}/addresses/{id}":
patch:
summary: Update a customer address
tags:
- 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',
})
- lang: bash
label: Spree CLI
source: spree api patch /customers/{customer_id}/addresses/{id} -d '{"city":"Manhattan"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: address updated
content:
application/json:
example:
id: addr_UkLWZg9DAJ
label:
first_name: John
last_name: Doe
full_name: John Doe
address1: 29 Lovely Street
address2: Northwest
postal_code: '10118'
city: Manhattan
phone: 555-555-0199
company: Company
country_name: United States
country_code: US
state_text: NY
state_code: NY
quick_checkout: false
is_default_billing: false
is_default_shipping: false
state_name: New York
owner:
id: cust_UkLWZg9DAJ
type: customer
name:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
latitude:
longitude:
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerAddressUpdateParams"
required: true
delete:
summary: Delete a customer address
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /customers/{customer_id}/addresses/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: address deleted
"/api/v3/admin/customers/{customer_id}/credit_cards":
get:
summary: List customer credit cards
tags:
- 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 }`.
**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')
- lang: bash
label: Spree CLI
source: spree api get /customers/{customer_id}/credit_cards
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., payment_method).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., brand,last4,month,year).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CreditCard
sortable:
- created_at
- id
- name
- updated_at
responses:
'200':
description: credit cards found
content:
application/json:
example:
data:
- id: card_UkLWZg9DAJ
brand: visa
last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":
get:
summary: Show a customer credit card
tags:
- 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')
- lang: bash
label: Spree CLI
source: spree api get /customers/{customer_id}/credit_cards/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., payment_method).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., brand,last4,month,year).
id is always included.
schema:
type: string
responses:
'200':
description: credit card found
content:
application/json:
example:
id: card_UkLWZg9DAJ
brand: visa
last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delete:
summary: Delete a customer credit card
tags:
- 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')
- lang: bash
label: Spree CLI
source: spree api delete /customers/{customer_id}/credit_cards/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: credit card deleted
"/api/v3/admin/customers/{customer_id}/store_credits":
get:
summary: List customer store credits
tags:
- 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')
- lang: bash
label: Spree CLI
source: spree api get /customers/{customer_id}/store_credits
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of memo (partial, case-insensitive).
- name: q[from_gift_card]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `from_gift_card`.
- name: q[outstanding]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `outstanding`.
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., store, created_by).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[memo_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `memo` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `amount`, `created_at`, `created_by_id`, `currency`, `customer_id`, `id`, `memo`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: StoreCredit
sortable:
- amount
- created_at
- created_by_id
- currency
- customer_id
- id
- memo
- updated_at
responses:
'200':
description: store credits found
content:
application/json:
example:
data:
- id: credit_UkLWZg9DAJ
amount: '50.00'
amount_used: '0.00'
amount_remaining: '50.00'
currency: USD
memo:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
amount_authorized: '0.00'
outstanding: true
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
originator_type:
originator_id:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Issue a store credit to a customer
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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',
memo: 'Goodwill credit',
})
- lang: bash
label: Spree CLI
source: spree api post /customers/{customer_id}/store_credits -d '{"amount":"25.00","currency":"USD","memo":"Goodwill
credit"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
responses:
'201':
description: store credit created
content:
application/json:
example:
id: credit_gbHJdmfrXB
amount: '25.00'
amount_used: '0.00'
amount_remaining: '25.00'
currency: USD
memo: Goodwill
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
amount_authorized: '0.00'
outstanding: true
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_gbHJdmfrXB
created_by_type: admin_user
originator_type:
originator_id:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerStoreCreditCreateParams"
required: true
"/api/v3/admin/customers/{customer_id}/store_credits/{id}":
patch:
summary: Update a store credit
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Update memo / 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',
})
- lang: bash
label: Spree CLI
source: spree api patch /customers/{customer_id}/store_credits/{id} -d '{"memo":"Reissued
for damaged shipment"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: store credit updated
content:
application/json:
example:
id: credit_UkLWZg9DAJ
amount: '50.00'
amount_used: '0.00'
amount_remaining: '50.00'
currency: USD
memo: Updated
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
amount_authorized: '0.00'
outstanding: true
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
originator_type:
originator_id:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerStoreCreditUpdateParams"
required: true
delete:
summary: Delete a store credit
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /customers/{customer_id}/store_credits/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: store credit deleted
"/api/v3/admin/customers/{customer_id}/tax_identifiers":
get:
summary: List customer tax registrations
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Returns the customer's own tax registrations, one per kind.
**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: registrations } = await client.customers.taxIdentifiers.list('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /customers/{customer_id}/tax_identifiers
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: TaxIdentifier
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: registrations found
content:
application/json:
example:
data:
- id: txi_UkLWZg9DAJ
kind: eu_vat
value: DE100000016
validation_status:
validation_evidence:
source:
validated_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
validatable: false
customer_id: cust_UkLWZg9DAJ
cart_id:
order_id:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/TaxIdentifier"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/customers/{customer_id}/tax_identifiers/{id}":
patch:
summary: Update a customer tax registration
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Corrects a registration number. A changed number is checked again before it counts as verified.
**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 registration = await client.customers.taxIdentifiers.update(
'cus_UkLWZg9DAJ',
'txi_UkLWZg9DAJ',
{ value: 'DE123456789' },
)
- lang: bash
label: Spree CLI
source: spree api patch /customers/{customer_id}/tax_identifiers/{id} -d '{"value":"DE123456789"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: registration updated
content:
application/json:
example:
id: txi_UkLWZg9DAJ
kind: eu_vat
value: DE100000008
validation_status:
validation_evidence:
source:
validated_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
validatable: false
customer_id: cust_UkLWZg9DAJ
cart_id:
order_id:
schema:
"$ref": "#/components/schemas/TaxIdentifier"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/TaxIdentifierUpdateParams"
required: true
"/api/v3/admin/customers/{customer_id}/tax_identifiers/{id}/validate":
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: customer_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
post:
summary: Re-check a customer tax registration
tags:
- 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 registration = await client.customers.taxIdentifiers.validate(
'cust_UkLWZg9DAJ',
'txi_UkLWZg9DAJ',
)
- lang: bash
label: Spree CLI
source: spree api post /customers/{customer_id}/tax_identifiers/{id}/validate
-d '{ ... }'
operationId: customer_tax_identifiers_validate
security:
- api_key: []
bearer_auth: []
description: |-
Asks the registry again. Manual because a registry answers only "valid now" — a number verified
last year may have been deregistered since — and because a check that came back unavailable
cannot otherwise be retried without editing the number.
**Required scope:** `write_customers` (for API-key authentication).
responses:
'202':
description: registry check queued
content:
application/json:
example:
id: txi_UkLWZg9DAJ
kind: eu_vat
value: DE100000032
validation_status: pending
validation_evidence:
source:
validated_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
validatable: true
customer_id: cust_UkLWZg9DAJ
cart_id:
order_id:
schema:
"$ref": "#/components/schemas/TaxIdentifier"
'422':
description: no validator installed for this kind
content:
application/json:
example:
error:
code: tax_id_not_validatable
message: No registry validator is installed for tax identifier kind
'eu_vat'
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/customers":
get:
summary: List customers
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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,
})
- lang: bash
label: Spree CLI
source: spree api get /customers -d '{"search":"jane","sort":"-created_at","limit":25}'
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: q[search]
in: query
required: false
schema:
type: string
description: Matches email, first name, last name or full name (partial, case-insensitive).
- name: q[anonymized]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `anonymized`.
- name: q[with_min_total_spent]
in: query
required: false
schema:
type: number
description: Applies `with_min_total_spent` to the given value.
- name: q[with_standing_for_company][]
in: query
required: false
schema:
type: array
items:
type: string
description: Applies `with_standing_for_company` to the given value.
- name: page
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., addresses, store_credits).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., email,first_name,last_name).
id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `accepts_email_marketing` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[addresses_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Customer
sortable:
- accepts_email_marketing
- created_at
- email
- first_name
- id
- last_name
- phone
- updated_at
responses:
'200':
description: customers found
content:
application/json:
example:
data:
- id: cust_UkLWZg9DAJ
email: [email protected]
first_name: Jane
last_name: Doe
phone:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Jane Doe
available_store_credit_total: '0.00'
failed_attempts: 0
metadata: {}
email_marketing_consent_source: unknown
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
anonymized_at:
anonymized: false
tags: []
internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
total_spent: '0.00'
last_order_completed_at:
customer_group_ids: []
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create a customer
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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,
})
- lang: bash
label: Spree CLI
source: spree api post /customers -d '{"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
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: customer created
content:
application/json:
example:
id: cust_gbHJdmfrXB
email: [email protected]
first_name: New
last_name: Customer
phone:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: New Customer
available_store_credit_total: '0.00'
failed_attempts: 0
metadata: {}
email_marketing_consent_source: unknown
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
anonymized_at:
anonymized: false
tags: []
internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
total_spent: '0.00'
last_order_completed_at:
customer_group_ids: []
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerCreateParams"
required: true
"/api/v3/admin/customers/{id}":
get:
summary: Show a customer
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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'],
})
- lang: bash
label: Spree CLI
source: spree api get /customers/{id} -d '{"expand":["addresses","store_credits"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
description: Customer ID
schema:
type: string
- name: expand
in: query
required: false
description: 'Comma-separated associations: addresses, orders, store_credits,
default_billing_address, default_shipping_address'
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., email,first_name,last_name).
id is always included.
schema:
type: string
responses:
'200':
description: customer found
content:
application/json:
example:
id: cust_UkLWZg9DAJ
email: [email protected]
first_name: Jane
last_name: Doe
phone:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Jane Doe
available_store_credit_total: '0.00'
failed_attempts: 0
metadata: {}
email_marketing_consent_source: unknown
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
anonymized_at:
anonymized: false
tags: []
internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
total_spent: '0.00'
last_order_completed_at:
customer_group_ids: []
patch:
summary: Update a customer
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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'],
})
- lang: bash
label: Spree CLI
source: spree api patch /customers/{id} -d '{"first_name":"Updated","tags":["wholesale","vip"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: customer updated
content:
application/json:
example:
id: cust_UkLWZg9DAJ
email: [email protected]
first_name: Updated
last_name: Doe
phone:
accepts_email_marketing: false
email_marketing_consent_updated_at: '2026-01-15T12:00:00Z'
full_name: Updated Doe
available_store_credit_total: '0.00'
failed_attempts: 0
metadata: {}
email_marketing_consent_source: unknown
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
anonymized_at:
anonymized: false
tags: []
internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
orders_count: 0
total_spent: '0.00'
last_order_completed_at:
customer_group_ids: []
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerUpdateParams"
required: true
delete:
summary: Delete a customer
tags:
- Customers
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /customers/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: customer deleted
"/api/v3/admin/customers/bulk_add_to_groups":
post:
summary: Bulk-add customers to groups
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Attaches each customer in `ids` to every group in `customer_group_ids`.
Idempotent — customers already in a group are skipped server-side.
Groups from sibling stores are silently ignored. Returns counts of
customers and groups that were processed (post store-scoping).
**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 result = await client.customers.bulkAddToGroups({
ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
customer_group_ids: ['cg_UkLWZg9DAJ'],
})
- lang: bash
label: Spree CLI
source: spree api post /customers/bulk_add_to_groups -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: customers added to groups
content:
application/json:
example:
customer_count: 1
customer_group_count: 1
schema:
type: object
properties:
customer_count:
type: integer
customer_group_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerBulkGroupsParams"
required: true
"/api/v3/admin/customers/bulk_remove_from_groups":
post:
summary: Bulk-remove customers from groups
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Detaches each customer in `ids` from every group in `customer_group_ids`.
No-op for non-members. Groups from sibling stores are silently ignored.
**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 result = await client.customers.bulkRemoveFromGroups({
ids: ['cus_UkLWZg9DAJ'],
customer_group_ids: ['cg_UkLWZg9DAJ'],
})
- lang: bash
label: Spree CLI
source: spree api post /customers/bulk_remove_from_groups -d '{"ids":["cus_UkLWZg9DAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: customers removed from groups
content:
application/json:
example:
customer_count: 1
customer_group_count: 1
schema:
type: object
properties:
customer_count:
type: integer
customer_group_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomerBulkGroupsParams"
required: true
"/api/v3/admin/customers/bulk_add_tags":
post:
summary: Bulk-add tags to customers
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Adds each tag name in `tags` to every customer in `ids`. Tags are
upserted by name; re-adding an existing tag is a no-op.
**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 result = await client.customers.bulkAddTags({
ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
tags: ['vip', 'newsletter'],
})
- lang: bash
label: Spree CLI
source: spree api post /customers/bulk_add_tags -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"tags":["vip","newsletter"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: tags added
content:
application/json:
example:
customer_count: 1
tag_count: 2
schema:
type: object
properties:
customer_count:
type: integer
tag_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/BulkTagsParams"
required: true
"/api/v3/admin/customers/bulk_remove_tags":
post:
summary: Bulk-remove tags from customers
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
Removes each tag name in `tags` from every customer in `ids`. No-op
for customers that don't carry the tag.
**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 result = await client.customers.bulkRemoveTags({
ids: ['cus_UkLWZg9DAJ'],
tags: ['vip'],
})
- lang: bash
label: Spree CLI
source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: tags removed
content:
application/json:
example:
customer_count: 1
tag_count: 1
schema:
type: object
properties:
customer_count:
type: integer
tag_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/BulkTagsParams"
required: true
"/api/v3/admin/email_templates":
get:
summary: List email templates
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Returns every email template merchants may edit: the emails customers
receive, the email layout and the shared partials. Each shows what
customers receive now (the store's published version, else Spree's
default) and any draft in progress. Staff emails are not editable.
**Required scope:** `read_email_templates` (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 templates = await client.emailTemplates.list()
- lang: bash
label: Spree CLI
source: spree api get /email_templates
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: language
in: query
required: false
description: A language code, or `any` (the default) for the version every
language uses
schema:
type: string
responses:
'200':
description: email templates found
content:
application/json:
example:
data:
- id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Order {{ order.number }} confirmed
body: "<mj-section><mj-column><mj-text>Thanks for your order, {{
order.customer_name }}!</mj-text></mj-column></mj-section>\n"
language: any
customized_languages: []
kind: email
customized: false
published_at:
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language:
default_changed: false
base_subject:
base_body:
draft:
- id: layouts.spree.base_mailer
key: layouts/spree/base_mailer
subject:
body: |
{% assign brand = store.branding %}<mjml lang="{{ locale }}">
<mj-head>
<mj-title>{{ subject }}</mj-title>
{% if brand.font_url %}<mj-font name="{{ brand.font_family | split: ',' | first }}" href="{{ brand.font_url }}" />{% endif %}
<mj-attributes>
<mj-all font-family="{{ brand.font_family }}" />
<mj-section padding="0" />
<mj-column padding="0" />
<mj-text padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" align="center" />
<mj-button background-color="{{ brand.button_color }}" border="{{ brand.button_border }}" border-radius="8px" color="{{ brand.button_text_color }}" font-size="15px" font-weight="500" line-height="1.6" inner-padding="12px 20px" padding="32px 0 0" />
<mj-table padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" />
<mj-class name="heading" font-family="{{ brand.heading_font_family }}" font-size="40px" font-weight="700" line-height="1.2" letter-spacing="-0.8px" color="{{ brand.heading_color }}" css-class="heading" />
<mj-class name="greeting" padding="24px 0 0" font-size="15px" font-weight="500" color="{{ brand.heading_color }}" />
<mj-class name="lead" padding="12px 0 0" />
<mj-class name="note" padding="24px 0 0" font-size="13px" css-class="note" />
<mj-class name="section-heading" padding="48px 0 16px" font-family="{{ brand.heading_font_family }}" font-size="16px" font-weight="500" letter-spacing="-0.16px" align="left" />
<mj-class name="body" padding="16px 0 0" align="left" />
<mj-class name="footer" padding="12px 0 0" font-size="11px" line-height="1.5" />
</mj-attributes>
<mj-style>
{% if brand.font == 'inter' %}
@font-face { font-family: "Geist"; font-style: normal; font-weight: 500 700; src: url("https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2") format("woff2"); }
@font-face { font-family: "Inter"; font-style: normal; font-weight: 400 450; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuOKfMZg.ttf") format("truetype"); }
@font-face { font-family: "Inter"; font-style: normal; font-weight: 500; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf") format("truetype"); }
@font-face { font-family: "Inter"; font-style: normal; font-weight: 600; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuGKYMZg.ttf") format("truetype"); }
{% endif %}
a { color: {{ brand.link_color }}; }
.hero > table { max-width: 420px; margin: 0 auto; }
.note a { color: {{ brand.text_color }}; word-break: break-all; }
.footer a { color: {{ brand.text_color }}; }
.item { width: 100%; background-color: #F0F0F0; border-radius: 16px; margin: 0 0 8px; }
.item_image { padding: 8px; width: 96px; }
.item_thumb { display: block; width: 80px; height: auto; border-radius: 12px; }
.item_thumb_placeholder { width: 80px; height: 80px; background-color: #E4E4E4; border-radius: 12px; }
.item_info { padding: 8px 16px 8px 8px; }
.item_name { font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; text-decoration: none; }
.item_meta { margin: 2px 0 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
.item_amount { padding: 8px 16px 8px 8px; text-align: right; white-space: nowrap; }
.item_qty { margin: 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
.item_price { margin: 2px 0 0; font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; }
.summary td { padding: 6px 0; font-size: 14px; line-height: 1.6; color: {{ brand.text_color }}; }
.summary_value { font-size: 15px; font-weight: 500; text-align: right; white-space: nowrap; color: {{ brand.heading_color }}; }
.summary_sub { display: block; font-size: 13px; line-height: 1.5; }
.summary_total td { padding: 14px 0 0; border-top: 1px solid #E8E9E9; font-weight: 500; color: {{ brand.heading_color }}; }
.summary_total .summary_value { font-weight: 600; }
.mailer_hero h1 { margin: 0; font-family: {{ brand.heading_font_family }}; font-size: 40px; line-height: 1.2; letter-spacing: -0.8px; font-weight: 700; color: {{ brand.heading_color }}; }
.mailer_hero p { margin: 12px 0 0; }
.mailer_hero .greeting { margin-top: 24px; font-size: 15px; font-weight: 500; color: {{ brand.heading_color }}; }
.mailer_hero .sub { margin-top: 24px; font-size: 13px; }
@media only screen and (max-width: 600px) {
.heading div { font-size: 32px !important; letter-spacing: -0.64px !important; }
}
</mj-style>
</mj-head>
<mj-body background-color="{{ brand.background_color }}" width="640px">
<mj-wrapper background-color="{{ brand.card_color }}" padding="56px 24px">
<mj-section padding="0 0 32px">
<mj-column>
{% if store.logo_url and store.logo_width %}
<mj-image src="{{ store.logo_url }}" href="{{ store.url }}" alt="{{ store.name }}" width="{{ store.logo_width }}px" height="32px" padding="0" />
{% elsif store.logo_url %}
<mj-text><a href="{{ store.url }}"><img src="{{ store.logo_url }}" alt="{{ store.name }}" height="32" style="height: 32px; width: auto; border: 0;" /></a></mj-text>
{% else %}
<mj-text font-size="22px" font-weight="700" color="{{ brand.heading_color }}" text-transform="uppercase"><a href="{{ store.url }}" style="color: {{ brand.heading_color }}; text-decoration: none;">{{ store.name }}</a></mj-text>
{% endif %}
</mj-column>
</mj-section>
{{ content_for_layout }}
</mj-wrapper>
<mj-section padding="64px 24px">
<mj-column>
<mj-text font-size="13px" line-height="1.5" css-class="footer"><a href="{{ store.url }}" style="font-weight: 500; text-decoration: none;">{{ store.name }}</a></mj-text>
{% if store.address != blank %}<mj-text mj-class="footer">{{ store.address }}</mj-text>{% endif %}
{% if store.support_email != blank %}<mj-text mj-class="footer" css-class="footer"><a href="mailto:{{ store.support_email }}">{{ store.support_email }}</a></mj-text>{% endif %}
<mj-text mj-class="footer" padding="20px 0 0">© {{ 'now' | date: '%Y' }} {{ store.name }}</mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>
language: any
customized_languages: []
kind: layout
customized: false
published_at:
default_subject:
default_body: |
{% assign brand = store.branding %}<mjml lang="{{ locale }}">
<mj-head>
<mj-title>{{ subject }}</mj-title>
{% if brand.font_url %}<mj-font name="{{ brand.font_family | split: ',' | first }}" href="{{ brand.font_url }}" />{% endif %}
<mj-attributes>
<mj-all font-family="{{ brand.font_family }}" />
<mj-section padding="0" />
<mj-column padding="0" />
<mj-text padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" align="center" />
<mj-button background-color="{{ brand.button_color }}" border="{{ brand.button_border }}" border-radius="8px" color="{{ brand.button_text_color }}" font-size="15px" font-weight="500" line-height="1.6" inner-padding="12px 20px" padding="32px 0 0" />
<mj-table padding="0" color="{{ brand.text_color }}" font-size="14px" line-height="1.6" />
<mj-class name="heading" font-family="{{ brand.heading_font_family }}" font-size="40px" font-weight="700" line-height="1.2" letter-spacing="-0.8px" color="{{ brand.heading_color }}" css-class="heading" />
<mj-class name="greeting" padding="24px 0 0" font-size="15px" font-weight="500" color="{{ brand.heading_color }}" />
<mj-class name="lead" padding="12px 0 0" />
<mj-class name="note" padding="24px 0 0" font-size="13px" css-class="note" />
<mj-class name="section-heading" padding="48px 0 16px" font-family="{{ brand.heading_font_family }}" font-size="16px" font-weight="500" letter-spacing="-0.16px" align="left" />
<mj-class name="body" padding="16px 0 0" align="left" />
<mj-class name="footer" padding="12px 0 0" font-size="11px" line-height="1.5" />
</mj-attributes>
<mj-style>
{% if brand.font == 'inter' %}
@font-face { font-family: "Geist"; font-style: normal; font-weight: 500 700; src: url("https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2") format("woff2"); }
@font-face { font-family: "Inter"; font-style: normal; font-weight: 400 450; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuOKfMZg.ttf") format("truetype"); }
@font-face { font-family: "Inter"; font-style: normal; font-weight: 500; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf") format("truetype"); }
@font-face { font-family: "Inter"; font-style: normal; font-weight: 600; src: url("https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuGKYMZg.ttf") format("truetype"); }
{% endif %}
a { color: {{ brand.link_color }}; }
.hero > table { max-width: 420px; margin: 0 auto; }
.note a { color: {{ brand.text_color }}; word-break: break-all; }
.footer a { color: {{ brand.text_color }}; }
.item { width: 100%; background-color: #F0F0F0; border-radius: 16px; margin: 0 0 8px; }
.item_image { padding: 8px; width: 96px; }
.item_thumb { display: block; width: 80px; height: auto; border-radius: 12px; }
.item_thumb_placeholder { width: 80px; height: 80px; background-color: #E4E4E4; border-radius: 12px; }
.item_info { padding: 8px 16px 8px 8px; }
.item_name { font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; text-decoration: none; }
.item_meta { margin: 2px 0 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
.item_amount { padding: 8px 16px 8px 8px; text-align: right; white-space: nowrap; }
.item_qty { margin: 0; font-size: 13px; line-height: 1.5; color: {{ brand.text_color }}; }
.item_price { margin: 2px 0 0; font-size: 15px; line-height: 1.5; font-weight: 500; color: {{ brand.heading_color }}; }
.summary td { padding: 6px 0; font-size: 14px; line-height: 1.6; color: {{ brand.text_color }}; }
.summary_value { font-size: 15px; font-weight: 500; text-align: right; white-space: nowrap; color: {{ brand.heading_color }}; }
.summary_sub { display: block; font-size: 13px; line-height: 1.5; }
.summary_total td { padding: 14px 0 0; border-top: 1px solid #E8E9E9; font-weight: 500; color: {{ brand.heading_color }}; }
.summary_total .summary_value { font-weight: 600; }
.mailer_hero h1 { margin: 0; font-family: {{ brand.heading_font_family }}; font-size: 40px; line-height: 1.2; letter-spacing: -0.8px; font-weight: 700; color: {{ brand.heading_color }}; }
.mailer_hero p { margin: 12px 0 0; }
.mailer_hero .greeting { margin-top: 24px; font-size: 15px; font-weight: 500; color: {{ brand.heading_color }}; }
.mailer_hero .sub { margin-top: 24px; font-size: 13px; }
@media only screen and (max-width: 600px) {
.heading div { font-size: 32px !important; letter-spacing: -0.64px !important; }
}
</mj-style>
</mj-head>
<mj-body background-color="{{ brand.background_color }}" width="640px">
<mj-wrapper background-color="{{ brand.card_color }}" padding="56px 24px">
<mj-section padding="0 0 32px">
<mj-column>
{% if store.logo_url and store.logo_width %}
<mj-image src="{{ store.logo_url }}" href="{{ store.url }}" alt="{{ store.name }}" width="{{ store.logo_width }}px" height="32px" padding="0" />
{% elsif store.logo_url %}
<mj-text><a href="{{ store.url }}"><img src="{{ store.logo_url }}" alt="{{ store.name }}" height="32" style="height: 32px; width: auto; border: 0;" /></a></mj-text>
{% else %}
<mj-text font-size="22px" font-weight="700" color="{{ brand.heading_color }}" text-transform="uppercase"><a href="{{ store.url }}" style="color: {{ brand.heading_color }}; text-decoration: none;">{{ store.name }}</a></mj-text>
{% endif %}
</mj-column>
</mj-section>
{{ content_for_layout }}
</mj-wrapper>
<mj-section padding="64px 24px">
<mj-column>
<mj-text font-size="13px" line-height="1.5" css-class="footer"><a href="{{ store.url }}" style="font-weight: 500; text-decoration: none;">{{ store.name }}</a></mj-text>
{% if store.address != blank %}<mj-text mj-class="footer">{{ store.address }}</mj-text>{% endif %}
{% if store.support_email != blank %}<mj-text mj-class="footer" css-class="footer"><a href="mailto:{{ store.support_email }}">{{ store.support_email }}</a></mj-text>{% endif %}
<mj-text mj-class="footer" padding="20px 0 0">© {{ 'now' | date: '%Y' }} {{ store.name }}</mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>
published_language:
default_changed: false
base_subject:
base_body:
draft:
meta: {}
"/api/v3/admin/email_templates/{id}":
parameters:
- name: id
in: path
required: true
description: The template key with dots, e.g. `spree.order_mailer.confirm_email`
schema:
type: string
get:
summary: Get an email template
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Returns the template for one language: what customers receive now,
Spree's default, and the draft with its `lock_version`. When Spree's
default changed since the store's version started from it,
`default_changed` is true and `base_body` holds the default it
started from, to compare with `default_body`.
**Required scope:** `read_email_templates` (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 template = await client.emailTemplates.get('spree.order_mailer.confirm_email', {
language: 'de',
expand: ['draft.updated_by'],
})
- lang: bash
label: Spree CLI
source: spree api get /email_templates/{id} -d '{"language":"de","expand":["draft.updated_by"]}'
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: language
in: query
required: false
description: A language code, or `any` (the default)
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (`draft.updated_by`)
schema:
type: string
responses:
'200':
description: email template found
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Order {{ order.number }} confirmed
body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>\n"
language: any
customized_languages: []
kind: email
customized: false
published_at:
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language:
default_changed: true
base_subject: Reset {{ store.name }}
base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"
draft:
id: etdr_UkLWZg9DAJ
subject: Reset {{ store.name }}
body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>"
lock_version: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
updated_by_id: adm_UkLWZg9DAJ
updated_by_type: admin_user
schema:
"$ref": "#/components/schemas/EmailTemplate"
'404':
description: not an editable template
content:
application/json:
example:
error:
code: record_not_found
message: record not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
delete:
summary: Revert an email template to Spree's default
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Goes back to Spree's default for one language and discards the draft.
The store's published versions are kept, so one can still be restored.
**Required scope:** `write_email_templates` (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',
})
// Goes back to Spree's default. Published versions stay in the history.
const template = await client.emailTemplates.revert('spree.order_mailer.confirm_email')
- lang: bash
label: Spree CLI
source: spree api delete /email_templates/{id}
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: language
in: query
required: false
description: A language code, or `any` (the default)
schema:
type: string
- name: lock_version
in: query
required: false
description: The draft's `lock_version` as last seen; a draft saved since
is refused with 409
schema:
type: integer
responses:
'200':
description: email template reverted
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Order {{ order.number }} confirmed
body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>\n"
language: any
customized_languages: []
kind: email
customized: false
published_at:
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language:
default_changed: false
base_subject:
base_body:
draft:
schema:
"$ref": "#/components/schemas/EmailTemplate"
"/api/v3/admin/email_templates/{email_template_id}/draft":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
put:
summary: Save an email template draft
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Saves the draft, in any state; customers keep receiving the published
version until it is published. Send the `lock_version` the draft was
loaded with: a save made from an older copy is refused with 409,
naming who saved last. The first save starts from what is published,
else Spree's default.
**Required scope:** `write_email_templates` (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',
})
// Pass the lock_version the draft was loaded with: a save made from an
// older copy is refused with 409, naming who saved last.
const template = await client.emailTemplates.draft.update('spree.order_mailer.confirm_email', {
subject: 'Your order {{ order.number }} is confirmed',
body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
lock_version: 0,
})
- lang: bash
label: Spree CLI
source: spree api put /email_templates/{email_template_id}/draft -d '{"subject":"Your
order {{ order.number }} is confirmed","body":"<mj-section><mj-column><mj-text>Thanks,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>","lock_version":0}'
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
responses:
'200':
description: draft saved
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Order {{ order.number }} confirmed
body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>\n"
language: any
customized_languages: []
kind: email
customized: false
published_at:
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language:
default_changed: false
base_subject:
base_body:
draft:
id: etdr_UkLWZg9DAJ
subject: Your order {{ order.number }} is confirmed
body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>"
lock_version: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
updated_by_id: adm_UkLWZg9DAJ
updated_by_type: admin_user
schema:
"$ref": "#/components/schemas/EmailTemplate"
'409':
description: saved by someone else since it was loaded
content:
application/json:
example:
error:
code: email_template_stale
message: Mirta Hamill saved this draft after you opened it. Reload
to see their changes before saving yours.
details:
updated_by: Mirta Hamill
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/EmailTemplateDraftParams"
required: true
delete:
summary: Discard an email template draft
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: "**Required scope:** `write_email_templates` (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 template = await client.emailTemplates.draft.delete('spree.order_mailer.confirm_email')
- lang: bash
label: Spree CLI
source: spree api delete /email_templates/{email_template_id}/draft
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: language
in: query
required: false
description: A language code, or `any` (the default)
schema:
type: string
- name: lock_version
in: query
required: false
description: The draft's `lock_version` as last seen; a draft saved since
is refused with 409
schema:
type: integer
responses:
'200':
description: draft discarded
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Order {{ order.number }} confirmed
body: "<mj-section><mj-column><mj-text>Thanks for your order, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>\n"
language: any
customized_languages: []
kind: email
customized: false
published_at:
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language:
default_changed: false
base_subject:
base_body:
draft:
schema:
"$ref": "#/components/schemas/EmailTemplate"
"/api/v3/admin/email_templates/{email_template_id}/publication":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
post:
summary: Publish an email template draft
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Makes the draft what customers receive. The draft is first rendered
with sample data; one that does not render (for the layout or a
partial: in any email using it) is refused with 422, listing each
problem with its email and line.
**Required scope:** `write_email_templates` (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',
})
// Refused with 422 and each problem's email and line when the draft does not render.
const template = await client.emailTemplates.publish('spree.order_mailer.confirm_email')
- lang: bash
label: Spree CLI
source: spree api post /email_templates/{email_template_id}/publication -d
'{ ... }'
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
responses:
'201':
description: draft published
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Reset {{ store.name }}
body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>"
language: any
customized_languages:
- any
kind: email
customized: true
published_at: '2026-01-15T12:00:00Z'
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language: any
default_changed: true
base_subject: Reset {{ store.name }}
base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"
draft:
schema:
"$ref": "#/components/schemas/EmailTemplate"
'422':
description: the draft does not render
content:
application/json:
example:
error:
code: email_template_invalid
message: 'Liquid error (line 1): undefined variable nubmer'
details:
problems:
- email: spree.order_mailer.confirm_email
locale: any
message: 'Liquid error (line 1): undefined variable nubmer'
line: 1
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/EmailTemplateVersionParams"
"/api/v3/admin/email_templates/{email_template_id}/preview":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
post:
summary: Preview an email template
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Renders the template with sample data built from the store's latest
matching record, or the one `record_id` names, and returns the email
with the variables it was rendered with. An unsaved `subject` and
`body` take the place of the current version. The layout and partials
render inside an email, `email_key` or the first one. `branding`
previews colors and a font before they are saved to the store.
**Required scope:** `write_email_templates` (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 preview = await client.emailTemplates.preview('spree.order_mailer.confirm_email', {
body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
record_id: 'or_m3Rp9wXz',
})
- lang: bash
label: Spree CLI
source: spree api post /email_templates/{email_template_id}/preview -d '{"body":"<mj-section><mj-column><mj-text>Thanks,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>","record_id":"or_m3Rp9wXz"}'
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
responses:
'200':
description: email template rendered
content:
application/json:
example:
id:
subject: Order R123456789 confirmed
html: "<!doctype html><html lang=\"en\" dir=\"auto\" xmlns=\"http://www.w3.org/1999/xhtml\"
xmlns:v=\"urn:schemas-microsoft-com:vml\" xmlns:o=\"urn:schemas-microsoft-com:office:office\"><head><title>Order
R123456789 confirmed</title><!--[if !mso]><!--><meta http-equiv=\"X-UA-Compatible\"
content=\"IE=edge\"><!--<![endif]--><meta http-equiv=\"Content-Type\"
content=\"text/html; charset=UTF-8\"><meta name=\"viewport\" content=\"width=device-width,
initial-scale=1\">\n<style type=\"text/css\">\n#outlook a { padding:
0; }\nbody { margin: 0; padding: 0; -webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%; }\ntable, td { border-collapse: collapse;
mso-table-lspace: 0pt; mso-table-rspace: 0pt; }\nimg { border: 0;
height: auto; line-height: 100%; outline: none; text-decoration:
none; -ms-interpolation-mode: bicubic; }\np { display: block; margin:
13px 0; }\n</style>\n<!--[if mso]>\n<noscript>\n<xml>\n<o:OfficeDocumentSettings>\n
\ <o:AllowPNG/>\n <o:PixelsPerInch>96</o:PixelsPerInch>\n</o:OfficeDocumentSettings>\n</xml>\n</noscript>\n<![endif]-->\n<!--[if
lte mso 11]>\n<style type=\"text/css\">\n.mj-outlook-group-fix {
width:100% !important; }\n</style>\n<![endif]-->\n<style type=\"text/css\">@media
only screen and (min-width:480px) { .mj-column-per-100 { width:100%
!important; max-width:100%; } }</style><style media=\"screen and
(min-width:480px)\">.moz-text-html .mj-column-per-100 { width:100%
!important; max-width:100%; } </style><style type=\"text/css\">@font-face
{ font-family: \"Geist\"; font-style: normal; font-weight: 500 700;
src: url(\"https://fonts.gstatic.com/s/geist/v4/gyByhwUxId8gMEwcGFU.woff2\")
format(\"woff2\"); }\n @font-face { font-family: \"Inter\";
font-style: normal; font-weight: 400 450; src: url(\"https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuOKfMZg.ttf\")
format(\"truetype\"); }\n @font-face { font-family: \"Inter\";
font-style: normal; font-weight: 500; src: url(\"https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuI6fMZg.ttf\")
format(\"truetype\"); }\n @font-face { font-family: \"Inter\";
font-style: normal; font-weight: 600; src: url(\"https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuGKYMZg.ttf\")
format(\"truetype\"); }\n \n a { color: #332C2C; }\n .hero
> table { max-width: 420px; margin: 0 auto; }\n .note a { color:
#726A6A; word-break: break-all; }\n .footer a { color: #726A6A;
}\n .item { width: 100%; background-color: #F0F0F0; border-radius:
16px; margin: 0 0 8px; }\n .item_image { padding: 8px; width:
96px; }\n .item_thumb { display: block; width: 80px; height:
auto; border-radius: 12px; }\n .item_thumb_placeholder { width:
80px; height: 80px; background-color: #E4E4E4; border-radius: 12px;
}\n .item_info { padding: 8px 16px 8px 8px; }\n .item_name
{ font-size: 15px; line-height: 1.5; font-weight: 500; color: #332C2C;
text-decoration: none; }\n .item_meta { margin: 2px 0 0; font-size:
13px; line-height: 1.5; color: #726A6A; }\n .item_amount {
padding: 8px 16px 8px 8px; text-align: right; white-space: nowrap;
}\n .item_qty { margin: 0; font-size: 13px; line-height: 1.5;
color: #726A6A; }\n .item_price { margin: 2px 0 0; font-size:
15px; line-height: 1.5; font-weight: 500; color: #332C2C; }\n .summary
td { padding: 6px 0; font-size: 14px; line-height: 1.6; color: #726A6A;
}\n .summary_value { font-size: 15px; font-weight: 500; text-align:
right; white-space: nowrap; color: #332C2C; }\n .summary_sub
{ display: block; font-size: 13px; line-height: 1.5; }\n .summary_total
td { padding: 14px 0 0; border-top: 1px solid #E8E9E9; font-weight:
500; color: #332C2C; }\n .summary_total .summary_value { font-weight:
600; }\n .mailer_hero h1 { margin: 0; font-family: Geist, Inter,
Helvetica, Arial, sans-serif; font-size: 40px; line-height: 1.2;
letter-spacing: -0.8px; font-weight: 700; color: #332C2C; }\n .mailer_hero
p { margin: 12px 0 0; }\n .mailer_hero .greeting { margin-top:
24px; font-size: 15px; font-weight: 500; color: #332C2C; }\n .mailer_hero
.sub { margin-top: 24px; font-size: 13px; }\n @media only screen
and (max-width: 600px) {\n .heading div { font-size: 32px
!important; letter-spacing: -0.64px !important; }\n }</style></head><body
style=\"word-spacing:normal;background-color:#FFFFFF;\"><div lang=\"en\"
dir=\"auto\" style=\"background-color:#FFFFFF;\"><!--[if mso | IE]><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
bgcolor=\"#F6F6F6\" align=\"center\" width=\"640\" style=\"width:640px;\"><tr><td
style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
style=\"background:#F6F6F6;background-color:#F6F6F6;margin:0px auto;max-width:640px;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
align=\"center\" style=\"background:#F6F6F6;background-color:#F6F6F6;width:100%;\"><tbody><tr><td
style=\"direction:ltr;font-size:0px;padding:56px 24px;text-align:center;\"><!--[if
mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
role=\"presentation\"><tr><td width=\"640px\"><![endif]--><!--[if
mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
role=\"presentation\" align=\"center\" width=\"592\" style=\"width:592px;\"><tr><td
style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
style=\"margin:0px auto;max-width:592px;\"><table border=\"0\" cellpadding=\"0\"
cellspacing=\"0\" role=\"presentation\" align=\"center\" style=\"width:100%;\"><tbody><tr><td
style=\"direction:ltr;font-size:0px;padding:0 0 32px;text-align:center;\"><!--[if
mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
role=\"presentation\"><tr><![endif]--><!--[if mso | IE]><td style=\"vertical-align:top;width:592px;\"><![endif]--><div
class=\"mj-outlook-group-fix mj-column-per-100\" style=\"font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
width=\"100%\"><tbody><tr><td style=\"vertical-align:top;padding:0;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
width=\"100%\"><tbody><tr><td align=\"center\" style=\"font-size:0px;padding:0;word-break:break-word;\"><div
style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:22px;font-weight:700;line-height:1.6;text-align:center;text-transform:uppercase;color:#332C2C;\"><a
href=\"http://www.example.com:3000\" style=\"color: #332C2C; text-decoration:
none;\">Spree Test Store</a></div></td></tr></tbody></table></td></tr></tbody></table></div><!--[if
mso | IE]></td><![endif]--><!--[if mso | IE]></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
mso | IE]></td></tr></table><![endif]--><!--[if mso | IE]></td></tr><tr><td
width=\"640px\"><![endif]--><!--[if mso | IE]><table border=\"0\"
cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\" align=\"center\"
width=\"592\" style=\"width:592px;\"><tr><td style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
style=\"margin:0px auto;max-width:592px;\"><table border=\"0\" cellpadding=\"0\"
cellspacing=\"0\" role=\"presentation\" align=\"center\" style=\"width:100%;\"><tbody><tr><td
style=\"direction:ltr;font-size:0px;padding:0;text-align:center;\"><!--[if
mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
role=\"presentation\"><tr><![endif]--><!--[if mso | IE]><td style=\"vertical-align:top;width:592px;\"><![endif]--><div
class=\"mj-outlook-group-fix mj-column-per-100\" style=\"font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
width=\"100%\"><tbody><tr><td style=\"vertical-align:top;padding:0;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
width=\"100%\"><tbody><tr><td align=\"center\" style=\"font-size:0px;padding:0;word-break:break-word;\"><div
style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:14px;line-height:1.6;text-align:center;color:#726A6A;\">Thanks,
Ann Lee!</div></td></tr></tbody></table></td></tr></tbody></table></div><!--[if
mso | IE]></td><![endif]--><!--[if mso | IE]></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
mso | IE]></td></tr></table><![endif]--><!--[if mso | IE]></td></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
mso | IE]></td></tr></table><![endif]--><!--[if mso | IE]><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
align=\"center\" width=\"640\" style=\"width:640px;\"><tr><td style=\"line-height:0px;font-size:0px;mso-line-height-rule:exactly;\"><![endif]--><div
style=\"margin:0px auto;max-width:640px;\"><table border=\"0\" cellpadding=\"0\"
cellspacing=\"0\" role=\"presentation\" align=\"center\" style=\"width:100%;\"><tbody><tr><td
style=\"direction:ltr;font-size:0px;padding:64px 24px;text-align:center;\"><!--[if
mso | IE]><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\"
role=\"presentation\"><tr><![endif]--><!--[if mso | IE]><td style=\"vertical-align:top;width:640px;\"><![endif]--><div
class=\"mj-outlook-group-fix mj-column-per-100\" style=\"font-size:0px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
width=\"100%\"><tbody><tr><td style=\"vertical-align:top;padding:0;\"><table
border=\"0\" cellpadding=\"0\" cellspacing=\"0\" role=\"presentation\"
width=\"100%\"><tbody><tr><td align=\"center\" class=\"footer\"
style=\"font-size:0px;padding:0;word-break:break-word;\"><div style=\"font-family:Inter,
Helvetica, Arial, sans-serif;font-size:13px;line-height:1.5;text-align:center;color:#726A6A;\"><a
href=\"http://www.example.com:3000\" style=\"font-weight: 500; text-decoration:
none;\">Spree Test Store</a></div></td></tr><tr><td align=\"center\"
class=\"footer\" style=\"font-size:0px;padding:12px 0 0;word-break:break-word;\"><div
style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:11px;line-height:1.5;text-align:center;color:#726A6A;\"><a
href=\"mailto:[email protected]\">[email protected]</a></div></td></tr><tr><td
align=\"center\" style=\"font-size:0px;padding:20px 0 0;word-break:break-word;\"><div
style=\"font-family:Inter, Helvetica, Arial, sans-serif;font-size:11px;line-height:1.5;text-align:center;color:#726A6A;\">©
2026 Spree Test Store</div></td></tr></tbody></table></td></tr></tbody></table></div><!--[if
mso | IE]></td><![endif]--><!--[if mso | IE]></tr></table><![endif]--></td></tr></tbody></table></div><!--[if
mso | IE]></td></tr></table><![endif]--></div></body></html>"
text: |
Spree Test Store (http://www.example.com:3000)
Thanks, Ann Lee!
Spree Test Store (http://www.example.com:3000)
[email protected]
© 2026 Spree Test Store
email_key: spree.order_mailer.confirm_email
variables:
store:
id: store_UkLWZg9DAJ
name: Spree Test Store
address:
mail_from_address: [email protected]
default_currency: USD
default_locale: en
url: http://www.example.com:3000
support_email: [email protected]
logo_url:
logo_width:
branding:
background_color: "#FFFFFF"
card_color: "#F6F6F6"
text_color: "#726A6A"
heading_color: "#332C2C"
accent_color:
link_color: "#332C2C"
button_color: "#FFFFFF"
button_text_color: "#1F2222"
button_border: '1px solid #E8E9E9'
font: inter
font_family: Inter, Helvetica, Arial, sans-serif
heading_font_family: Geist, Inter, Helvetica, Arial, sans-serif
font_url:
locale: en
user:
first_name: Ann
email: [email protected]
order:
number: R123456789
customer_name: Ann Lee
reset_url: http://www.example.com:3000/reset-password?token=preview
schema:
"$ref": "#/components/schemas/EmailTemplatePreview"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/EmailTemplatePreviewParams"
required: true
"/api/v3/admin/email_templates/{email_template_id}/test_email":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
post:
summary: Send a test email
tags:
- Email Templates
security:
- bearer_auth: []
description: |
Sends the template, rendered as the preview renders it, to the
signed-in admin, and never to another address: the sample data comes
from a real customer's records. Takes the same body as the preview.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
jwtToken: 'eyJhbGciOi...',
})
// Sent to the signed-in admin, so this needs a client created with `jwtToken`;
// a secret key has no inbox and is refused.
const { sent_to } = await client.emailTemplates.sendTest('spree.order_mailer.confirm_email', {
body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
})
- lang: bash
label: Spree CLI
source: spree api post /email_templates/{email_template_id}/test_email -d
'{"body":"<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>"}'
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
responses:
'202':
description: test email queued
content:
application/json:
example:
sent_to: [email protected]
schema:
type: object
properties:
sent_to:
type: string
required:
- sent_to
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/EmailTemplatePreviewParams"
required: true
"/api/v3/admin/email_templates/{email_template_id}/sample_records":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
get:
summary: List records to preview an email template with
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
The store's five latest records the template can be previewed with,
newest first, to pass as `record_id` to the preview. For the layout
and partials, those of the email `email_key` names. Empty for an
email that needs no record.
**Required scope:** `write_email_templates` (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',
})
// The latest orders to preview the order confirmation with; pass one's id as `record_id`.
const { data: records } = await client.emailTemplates.sampleRecords.list(
'spree.order_mailer.confirm_email',
)
- lang: bash
label: Spree CLI
source: spree api get /email_templates/{email_template_id}/sample_records
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: email_key
in: query
required: false
description: For the layout or a partial, the email to show it in
schema:
type: string
responses:
'200':
description: records found
content:
application/json:
example:
data:
- id: or_UkLWZg9DAJ
label: R1001
created_at: '2026-01-15T12:00:00.000Z'
"/api/v3/admin/email_templates/{email_template_id}/revisions":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
get:
summary: List email template revisions
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Every version of the template published in one language, newest
first. Reverting to Spree's default keeps them.
**Required scope:** `read_email_templates` (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 revisions = await client.emailTemplates.revisions.list('spree.order_mailer.confirm_email', {
expand: ['published_by'],
})
- lang: bash
label: Spree CLI
source: spree api get /email_templates/{email_template_id}/revisions -d '{"expand":["published_by"]}'
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: language
in: query
required: false
description: A language code, or `any` (the default)
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
- name: expand
in: query
required: false
description: Comma-separated associations to expand (`published_by`)
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
**Sort by:** `created_at`, `id`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: EmailTemplateRevision
sortable:
- created_at
- id
responses:
'200':
description: revisions found
content:
application/json:
example:
data:
- id: etrv_UkLWZg9DAJ
subject: Reset {{ store.name }}
body: "<mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section>"
created_at: '2026-01-15T12:00:00.000Z'
published_by_id: adm_UkLWZg9DAJ
published_by_type: admin_user
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
"/api/v3/admin/email_templates/{email_template_id}/revisions/{revision_id}/restoration":
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
- name: revision_id
in: path
required: true
schema:
type: string
post:
summary: Restore an email template revision
tags:
- Email Templates
security:
- api_key: []
bearer_auth: []
description: |-
Copies the revision into the draft, to be published like any change.
Send the draft's `lock_version` when one is open, as when saving it.
**Required scope:** `write_email_templates` (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',
})
// Copies the revision into the draft, to publish like any change.
const template = await client.emailTemplates.revisions.restore(
'spree.order_mailer.confirm_email',
'etrv_k5nR8xLq',
)
- lang: bash
label: Spree CLI
source: spree api post /email_templates/{email_template_id}/revisions/{revision_id}/restoration
-d '{ ... }'
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
responses:
'201':
description: revision copied into the draft
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Reset {{ store.name }}
body: "<mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section>"
language: any
customized_languages:
- any
kind: email
customized: true
published_at: '2026-01-15T12:00:00Z'
default_subject: Order {{ order.number }} confirmed
default_body: "<mj-section><mj-column><mj-text>Thanks for your order,
{{ order.customer_name }}!</mj-text></mj-column></mj-section>\n"
published_language: any
default_changed: true
base_subject: Reset {{ store.name }}
base_body: "<mj-section><mj-column><mj-text>Default</mj-text></mj-column></mj-section>"
draft:
id: etdr_UkLWZg9DAJ
subject: Reset {{ store.name }}
body: "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name
}}!</mj-text></mj-column></mj-section>"
lock_version: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
updated_by_id: adm_UkLWZg9DAJ
updated_by_type: admin_user
schema:
"$ref": "#/components/schemas/EmailTemplate"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/EmailTemplateRestoreParams"
"/api/v3/admin/exports":
get:
summary: List exports
tags:
- Exports
security:
- api_key: []
bearer_auth: []
description: |-
Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).
**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
const { data: exports } = await client.exports.list()
- lang: bash
label: Spree CLI
source: spree api get /exports
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `format` | One of `csv` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `format`, `id`, `number`, `seller_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Export
sortable:
- created_at
- format
- id
- number
- seller_id
- type
- updated_at
responses:
'200':
description: exports found
content:
application/json:
example:
data:
- id: exp_UkLWZg9DAJ
number: EF1001
format: csv
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
store_id: store_UkLWZg9DAJ
seller_id:
seller_name:
filename:
byte_size:
download_url:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create an export
tags:
- Exports
security:
- api_key: []
bearer_auth: []
description: |-
Queues a CSV export. The `type` selects the dataset; `search_params` is an
optional Ransack query (same shape used by the `q[...]` params on list endpoints)
that filters which records are exported. Pass `record_selection: "all"` to
clear the filter server-side and export everything in scope.
Generation is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,
then redirect the browser to `download_url` to fetch the file.
**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
const exp = await client.exports.create({
type: 'products',
search_params: { name_cont: 'shirt' },
})
- lang: bash
label: Spree CLI
source: spree api post /exports -d '{"type":"products","search_params":{"name_cont":"shirt"}}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: export queued
content:
application/json:
example:
id: exp_gbHJdmfrXB
number: EF1002
format: csv
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
store_id: store_UkLWZg9DAJ
seller_id:
seller_name:
filename:
byte_size:
download_url:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ExportCreateParams"
required: true
"/api/v3/admin/exports/{id}":
get:
summary: Show an export
tags:
- Exports
security:
- api_key: []
bearer_auth: []
description: |-
Returns export status. While `done` is `false`, the SPA continues polling.
**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
const exp = await client.exports.get('exp_xxx')
- lang: bash
label: Spree CLI
source: spree api get /exports/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: export found
content:
application/json:
example:
id: exp_UkLWZg9DAJ
number: EF1001
format: csv
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
store_id: store_UkLWZg9DAJ
seller_id:
seller_name:
filename:
byte_size:
download_url:
delete:
summary: Delete an export
tags:
- Exports
security:
- api_key: []
bearer_auth: []
description: |-
Removes the export and purges its attachment.
**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
await client.exports.delete('exp_xxx')
- lang: bash
label: Spree CLI
source: spree api delete /exports/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: export deleted
"/api/v3/admin/exports/{id}/download":
get:
summary: Download an export
tags:
- Exports
security:
- api_key: []
bearer_auth: []
description: |-
Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.
**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: |-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
// Fetch with the Bearer token, then drive the browser download:
const res = await fetch(exp.download_url, {
headers: { Authorization: `Bearer ${token}` },
})
const blob = await res.blob()
const url = URL.createObjectURL(blob)
const a = Object.assign(document.createElement('a'), {
href: url,
download: exp.filename,
})
a.click()
URL.revokeObjectURL(url)
- lang: bash
label: Spree CLI
source: spree api get /exports/{id}/download
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: CSV file
content:
text/csv:
schema:
type: string
format: binary
"/api/v3/admin/files":
post:
summary: Upload a file
tags:
- Files
security:
- api_key: []
bearer_auth: []
description: |-
Accepts a file and returns a `signed_id` to send to the endpoint that
uses it — `signed_id` on product media, `avatar_signed_id` on a
customer, `attachment_signed_id` on an import, and so on.
Two ways to send the bytes, one response:
- **Presigned** (JSON): send the file's metadata, then `PUT` the bytes
to `upload.url` with exactly `upload.headers`. Use this for anything
large — the bytes go straight to storage.
- **Multipart**: send the bytes in a `file` part. The file is stored
before the response, so `upload` is null. Limited to 10 MB by default.
`signed_id` is opaque: pass it back unchanged and never parse it. It
stops being attachable at `expires_at`, one day after the upload.
`visibility` picks the storage: `public` (the default) for images and
videos customers see, `private` for documents, imports and digital
products. Public uploads accept web images, videos and CSV; private
uploads accept any type. `checksum` is the file's MD5 digest,
base64-encoded — the storage service verifies the bytes against it.
**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',
})
// Returns where to send the bytes: send the file to `upload.url` with
// `upload.method` and `upload.headers`, then pass `signed_id` to the
// endpoint that uses it.
// `client.files.upload(file)` does both steps for you.
const { signed_id, upload } = await client.files.create({
filename: 'products.csv',
content_type: 'text/csv',
byte_size: 48213,
checksum: 'XrY7u+Ae7tCTyyK7j1rNww==',
visibility: 'private',
})
- lang: bash
label: Spree CLI
source: spree api post /files -d '{"filename":"products.csv","content_type":"text/csv","byte_size":48213,"checksum":"XrY7u+Ae7tCTyyK7j1rNww==","visibility":"private"}'
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
responses:
'201':
description: presigned upload target created
content:
application/json:
example:
signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--aacde269a0019661ac951ab66e97e4338f76c0e3
filename: products.csv
content_type: text/csv
byte_size: 48213
visibility: private
expires_at: '2026-01-16T12:00:00.000Z'
upload:
method: PUT
url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJxcmZsMnNod3YwYmR4cWF3ZWFocDZvYjhlYzh5IiwiY29udGVudF90eXBlIjoidGV4dC9jc3YiLCJjb250ZW50X2xlbmd0aCI6NDgyMTMsImNoZWNrc3VtIjoiaGdKTXJSNkRFQjJYTloxelVRVVJWZz09Iiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI2LTAxLTE1VDEyOjA1OjAwLjAwMFoiLCJwdXIiOiJibG9iX3Rva2VuIn19--c3b32cb7c8370747da83a558fab123e28b943128
headers:
Content-Type: text/csv
schema:
"$ref": "#/components/schemas/FileUpload"
'422':
description: content type not allowed for a public upload
content:
application/json:
example:
error:
code: validation_error
message: Content type is not included in the list
details:
content_type:
- value: application/x-sh
code: inclusion
message: is not included in the list
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FileUploadCreateParams"
multipart/form-data:
schema:
"$ref": "#/components/schemas/FileUploadCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/fulfillments":
get:
summary: List fulfillments
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/fulfillments
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 ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., inventory_units,
stock_location, shipping_rates). Use dot notation for nested expand (max
4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Fulfillment
sortable:
- created_at
- id
- number
- updated_at
responses:
'200':
description: fulfillments found
content:
application/json:
example:
data:
- id: ful_UkLWZg9DAJ
number: R1001-F1
tracking: U10000
tracking_url:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_UkLWZg9DAJ
tracking_number: U10000
carrier:
carrier_name:
service:
status: pending
tracking_url:
estimated_delivery_at:
delivered_at:
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create a fulfillment
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange and claim replacements are moved only out of a named `source_fulfillment_id`, which is how a canceled replacement is sent again. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).
**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.create('or_UkLWZg9DAJ', {
stock_location_id: 'sloc_UkLWZg9DAJ',
tracking: 'INPOST-12345',
delivery_method_id: 'dm_UkLWZg9DAJ',
status: 'shipped',
items: [{ item_id: 'li_UkLWZg9DAJ', quantity: 1 }],
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'
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 ID
schema:
type: string
responses:
'201':
description: fulfillment created
content:
application/json:
example:
id: ful_gbHJdmfrXB
number: R1001-F1
tracking: INPOST-12345
tracking_url:
pickup_point_data:
selected_delivery_rate_id: dr_EfhxLZ9ck8
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: fulfilled
fulfillment_type: shipping
fulfilled_at: '2026-01-15T12:00:00.000Z'
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_gbHJdmfrXB
tracking_number: INPOST-12345
carrier:
carrier_name:
service:
status: pending
tracking_url:
estimated_delivery_at:
delivered_at:
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '0.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
'422':
description: order not completed
content:
application/json:
example:
error:
code: processing_error
message: Fulfillments can only be created manually on completed
orders
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FulfillmentCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/fulfillments/{id}":
get:
summary: Show a shipment
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/fulfillments/{id}
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Fulfillment ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., inventory_units,
stock_location, shipping_rates). Use dot notation for nested expand (max
4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).
id is always included.
schema:
type: string
responses:
'200':
description: shipment found
content:
application/json:
example:
id: ful_UkLWZg9DAJ
number: R1001-F1
tracking: U10000
tracking_url:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_UkLWZg9DAJ
tracking_number: U10000
carrier:
carrier_name:
service:
status: pending
tracking_url:
estimated_delivery_at:
delivered_at:
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
patch:
summary: Update a shipment
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
Updates a fulfillment (tracking, delivery 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',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Fulfillment ID
schema:
type: string
responses:
'200':
description: shipment updated
content:
application/json:
example:
id: ful_UkLWZg9DAJ
number: R1001-F1
tracking: 1Z999AA10123456784
tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_UkLWZg9DAJ
tracking_number: 1Z999AA10123456784
carrier: ups
carrier_name: UPS
service:
status: pending
tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
estimated_delivery_at:
delivered_at:
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FulfillmentUpdateParams"
required: true
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":
patch:
summary: Fulfill a fulfillment
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{
... }'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Fulfillment ID
schema:
type: string
responses:
'200':
description: fulfillment fulfilled
content:
application/json:
example:
id: ful_UkLWZg9DAJ
number: R1001-F1
tracking: 1Z999AA10123456784
tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: fulfilled
fulfillment_type: shipping
fulfilled_at: '2026-01-15T12:00:00.000Z'
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_UkLWZg9DAJ
tracking_number: 1Z999AA10123456784
carrier: ups
carrier_name: UPS
service:
status: pending
tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
estimated_delivery_at:
delivered_at:
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FulfillmentFulfillParams"
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":
patch:
summary: Mark a fulfillment delivered
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.
**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.markDelivered(
'or_UkLWZg9DAJ',
'ful_UkLWZg9DAJ',
{ delivered_at: '2026-08-11T09:30:00Z' },
)
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fulfillments/{id}/mark_delivered
-d '{"delivered_at":"2026-08-11T09:30:00Z"}'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Fulfillment ID
schema:
type: string
responses:
'200':
description: fulfillment delivered
content:
application/json:
example:
id: ful_UkLWZg9DAJ
number: R1001-F1
tracking: U10000
tracking_url:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: delivered
fulfillment_type: shipping
fulfilled_at: '2026-01-15T12:00:00.000Z'
delivered_at: '2026-01-15T12:00:00.000Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_UkLWZg9DAJ
tracking_number: U10000
carrier:
carrier_name:
service:
status: delivered
tracking_url:
estimated_delivery_at:
delivered_at: '2026-01-15T12:00:00.000Z'
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
'422':
description: fulfillment has not shipped
content:
application/json:
example:
error:
code: processing_error
message: Only a fulfilled shipment can be marked delivered
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FulfillmentMarkDeliveredParams"
required: true
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
patch:
summary: Cancel a fulfillment
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fulfillments/{id}/cancel -d '{
... }'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Fulfillment ID
schema:
type: string
responses:
'200':
description: fulfillment canceled
content:
application/json:
example:
id: ful_UkLWZg9DAJ
number: R1001-F1
tracking: U10000
tracking_url:
pickup_point_data:
selected_delivery_rate_id: dr_gbHJdmfrXB
unpriced: false
cost: '100.00'
total: '100.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: canceled
fulfillment_type: shipping
fulfilled_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries:
- id: dlv_UkLWZg9DAJ
tracking_number: U10000
carrier:
carrier_name:
service:
status: pending
tracking_url:
estimated_delivery_at:
delivered_at:
details:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
shipping_label_id:
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '100.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
labels: []
provider_generates_labels: false
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
patch:
summary: Split a fulfillment
tags:
- Fulfillments
security:
- api_key: []
bearer_auth: []
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',
})
// Splitting moves a quantity of one variant into its own fulfillment, so the
// response is the order's full set: the source is re-shaped, and disappears
// when the split drains it. Pass stock_location_id to send the new
// fulfillment out from a different origin.
const { data: fulfillments } = await client.orders.fulfillments.split(
'or_UkLWZg9DAJ',
'ful_UkLWZg9DAJ',
{
variant_id: 'variant_86Rf07xd4z',
quantity: 1,
},
)
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fulfillments/{id}/split -d '{"variant_id":"variant_86Rf07xd4z","quantity":1}'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Fulfillment ID
schema:
type: string
responses:
'200':
description: fulfillment split
content:
application/json:
example:
data:
- id: ful_gbHJdmfrXB
number: R1001-F1
tracking:
tracking_url:
pickup_point_data:
selected_delivery_rate_id: dr_EfhxLZ9ck8
unpriced: false
cost: '10.00'
total: '10.00'
discount_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
tax_total: '0.00'
status: unfulfilled
fulfillment_type: shipping
fulfilled_at:
delivered_at:
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
deliveries: []
external_references: {}
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
adjustment_total: '0.00'
pre_tax_amount: '0.00'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
documents: []
labels: []
provider_generates_labels: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FulfillmentSplitParams"
required: true
"/api/v3/admin/gift_cards/{gift_card_id}/custom_fields":
get:
summary: List gift card custom fields
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Returns the gift card's custom field values.
**Required scope:** `read_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',
})
const { data: customFields } = await client.customFields('gift_card', 'gc_UkLWZg9DAJ').list()
- lang: bash
label: Spree CLI
source: spree api get /gift_cards/{gift_card_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: gift_card_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomField"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/gift_card_batches":
get:
summary: List gift card batches
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Returns the gift card batches issued by the current store. Each batch
groups the cards generated together for a campaign or bulk-issuance
— the cards themselves live under `/admin/gift_cards` and reference
the batch via `gift_card_batch_id`.
**Required scope:** `read_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',
})
const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
source: spree api get /gift_card_batches -d '{"page":1,"limit":25}'
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: page
in: query
required: false
description: Page number
schema:
type: integer
- name: limit
in: query
required: false
description: Records per page
schema:
type: integer
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[prefix_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `prefix` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `prefix`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: GiftCardBatch
sortable:
- created_at
- id
- prefix
- updated_at
responses:
'200':
description: gift card batches found
content:
application/json:
example:
data:
- id: gcb_UkLWZg9DAJ
codes_count: 2
currency: USD
prefix: WELCOME
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
amount: '50.00'
expires_at:
created_by_id:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/GiftCardBatch"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a gift card batch
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Issues a batch of gift cards in a single call. The server generates
`codes_count` cards inline for small batches (configurable via
`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
a background job for larger ones. Each card's code is the batch
`prefix` followed by random hex.
**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',
})
const batch = await client.giftCardBatches.create({
prefix: 'WELCOME',
amount: '25.00',
currency: 'USD',
codes_count: 100,
expires_at: '2030-12-31',
})
- lang: bash
label: Spree CLI
source: spree api post /gift_card_batches -d '{"prefix":"WELCOME","amount":"25.00","currency":"USD","codes_count":100,"expires_at":"2030-12-31"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: gift card batch created
content:
application/json:
example:
id: gcb_gbHJdmfrXB
codes_count: 5
currency: USD
prefix: NEWCAMP
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
amount: '25.00'
expires_at: '2030-12-31'
created_by_id: adm_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/GiftCardBatch"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Prefix can't be blank
details:
prefix:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/GiftCardBatchCreateParams"
required: true
"/api/v3/admin/gift_card_batches/{id}":
parameters:
- name: id
in: path
required: true
description: Gift card batch prefixed ID
schema:
type: string
get:
summary: Get a gift card batch
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single batch.
**Required scope:** `read_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',
})
const batch = await client.giftCardBatches.get('gcb_K3zr8x')
- lang: bash
label: Spree CLI
source: spree api get /gift_card_batches/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: gift card batch found
content:
application/json:
example:
id: gcb_UkLWZg9DAJ
codes_count: 2
currency: USD
prefix: WELCOME
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
amount: '50.00'
expires_at:
created_by_id:
schema:
"$ref": "#/components/schemas/GiftCardBatch"
'404':
description: gift card batch not found
content:
application/json:
example:
error:
code: record_not_found
message: Gift card batch not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/gift_cards":
get:
summary: List gift cards
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Returns the gift cards issued by the current store. Filter by
`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued
to a specific customer, or `q[status_eq]` for status filtering.
**Required scope:** `read_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',
})
const { data: giftCards } = await client.giftCards.list({
page: 1,
limit: 25,
expand: ['customer', 'created_by'],
})
- lang: bash
label: Spree CLI
source: spree api get /gift_cards -d '{"page":1,"limit":25,"expand":["customer","created_by"]}'
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: q[search]
in: query
required: false
schema:
type: string
description: Matches any of code (partial, case-insensitive).
- name: q[active]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `active`.
- name: q[expired]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `expired`.
- name: q[partially_redeemed]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `partially_redeemed`.
- name: q[redeemed]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `redeemed`.
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `expires_at` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `gift_card_batch_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `state` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `status` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[batch_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `batch_` | `created_at`, `id`, `prefix`, `updated_at` |
| `customers_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `customers_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customers_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customers_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
| `customers_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `customers_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customers_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `customers_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `users_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `users_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `users_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `users_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
| `users_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `users_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `users_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `users_tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `code`, `created_at`, `created_by_id`, `currency`, `customer_id`, `expires_at`, `gift_card_batch_id`, `id`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: GiftCard
sortable:
- code
- created_at
- created_by_id
- currency
- customer_id
- expires_at
- gift_card_batch_id
- id
- state
- status
- updated_at
responses:
'200':
description: gift cards found
content:
application/json:
example:
data:
- id: gc_UkLWZg9DAJ
code: C5BC700C4EF16A06
status: active
currency: USD
amount: '50.00'
amount_used: '0.00'
amount_authorized: '0.00'
amount_remaining: '50.00'
expires_at:
redeemed_at:
expired: false
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
code: 3BECEA5A776AD146
status: active
currency: USD
amount: '25.00'
amount_used: '0.00'
amount_authorized: '0.00'
amount_remaining: '25.00'
expires_at:
redeemed_at:
expired: false
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id:
created_by_id:
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/GiftCard"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Issues a gift card scoped to the current store. The code is
auto-generated when omitted. `currency` defaults to the store's
configured currency. Pass `customer_id` (prefixed ID) to attach the
card to a specific customer.
**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',
})
const giftCard = await client.giftCards.create({
amount: '25.00',
currency: 'USD',
expires_at: '2030-12-31',
customer_id: 'cus_UkLWZg9DAJ',
})
- lang: bash
label: Spree CLI
source: spree api post /gift_cards -d '{"amount":"25.00","currency":"USD","expires_at":"2030-12-31","customer_id":"cus_UkLWZg9DAJ"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: gift card created
content:
application/json:
example:
id: gc_EfhxLZ9ck8
code: A68048412201A26B
status: active
currency: USD
amount: '25.00'
amount_used: '0.00'
amount_authorized: '0.00'
amount_remaining: '25.00'
expires_at: '2030-12-31'
redeemed_at:
expired: false
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id:
created_by_id: adm_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/GiftCard"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Amount must be greater than 0
details:
amount:
- value: '0.0'
count: 0
code: greater_than
message: must be greater than 0
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/GiftCardCreateParams"
required: true
"/api/v3/admin/gift_cards/{id}":
parameters:
- name: id
in: path
required: true
description: Gift card prefixed ID
schema:
type: string
get:
summary: Get a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single gift card.
**Required scope:** `read_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',
})
const giftCard = await client.giftCards.get('gc_K3zr8x', {
expand: ['customer', 'created_by', 'orders'],
})
- lang: bash
label: Spree CLI
source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
description: gift card found
content:
application/json:
example:
id: gc_UkLWZg9DAJ
code: 06BEABE5C26AA7E5
status: active
currency: USD
amount: '50.00'
amount_used: '0.00'
amount_authorized: '0.00'
amount_remaining: '50.00'
expires_at:
redeemed_at:
expired: false
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id:
created_by_id:
schema:
"$ref": "#/components/schemas/GiftCard"
'404':
description: gift card not found
content:
application/json:
example:
error:
code: record_not_found
message: Gift card not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Updates an active gift card's editable attributes. Redeemed or
partially-redeemed cards cannot be edited.
**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',
})
const giftCard = await client.giftCards.update('gc_K3zr8x', {
amount: '75.00',
})
- lang: bash
label: Spree CLI
source: spree api patch /gift_cards/{id} -d '{"amount":"75.00"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: gift card updated
content:
application/json:
example:
id: gc_UkLWZg9DAJ
code: E34E66F15D82A3CD
status: active
currency: USD
amount: '75.00'
amount_used: '0.00'
amount_authorized: '0.00'
amount_remaining: '75.00'
expires_at:
redeemed_at:
expired: false
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id:
created_by_id:
schema:
"$ref": "#/components/schemas/GiftCard"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/GiftCardUpdateParams"
required: true
delete:
summary: Delete a gift card
tags:
- Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
Deletes an unused gift card. Cards that have been redeemed or
partially redeemed cannot be deleted and return 422.
**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.giftCards.delete('gc_K3zr8x')
- lang: bash
label: Spree CLI
source: spree api delete /gift_cards/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: gift card deleted
'422':
description: redeemed gift card cannot be deleted
content:
application/json:
example:
error:
code: validation_error
message: Gift card cannot be deleted
"/api/v3/admin/imports":
get:
summary: List imports
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Returns CSV imports queued or completed for the current store.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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: imports } = await client.imports.list({
status_eq: 'failed',
sort: '-created_at',
})
- lang: bash
label: Spree CLI
source: spree api get /imports -d '{"status_eq":"failed","sort":"-created_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `status` | One of `pending`, `mapping`, `completed_mapping`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `seller_id`, `status`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Import
sortable:
- created_at
- id
- number
- seller_id
- status
- type
- updated_at
responses:
'200':
description: imports found
content:
application/json:
example:
data:
- id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
status: pending
store_id: store_UkLWZg9DAJ
seller_id:
user_id: adm_UkLWZg9DAJ
processing_errors:
delimiter: ","
price_list_id:
seller_name:
original_filename: products_import.csv
original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_UkLWZg9DAJ/download"
completed_rows_count: 0
failed_rows_count: 0
schema_fields:
- name: slug
label: Slug
required: true
- name: sku
label: SKU
required: true
- name: name
label: Name
required: true
- name: price
label: Price
required: true
- name: status
label: Status
required: false
- name: description
label: Description
required: false
- name: meta_title
label: Meta Title
required: false
- name: meta_description
label: Meta Description
required: false
- name: meta_keywords
label: Meta Keywords
required: false
- name: tags
label: Tags
required: false
- name: compare_at_price
label: Compare at Price
required: false
- name: currency
label: Currency
required: false
- name: width
label: Width
required: false
- name: height
label: Height
required: false
- name: depth
label: Depth
required: false
- name: dimensions_unit
label: Dimensions Unit
required: false
- name: weight
label: Weight
required: false
- name: weight_unit
label: Weight Unit
required: false
- name: available_on
label: Available On
required: false
- name: discontinue_on
label: Discontinue On
required: false
- name: track_inventory
label: Track Inventory
required: false
- name: inventory_count
label: Inventory Count
required: false
- name: inventory_backorderable
label: Inventory Backorderable
required: false
- name: stock_location
label: Stock Location
required: false
- name: tax_category
label: Tax Category
required: false
- name: product_type
label: Product Type
required: false
- name: hs_code
label: HS Code
required: false
- name: country_of_origin
label: Country of Origin
required: false
- name: customs_description
label: Customs Description
required: false
- name: carton
label: Carton
required: false
- name: units_per_carton
label: Units per Carton
required: false
- name: carton_weight
label: Carton Weight
required: false
- name: cartons_per_pallet
label: Cartons per Pallet
required: false
- name: image1_src
label: Image 1 URL
required: false
- name: image2_src
label: Image 2 URL
required: false
- name: image3_src
label: Image 3 URL
required: false
- name: option1_name
label: Option 1 Name
required: false
- name: option1_value
label: Option 1 Value
required: false
- name: option2_name
label: Option 2 Name
required: false
- name: option2_value
label: Option 2 Value
required: false
- name: option3_name
label: Option 3 Name
required: false
- name: option3_value
label: Option 3 Value
required: false
- name: category1
label: Category 1
required: false
- name: category2
label: Category 2
required: false
- name: category3
label: Category 3
required: false
csv_headers: []
sample_row: {}
mappings: []
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create an import
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Queues a CSV import. Upload the file first via `POST /api/v3/admin/files`
and pass the returned `signed_id` as `attachment_signed_id`. On success the import is in the
`mapping` state and the response carries the mapping payload: `schema_fields`
(the canonical columns for the type), `csv_headers`, a `sample_row`, and the
auto-assigned `mappings`.
Adjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`
to start processing. Poll `GET /admin/imports/{id}` while `status` is
`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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',
})
// Upload the CSV with `client.files.upload(file, { visibility: 'private' })`
// first and pass its `signed_id`. The import then waits in `mapping`, with the
// columns assigned automatically.
const productImport = await client.imports.create({
type: 'products',
attachment_signed_id: 'eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3',
})
- lang: bash
label: Spree CLI
source: spree api post /imports -d '{"type":"products","attachment_signed_id":"eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--a1b2c3"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: import created in mapping state
content:
application/json:
example:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
status: mapping
store_id: store_UkLWZg9DAJ
seller_id:
user_id: adm_UkLWZg9DAJ
processing_errors:
delimiter: ","
price_list_id:
seller_name:
original_filename: import.csv
original_byte_size: 44
original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
completed_rows_count: 0
failed_rows_count: 0
schema_fields:
- name: slug
label: Slug
required: true
- name: sku
label: SKU
required: true
- name: name
label: Name
required: true
- name: price
label: Price
required: true
- name: status
label: Status
required: false
- name: description
label: Description
required: false
- name: meta_title
label: Meta Title
required: false
- name: meta_description
label: Meta Description
required: false
- name: meta_keywords
label: Meta Keywords
required: false
- name: tags
label: Tags
required: false
- name: compare_at_price
label: Compare at Price
required: false
- name: currency
label: Currency
required: false
- name: width
label: Width
required: false
- name: height
label: Height
required: false
- name: depth
label: Depth
required: false
- name: dimensions_unit
label: Dimensions Unit
required: false
- name: weight
label: Weight
required: false
- name: weight_unit
label: Weight Unit
required: false
- name: available_on
label: Available On
required: false
- name: discontinue_on
label: Discontinue On
required: false
- name: track_inventory
label: Track Inventory
required: false
- name: inventory_count
label: Inventory Count
required: false
- name: inventory_backorderable
label: Inventory Backorderable
required: false
- name: stock_location
label: Stock Location
required: false
- name: tax_category
label: Tax Category
required: false
- name: product_type
label: Product Type
required: false
- name: hs_code
label: HS Code
required: false
- name: country_of_origin
label: Country of Origin
required: false
- name: customs_description
label: Customs Description
required: false
- name: carton
label: Carton
required: false
- name: units_per_carton
label: Units per Carton
required: false
- name: carton_weight
label: Carton Weight
required: false
- name: cartons_per_pallet
label: Cartons per Pallet
required: false
- name: image1_src
label: Image 1 URL
required: false
- name: image2_src
label: Image 2 URL
required: false
- name: image3_src
label: Image 3 URL
required: false
- name: option1_name
label: Option 1 Name
required: false
- name: option1_value
label: Option 1 Value
required: false
- name: option2_name
label: Option 2 Name
required: false
- name: option2_value
label: Option 2 Value
required: false
- name: option3_name
label: Option 3 Name
required: false
- name: option3_value
label: Option 3 Value
required: false
- name: category1
label: Category 1
required: false
- name: category2
label: Category 2
required: false
- name: category3
label: Category 3
required: false
csv_headers:
- slug
- sku
- name
- price
sample_row:
slug: widget
sku: W-1
name: Widget
price: '10.00'
mappings:
- id: immap_UkLWZg9DAJ
schema_field: slug
file_column: slug
required: true
- id: immap_gbHJdmfrXB
schema_field: sku
file_column: sku
required: true
- id: immap_EfhxLZ9ck8
schema_field: name
file_column: name
required: true
- id: immap_VqXmZF31wY
schema_field: price
file_column: price
required: true
- id: immap_uw2YK1rnl0
schema_field: status
file_column:
required: false
- id: immap_OIJLhNcSbf
schema_field: description
file_column:
required: false
- id: immap_AXs1igzRC6
schema_field: meta_title
file_column:
required: false
- id: immap_p6klVeMgbn
schema_field: meta_description
file_column:
required: false
- id: immap_nJqfPa3Cpe
schema_field: meta_keywords
file_column:
required: false
- id: immap_98FqgRua4h
schema_field: tags
file_column:
required: false
- id: immap_xhoCpeNMWu
schema_field: compare_at_price
file_column:
required: false
- id: immap_vEmzDoNU0H
schema_field: currency
file_column:
required: false
- id: immap_2KY5XM6frI
schema_field: width
file_column:
required: false
- id: immap_HOVtlDrOmL
schema_field: height
file_column:
required: false
- id: immap_ed6l8wVqSM
schema_field: depth
file_column:
required: false
- id: immap_s18jaGonyx
schema_field: dimensions_unit
file_column:
required: false
- id: immap_GZUcnUYI5A
schema_field: weight
file_column:
required: false
- id: immap_ROeNhrwyV9
schema_field: weight_unit
file_column:
required: false
- id: immap_L3pHOn63Vw
schema_field: available_on
file_column:
required: false
- id: immap_PQNMcnNFWw
schema_field: discontinue_on
file_column:
required: false
- id: immap_C9SrJgpzQ4
schema_field: track_inventory
file_column:
required: false
- id: immap_YHETxCGlb0
schema_field: inventory_count
file_column:
required: false
- id: immap_5OQZnCRf8J
schema_field: inventory_backorderable
file_column:
required: false
- id: immap_F0GX8NaP3Y
schema_field: stock_location
file_column:
required: false
- id: immap_kOKT9MVfb0
schema_field: tax_category
file_column:
required: false
- id: immap_3uWpPTcf5W
schema_field: product_type
file_column:
required: false
- id: immap_D6Psx31WaT
schema_field: hs_code
file_column:
required: false
- id: immap_msx3nOJap6
schema_field: country_of_origin
file_column:
required: false
- id: immap_5CQZnCRf8J
schema_field: customs_description
file_column:
required: false
- id: immap_M2nyloHRUQ
schema_field: carton
file_column:
required: false
- id: immap_prklVeMgbn
schema_field: units_per_carton
file_column:
required: false
- id: immap_so8jaGonyx
schema_field: carton_weight
file_column:
required: false
- id: immap_rsClYtECFI
schema_field: cartons_per_pallet
file_column:
required: false
- id: immap_8DR0I7fEbw
schema_field: image1_src
file_column:
required: false
- id: immap_aAtNvLSUAr
schema_field: image2_src
file_column:
required: false
- id: immap_QiA48cIW7A
schema_field: image3_src
file_column:
required: false
- id: immap_QDA48cIW7A
schema_field: option1_name
file_column:
required: false
- id: immap_8cR0I7fEbw
schema_field: option1_value
file_column:
required: false
- id: immap_oqlrKdXjaP
schema_field: option2_name
file_column:
required: false
- id: immap_48Olu6p4zZ
schema_field: option2_value
file_column:
required: false
- id: immap_qp31JYFduR
schema_field: option3_name
file_column:
required: false
- id: immap_JgaEBgznCp
schema_field: option3_value
file_column:
required: false
- id: immap_tXyJwvFCuK
schema_field: category1
file_column:
required: false
- id: immap_NJzXvxTk8u
schema_field: category2
file_column:
required: false
- id: immap_XLbb5HTmVa
schema_field: category3
file_column:
required: false
'422':
description: unknown import type
content:
application/json:
example:
error:
code: validation_error
message: Type can't be blank
details:
type:
- code: blank
message: can't be blank
specific: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ImportCreateParams"
required: true
"/api/v3/admin/imports/template":
get:
summary: Download an import template
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Returns a CSV header row for the given import type, including the custom field columns available for the model.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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',
})
// The template is a CSV, so fetch it directly with the API key:
const response = await fetch('https://your-store.com/api/v3/admin/imports/template?type=products', {
headers: { 'X-Spree-API-Key': 'sk_xxx' },
})
if (!response.ok) throw new Error(`Download failed with status ${response.status}`)
const csvHeader = await response.text()
- lang: bash
label: Spree CLI
source: spree api get /imports/template
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: type
in: query
required: true
description: Registered import type, e.g. products.
schema:
type: string
responses:
'200':
description: CSV template
content:
text/csv:
schema:
type: string
format: binary
"/api/v3/admin/imports/example":
get:
summary: Download an example import file
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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',
})
// Redirects to a populated example CSV; fetch follows the redirect.
const response = await fetch('https://your-store.com/api/v3/admin/imports/example?type=products', {
headers: { 'X-Spree-API-Key': 'sk_xxx' },
})
if (!response.ok) throw new Error(`Download failed with status ${response.status}`)
const exampleCsv = await response.text()
- lang: bash
label: Spree CLI
source: spree api get /imports/example
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: type
in: query
required: true
description: Registered import type, e.g. products.
schema:
type: string
responses:
'302':
description: Redirect to the example CSV
"/api/v3/admin/imports/{id}":
get:
summary: Show an import
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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 productImport = await client.imports.get('imp_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /imports/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: import found
content:
application/json:
example:
id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
status: pending
store_id: store_UkLWZg9DAJ
seller_id:
user_id: adm_UkLWZg9DAJ
processing_errors:
delimiter: ","
price_list_id:
seller_name:
original_filename: products_import.csv
original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_UkLWZg9DAJ/download"
completed_rows_count: 0
failed_rows_count: 0
schema_fields:
- name: slug
label: Slug
required: true
- name: sku
label: SKU
required: true
- name: name
label: Name
required: true
- name: price
label: Price
required: true
- name: status
label: Status
required: false
- name: description
label: Description
required: false
- name: meta_title
label: Meta Title
required: false
- name: meta_description
label: Meta Description
required: false
- name: meta_keywords
label: Meta Keywords
required: false
- name: tags
label: Tags
required: false
- name: compare_at_price
label: Compare at Price
required: false
- name: currency
label: Currency
required: false
- name: width
label: Width
required: false
- name: height
label: Height
required: false
- name: depth
label: Depth
required: false
- name: dimensions_unit
label: Dimensions Unit
required: false
- name: weight
label: Weight
required: false
- name: weight_unit
label: Weight Unit
required: false
- name: available_on
label: Available On
required: false
- name: discontinue_on
label: Discontinue On
required: false
- name: track_inventory
label: Track Inventory
required: false
- name: inventory_count
label: Inventory Count
required: false
- name: inventory_backorderable
label: Inventory Backorderable
required: false
- name: stock_location
label: Stock Location
required: false
- name: tax_category
label: Tax Category
required: false
- name: product_type
label: Product Type
required: false
- name: hs_code
label: HS Code
required: false
- name: country_of_origin
label: Country of Origin
required: false
- name: customs_description
label: Customs Description
required: false
- name: carton
label: Carton
required: false
- name: units_per_carton
label: Units per Carton
required: false
- name: carton_weight
label: Carton Weight
required: false
- name: cartons_per_pallet
label: Cartons per Pallet
required: false
- name: image1_src
label: Image 1 URL
required: false
- name: image2_src
label: Image 2 URL
required: false
- name: image3_src
label: Image 3 URL
required: false
- name: option1_name
label: Option 1 Name
required: false
- name: option1_value
label: Option 1 Value
required: false
- name: option2_name
label: Option 2 Name
required: false
- name: option2_value
label: Option 2 Value
required: false
- name: option3_name
label: Option 3 Name
required: false
- name: option3_value
label: Option 3 Value
required: false
- name: category1
label: Category 1
required: false
- name: category2
label: Category 2
required: false
- name: category3
label: Category 3
required: false
csv_headers: []
sample_row: {}
mappings: []
delete:
summary: Delete an import
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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.imports.delete('imp_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /imports/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: import deleted
"/api/v3/admin/imports/{id}/download":
get:
summary: Download the originally uploaded file
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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 productImport = await client.imports.get('imp_UkLWZg9DAJ')
if (productImport.original_file_url) {
// The uploaded file is served through the API, so fetch it with the API key:
const response = await fetch(`https://your-store.com${productImport.original_file_url}`, {
headers: { 'X-Spree-API-Key': 'sk_xxx' },
})
if (!response.ok) throw new Error(`Download failed with status ${response.status}`)
const csv = await response.text()
console.log(csv)
}
- lang: bash
label: Spree CLI
source: spree api get /imports/{id}/download
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: CSV file
content:
text/csv:
schema:
type: string
format: binary
"/api/v3/admin/imports/{id}/complete_mapping":
patch:
summary: Complete mapping and start processing
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Applies the submitted column mappings, then starts row processing. Omit `mappings`
to accept the auto-assigned ones from the create response. Returns 422 when a
required schema field is left unmapped (`details.missing_required_fields`) or a
file column is assigned twice.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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',
})
// Omit `mappings` to accept the columns assigned on create.
const productImport = await client.imports.completeMapping('imp_UkLWZg9DAJ', {
mappings: [
{ schema_field: 'slug', file_column: 'handle' },
{ schema_field: 'price', file_column: 'price_usd' },
],
})
- lang: bash
label: Spree CLI
source: spree api patch /imports/{id}/complete_mapping -d '{"mappings":[{"schema_field":"slug","file_column":"handle"},{"schema_field":"price","file_column":"price_usd"}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: mapping completed, processing queued
content:
application/json:
example:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
status: completed_mapping
store_id: store_UkLWZg9DAJ
seller_id:
user_id: adm_UkLWZg9DAJ
processing_errors:
delimiter: ","
price_list_id:
seller_name:
original_filename: products_import.csv
original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
completed_rows_count: 0
failed_rows_count: 0
schema_fields:
- name: slug
label: Slug
required: true
- name: sku
label: SKU
required: true
- name: name
label: Name
required: true
- name: price
label: Price
required: true
- name: status
label: Status
required: false
- name: description
label: Description
required: false
- name: meta_title
label: Meta Title
required: false
- name: meta_description
label: Meta Description
required: false
- name: meta_keywords
label: Meta Keywords
required: false
- name: tags
label: Tags
required: false
- name: compare_at_price
label: Compare at Price
required: false
- name: currency
label: Currency
required: false
- name: width
label: Width
required: false
- name: height
label: Height
required: false
- name: depth
label: Depth
required: false
- name: dimensions_unit
label: Dimensions Unit
required: false
- name: weight
label: Weight
required: false
- name: weight_unit
label: Weight Unit
required: false
- name: available_on
label: Available On
required: false
- name: discontinue_on
label: Discontinue On
required: false
- name: track_inventory
label: Track Inventory
required: false
- name: inventory_count
label: Inventory Count
required: false
- name: inventory_backorderable
label: Inventory Backorderable
required: false
- name: stock_location
label: Stock Location
required: false
- name: tax_category
label: Tax Category
required: false
- name: product_type
label: Product Type
required: false
- name: hs_code
label: HS Code
required: false
- name: country_of_origin
label: Country of Origin
required: false
- name: customs_description
label: Customs Description
required: false
- name: carton
label: Carton
required: false
- name: units_per_carton
label: Units per Carton
required: false
- name: carton_weight
label: Carton Weight
required: false
- name: cartons_per_pallet
label: Cartons per Pallet
required: false
- name: image1_src
label: Image 1 URL
required: false
- name: image2_src
label: Image 2 URL
required: false
- name: image3_src
label: Image 3 URL
required: false
- name: option1_name
label: Option 1 Name
required: false
- name: option1_value
label: Option 1 Value
required: false
- name: option2_name
label: Option 2 Name
required: false
- name: option2_value
label: Option 2 Value
required: false
- name: option3_name
label: Option 3 Name
required: false
- name: option3_value
label: Option 3 Value
required: false
- name: category1
label: Category 1
required: false
- name: category2
label: Category 2
required: false
- name: category3
label: Category 3
required: false
csv_headers: []
sample_row: {}
mappings:
- id: immap_UkLWZg9DAJ
schema_field: slug
file_column: slug
required: true
- id: immap_gbHJdmfrXB
schema_field: sku
file_column: sku
required: true
- id: immap_EfhxLZ9ck8
schema_field: name
file_column: name
required: true
- id: immap_VqXmZF31wY
schema_field: price
file_column: price
required: true
- id: immap_uw2YK1rnl0
schema_field: status
file_column: status
required: false
- id: immap_OIJLhNcSbf
schema_field: description
file_column: description
required: false
- id: immap_AXs1igzRC6
schema_field: meta_title
file_column: meta_title
required: false
- id: immap_p6klVeMgbn
schema_field: meta_description
file_column: meta_description
required: false
- id: immap_nJqfPa3Cpe
schema_field: meta_keywords
file_column: meta_keywords
required: false
- id: immap_98FqgRua4h
schema_field: tags
file_column: tags
required: false
- id: immap_xhoCpeNMWu
schema_field: compare_at_price
file_column: compare_at_price
required: false
- id: immap_vEmzDoNU0H
schema_field: currency
file_column: currency
required: false
- id: immap_2KY5XM6frI
schema_field: width
file_column: width
required: false
- id: immap_HOVtlDrOmL
schema_field: height
file_column: height
required: false
- id: immap_ed6l8wVqSM
schema_field: depth
file_column: depth
required: false
- id: immap_s18jaGonyx
schema_field: dimensions_unit
file_column: dimensions_unit
required: false
- id: immap_GZUcnUYI5A
schema_field: weight
file_column: weight
required: false
- id: immap_ROeNhrwyV9
schema_field: weight_unit
file_column: weight_unit
required: false
- id: immap_L3pHOn63Vw
schema_field: available_on
file_column: available_on
required: false
- id: immap_PQNMcnNFWw
schema_field: discontinue_on
file_column: discontinue_on
required: false
- id: immap_C9SrJgpzQ4
schema_field: track_inventory
file_column: track_inventory
required: false
- id: immap_YHETxCGlb0
schema_field: inventory_count
file_column: inventory_count
required: false
- id: immap_5OQZnCRf8J
schema_field: inventory_backorderable
file_column: inventory_backorderable
required: false
- id: immap_F0GX8NaP3Y
schema_field: stock_location
file_column:
required: false
- id: immap_kOKT9MVfb0
schema_field: tax_category
file_column: tax_category
required: false
- id: immap_3uWpPTcf5W
schema_field: product_type
file_column:
required: false
- id: immap_D6Psx31WaT
schema_field: hs_code
file_column:
required: false
- id: immap_msx3nOJap6
schema_field: country_of_origin
file_column:
required: false
- id: immap_5CQZnCRf8J
schema_field: customs_description
file_column:
required: false
- id: immap_M2nyloHRUQ
schema_field: carton
file_column:
required: false
- id: immap_prklVeMgbn
schema_field: units_per_carton
file_column:
required: false
- id: immap_so8jaGonyx
schema_field: carton_weight
file_column:
required: false
- id: immap_rsClYtECFI
schema_field: cartons_per_pallet
file_column:
required: false
- id: immap_8DR0I7fEbw
schema_field: image1_src
file_column: image1_src
required: false
- id: immap_aAtNvLSUAr
schema_field: image2_src
file_column: image2_src
required: false
- id: immap_QiA48cIW7A
schema_field: image3_src
file_column: image3_src
required: false
- id: immap_QDA48cIW7A
schema_field: option1_name
file_column: option1_name
required: false
- id: immap_8cR0I7fEbw
schema_field: option1_value
file_column: option1_value
required: false
- id: immap_oqlrKdXjaP
schema_field: option2_name
file_column: option2_name
required: false
- id: immap_48Olu6p4zZ
schema_field: option2_value
file_column: option2_value
required: false
- id: immap_qp31JYFduR
schema_field: option3_name
file_column: option3_name
required: false
- id: immap_JgaEBgznCp
schema_field: option3_value
file_column: option3_value
required: false
- id: immap_tXyJwvFCuK
schema_field: category1
file_column: category1
required: false
- id: immap_NJzXvxTk8u
schema_field: category2
file_column: category2
required: false
- id: immap_XLbb5HTmVa
schema_field: category3
file_column: category3
required: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ImportCompleteMappingParams"
"/api/v3/admin/imports/{id}/retry_failed_rows":
patch:
summary: Retry failed rows
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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 productImport = await client.imports.retryFailedRows('imp_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /imports/{id}/retry_failed_rows -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: retry queued
content:
application/json:
example:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
type: products
status: processing
store_id: store_UkLWZg9DAJ
seller_id:
user_id: adm_UkLWZg9DAJ
processing_errors:
delimiter: ","
price_list_id:
seller_name:
original_filename: products_import.csv
original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
completed_rows_count: 0
failed_rows_count: 1
schema_fields:
- name: slug
label: Slug
required: true
- name: sku
label: SKU
required: true
- name: name
label: Name
required: true
- name: price
label: Price
required: true
- name: status
label: Status
required: false
- name: description
label: Description
required: false
- name: meta_title
label: Meta Title
required: false
- name: meta_description
label: Meta Description
required: false
- name: meta_keywords
label: Meta Keywords
required: false
- name: tags
label: Tags
required: false
- name: compare_at_price
label: Compare at Price
required: false
- name: currency
label: Currency
required: false
- name: width
label: Width
required: false
- name: height
label: Height
required: false
- name: depth
label: Depth
required: false
- name: dimensions_unit
label: Dimensions Unit
required: false
- name: weight
label: Weight
required: false
- name: weight_unit
label: Weight Unit
required: false
- name: available_on
label: Available On
required: false
- name: discontinue_on
label: Discontinue On
required: false
- name: track_inventory
label: Track Inventory
required: false
- name: inventory_count
label: Inventory Count
required: false
- name: inventory_backorderable
label: Inventory Backorderable
required: false
- name: stock_location
label: Stock Location
required: false
- name: tax_category
label: Tax Category
required: false
- name: product_type
label: Product Type
required: false
- name: hs_code
label: HS Code
required: false
- name: country_of_origin
label: Country of Origin
required: false
- name: customs_description
label: Customs Description
required: false
- name: carton
label: Carton
required: false
- name: units_per_carton
label: Units per Carton
required: false
- name: carton_weight
label: Carton Weight
required: false
- name: cartons_per_pallet
label: Cartons per Pallet
required: false
- name: image1_src
label: Image 1 URL
required: false
- name: image2_src
label: Image 2 URL
required: false
- name: image3_src
label: Image 3 URL
required: false
- name: option1_name
label: Option 1 Name
required: false
- name: option1_value
label: Option 1 Value
required: false
- name: option2_name
label: Option 2 Name
required: false
- name: option2_value
label: Option 2 Value
required: false
- name: option3_name
label: Option 3 Name
required: false
- name: option3_value
label: Option 3 Value
required: false
- name: category1
label: Category 1
required: false
- name: category2
label: Category 2
required: false
- name: category3
label: Category 3
required: false
csv_headers: []
sample_row: {}
mappings: []
"/api/v3/admin/imports/{import_id}/rows":
get:
summary: List import rows
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.
**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (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: failedRows } = await client.imports.rows.list('imp_UkLWZg9DAJ', {
status_eq: 'failed',
})
- lang: bash
label: Spree CLI
source: spree api get /imports/{import_id}/rows -d '{"status_eq":"failed"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: import_id
in: path
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `row_number` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `row_number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: ImportRow
sortable:
- created_at
- id
- row_number
- status
- updated_at
responses:
'200':
description: rows found
content:
application/json:
example:
data:
- id: imrow_gbHJdmfrXB
row_number: 2
status: failed
validation_errors: boom
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
import_id: imp_UkLWZg9DAJ
item_type:
item_id:
data:
slug: test-product
name: Test Product
price: '10.00'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
"/api/v3/admin/maintenance_task_runs":
get:
summary: List maintenance task runs
tags:
- Maintenance Tasks
security:
- api_key: []
bearer_auth: []
description: |-
The record of every maintenance task run: who started it, with which
arguments, how far it got and how it ended.
Runs are installation-wide rather than per store — an upgrade step
converts every store's data — so this list is not filtered by the
store the request is made against.
**Required scope:** `read_maintenance_tasks` (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: runs } = await client.maintenanceTaskRuns.list({ status_eq: 'succeeded' })
- lang: bash
label: Spree CLI
source: spree api get /maintenance_task_runs -d '{"status_eq":"succeeded"}'
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: 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
- name: q[task_name_cont]
in: query
required: false
description: Filter by task name (contains), e.g. `capture`
schema:
type: string
- name: q[status_eq]
in: query
required: false
description: Filter by status (enqueued, running, succeeded, errored, cancelled,
…)
schema:
type: string
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
responses:
'200':
description: maintenance task runs found
content:
application/json:
example:
data:
- id: mtr_UkLWZg9DAJ
status: succeeded
dry_run: false
initiated_via: dashboard
tick_count: 0
tick_total:
error_class:
error_message:
started_at:
ended_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
task_name: capture_methods
duration: 0.0
tallies: {}
arguments: {}
error_backtrace:
active: false
admin_user_id:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/MaintenanceTaskRun"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Start a maintenance task
tags:
- Maintenance Tasks
security:
- api_key: []
bearer_auth: []
description: |-
Starts a run of a registered maintenance task and returns it. The run
is enqueued, so poll it while `active` is true.
`arguments` are validated by the task's own Active Model validations,
so a bad value is rejected here rather than failing on the first
record. `dry_run` is honored only by tasks whose `supports_dry_run` is
true — recording a run as a preview that would in fact have written
would misrepresent what happened.
Only one run of a task can be in flight at a time: two would race over
the same records and their cursors would leapfrog.
**Required scope:** `write_maintenance_tasks` (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 run = await client.maintenanceTaskRuns.create({
task_name: 'capture_methods',
dry_run: true,
})
- lang: bash
label: Spree CLI
source: spree api post /maintenance_task_runs -d '{"task_name":"capture_methods","dry_run":true}'
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
responses:
'201':
description: maintenance task started
content:
application/json:
example:
id: mtr_UkLWZg9DAJ
status: enqueued
dry_run: true
initiated_via: dashboard
tick_count: 0
tick_total:
error_class:
error_message:
started_at:
ended_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
task_name: capture_methods
duration: 0.0
tallies: {}
arguments: {}
error_backtrace:
active: true
admin_user_id: adm_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/MaintenanceTaskRun"
'422':
description: task is not registered
content:
application/json:
example:
error:
code: validation_error
message: Task name nope is not a registered maintenance task
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/MaintenanceTaskRunCreateParams"
required: true
"/api/v3/admin/maintenance_task_runs/{id}":
parameters:
- name: id
in: path
description: Maintenance task run ID
required: true
schema:
type: string
get:
summary: Retrieve a maintenance task run
tags:
- Maintenance Tasks
security:
- api_key: []
bearer_auth: []
description: |-
A single run, with the progress a dashboard polls while it works.
`progress` is `0..1` when the task could count its collection and
`null` when it could not, in which case `tick_count` alone reports what
has been processed. `arguments` are rendered through the task's masking
rules, so a secret passed as a parameter is stored for reproducibility
but never echoed back.
**Required scope:** `read_maintenance_tasks` (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 run = await client.maintenanceTaskRuns.get('mtr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /maintenance_task_runs/{id}
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
responses:
'200':
description: maintenance task run found
content:
application/json:
example:
id: mtr_UkLWZg9DAJ
status: running
dry_run: false
initiated_via: api
tick_count: 5
tick_total: 20
error_class:
error_message:
started_at:
ended_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
task_name: capture_methods
duration: 0.0
tallies: {}
arguments: {}
error_backtrace:
active: true
admin_user_id:
schema:
"$ref": "#/components/schemas/MaintenanceTaskRun"
'404':
description: maintenance task run not found
content:
application/json:
example:
error:
code: record_not_found
message: Maintenance task run not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/maintenance_task_runs/{maintenance_task_run_id}/cancellation":
parameters:
- name: maintenance_task_run_id
in: path
description: Maintenance task run ID
required: true
schema:
type: string
post:
summary: Cancel a maintenance task run
tags:
- Maintenance Tasks
security:
- api_key: []
bearer_auth: []
description: |-
Asks the runner to stop for good at its next checkpoint.
Cancelling is not a rollback — work already committed stays committed.
What a cancelled run keeps is its cursor, so an operator can see how
far it got. A run that is still `cancelling` because its worker has
gone is cancelled outright by a second request.
**Required scope:** `write_maintenance_tasks` (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 run = await client.maintenanceTaskRuns.cancel('mtr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api post /maintenance_task_runs/{maintenance_task_run_id}/cancellation
-d '{ ... }'
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
responses:
'200':
description: maintenance task run cancelling
content:
application/json:
example:
id: mtr_UkLWZg9DAJ
status: cancelling
dry_run: false
initiated_via: api
tick_count: 0
tick_total:
error_class:
error_message:
started_at:
ended_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
task_name: capture_methods
duration: 0.0
tallies: {}
arguments: {}
error_backtrace:
active: true
admin_user_id:
schema:
"$ref": "#/components/schemas/MaintenanceTaskRun"
'422':
description: maintenance task run cannot be cancelled
content:
application/json:
example:
error:
code: validation_error
message: a run with status succeeded cannot be cancelled
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/markets":
get:
summary: List markets
tags:
- Markets
security:
- api_key: []
bearer_auth: []
description: |-
Returns the markets configured for the current store. Markets are
store-scoped and ordered by `position` (an `acts_as_list` column —
update the order via `PATCH /markets/{id}` with `position`).
**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: markets } = await client.markets.list()
- lang: bash
label: Spree CLI
source: spree api get /markets
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name (partial, case-insensitive).
- name: page
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
schema:
type: string
- name: expand
in: query
required: false
description: 'Comma-separated associations to embed. Supported: `countries`.'
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `default_locale` | One of the `LocaleCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `currency`, `default_locale`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Market
sortable:
- created_at
- currency
- default_locale
- id
- name
- position
- updated_at
responses:
'200':
description: markets found
content:
application/json:
example:
data:
- id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
- id: mkt_gbHJdmfrXB
name: EU
currency: USD
default_locale: en
tax_inclusive: false
default: false
country_codes:
- DE
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Market"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a market
tags:
- Markets
security:
- api_key: []
bearer_auth: []
description: |-
Creates a new market for the current store.
- `country_codes` accepts 2-letter ISO country codes (e.g. `["DE", "FR"]`);
the market must contain at least one country. Unknown codes are
silently dropped.
- `supported_locales` accepts an array of locale codes; the
`default_locale` is always implicitly included.
- Setting `default: true` automatically demotes the previous default
market in the store.
**Required scope:** `write_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 market = await client.markets.create({
name: 'Europe',
currency: 'EUR',
default_locale: 'de',
supported_locales: ['de', 'en', 'fr'],
tax_inclusive: true,
country_codes: ['DE', 'FR', 'IT'],
})
- lang: bash
label: Spree CLI
source: spree api post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_codes":["DE","FR","IT"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: market created
content:
application/json:
example:
id: mkt_EfhxLZ9ck8
name: France only
currency: EUR
default_locale: fr
tax_inclusive: true
default: false
country_codes:
- FR
supported_locales:
- en
- fr
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
schema:
"$ref": "#/components/schemas/Market"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank, Currency can't be blank, Default locale
can't be blank, and Countries can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
currency:
- code: blank
message: can't be blank
specific: false
default_locale:
- code: blank
message: can't be blank
specific: false
countries:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/MarketCreateParams"
required: true
"/api/v3/admin/markets/{id}":
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
summary: Get a market
tags:
- Markets
security:
- api_key: []
bearer_auth: []
description: "**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 market = await client.markets.get('market_xxx')
- lang: bash
label: Spree CLI
source: spree api get /markets/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: expand
in: query
required: false
schema:
type: string
responses:
'200':
description: market found
content:
application/json:
example:
id: mkt_gbHJdmfrXB
name: EU
currency: USD
default_locale: en
tax_inclusive: false
default: false
country_codes:
- DE
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
schema:
"$ref": "#/components/schemas/Market"
'404':
description: market not found
content:
application/json:
example:
error:
code: record_not_found
message: Market not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a market
tags:
- Markets
security:
- api_key: []
bearer_auth: []
description: |-
Updates an existing market. Pass `country_codes` to replace the
market's country list (full-set update), `supported_locales` to
replace the supported locales, or `position` to reorder the market
within the store.
Setting `default: true` automatically demotes the previous default.
**Required scope:** `write_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',
})
// `country_codes` is a full-set update — the market is reconciled to match
// the array (adds new countries, removes ones not present). Setting
// `default: true` demotes the previous default market in the store.
const market = await client.markets.update('market_UkLWZg9DAJ', {
name: 'European Union',
tax_inclusive: true,
country_codes: ['DE', 'FR'],
})
- lang: bash
label: Spree CLI
source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_codes":["DE","FR"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: market updated
content:
application/json:
example:
id: mkt_gbHJdmfrXB
name: European Union
currency: USD
default_locale: en
tax_inclusive: true
default: false
country_codes:
- DE
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
schema:
"$ref": "#/components/schemas/Market"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/MarketUpdateParams"
required: true
delete:
summary: Delete a market
tags:
- Markets
security:
- api_key: []
bearer_auth: []
description: |-
Soft-deletes the market (sets `deleted_at`). The default market and
the last remaining market in a store cannot be deleted — both return
422 with a `validation_error`.
**Required scope:** `write_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',
})
// Soft-deletes the market (sets `deleted_at`). The default market and the
// last remaining market in a store cannot be deleted — both return 422.
await client.markets.delete('market_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /markets/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: market deleted
'422':
description: cannot delete default or last market
content:
application/json:
example:
error:
code: validation_error
message: Market cannot be deleted
"/api/v3/admin/option_types/{option_type_id}/custom_fields":
get:
summary: List option type custom fields
tags:
- Option Types
security:
- api_key: []
bearer_auth: []
description: |-
Returns the option type's custom field 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 { data: customFields } = await client.optionTypes.customFields.list('opt_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /option_types/{option_type_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: option_type_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomField"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/option_types":
get:
summary: List option types
tags:
- Option Types
security:
- api_key: []
bearer_auth: []
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()
- lang: bash
label: Spree CLI
source: spree api get /option_types
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: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name and label (partial, case-insensitive).
- name: q[search_by_name]
in: query
required: false
schema:
type: string
description: Applies `search_by_name` to the given value.
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., option_values).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., name,label,position).
id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `kind` | One of `dropdown`, `color_swatch`, `buttons` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: OptionType
sortable:
- created_at
- id
- kind
- label
- name
- position
- updated_at
responses:
'200':
description: option types found
content:
application/json:
example:
data:
- id: opt_UkLWZg9DAJ
name: foo-size-14
label: Size
position: 1
kind: dropdown
metadata: {}
filterable: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/OptionType"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create an option type
tags:
- Option Types
security:
- api_key: []
bearer_auth: []
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',
label: 'Color',
option_values: [
{ name: 'red', label: 'Red' },
{ name: 'navy', label: 'Navy' },
],
})
- lang: bash
label: Spree CLI
source: spree api post /option_types -d '{"name":"color","label":"Color","option_values":[{"name":"red","label":"Red"},{"name":"navy","label":"Navy"}]}'
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
responses:
'201':
description: option type created
content:
application/json:
example:
id: opt_gbHJdmfrXB
name: material
label: Material
position: 2
kind: dropdown
metadata: {}
filterable: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank and Label can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
label:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OptionTypeCreateParams"
required: true
"/api/v3/admin/option_types/{id}":
get:
summary: Get an option type
tags:
- Option Types
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /option_types/{id}
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: id
in: path
required: true
description: Option type ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., option_values).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., name,label,position).
id is always included.
schema:
type: string
responses:
'200':
description: option type found
content:
application/json:
example:
id: opt_UkLWZg9DAJ
name: foo-size-18
label: Size
position: 1
kind: dropdown
metadata: {}
filterable: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
description: option type not found
content:
application/json:
example:
error:
code: record_not_found
message: Option type not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update an option type
tags:
- Option Types
security:
- api_key: []
bearer_auth: []
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', {
label: 'Updated Label',
option_values: [{ name: 'red', label: 'Crimson' }],
})
- lang: bash
label: Spree CLI
source: spree api patch /option_types/{id} -d '{"label":"Updated Label","option_values":[{"name":"red","label":"Crimson"}]}'
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: id
in: path
required: true
description: Option type ID
schema:
type: string
responses:
'200':
description: option type updated
content:
application/json:
example:
id: opt_UkLWZg9DAJ
name: foo-size-20
label: Updated Label
position: 1
kind: dropdown
metadata: {}
filterable: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Label can't be blank
details:
label:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OptionTypeUpdateParams"
required: true
delete:
summary: Delete an option type
tags:
- Option Types
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /option_types/{id}
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: id
in: path
required: true
description: Option type ID
schema:
type: string
responses:
'204':
description: option type deleted
"/api/v3/admin/claims":
get:
summary: List claims
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Every damage or missing-item claim in the store, across all orders.
**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: claims } = await client.claims.list({
status_eq: 'open',
sort: '-created_at',
})
- lang: bash
label: Spree CLI
source: spree api get /claims -d '{"status_eq":"open","sort":"-created_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Claim
sortable:
- created_at
- id
- number
- status
- updated_at
responses:
'200':
description: claims listed
content:
application/json:
example:
data:
- id: claim_UkLWZg9DAJ
number: CLM1001
status: open
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
approved_at:
resolved_at:
denied_at:
canceled_at:
memo: Arrived with a cracked screen
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id:
created_by_type:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Claim"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/orders/{order_id}/claims":
get:
summary: List order claims
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
The damage or missing-item claims opened on one 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: claims } = await client.orders.claims.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/claims
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Claim
sortable:
- created_at
- id
- number
- status
- updated_at
responses:
'200':
description: claims listed
content:
application/json:
example:
data:
- id: claim_UkLWZg9DAJ
number: CLM1001
status: open
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
approved_at:
resolved_at:
denied_at:
canceled_at:
memo: Arrived with a cracked screen
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id:
created_by_type:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Claim"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a claim
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Opens a damage or missing-item claim on a completed order. Each item says how it should be made right: money back, a replacement, or both.
**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',
})
// The customer keeps the goods: nothing comes back, so no return is opened.
const claim = await client.orders.claims.create('or_UkLWZg9DAJ', {
reason_id: 'clr_UkLWZg9DAJ',
memo: 'Arrived with a cracked lid',
items: [
{
line_item_id: 'li_UkLWZg9DAJ',
quantity: 1,
description: 'Lid cracked in transit',
send_replacement: true,
},
],
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/claims -d '{"reason_id":"clr_UkLWZg9DAJ","memo":"Arrived
with a cracked lid","items":[{"line_item_id":"li_UkLWZg9DAJ","quantity":1,"description":"Lid
cracked in transit","send_replacement":true}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
responses:
'201':
description: claim opened
content:
application/json:
example:
id: claim_gbHJdmfrXB
number: CLM1002
status: open
resolution:
order_id: or_gbHJdmfrXB
reason_id:
refund_total: '10.00'
approved_at:
resolved_at:
denied_at:
canceled_at:
memo: Arrived cracked
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
schema:
"$ref": "#/components/schemas/Claim"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ClaimCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/claims/{id}":
patch:
summary: Update a claim
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Edits the reason, memo or metadata of a claim. Its status moves only through the approve, resolve, deny and cancel actions.
**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 claim = await client.orders.claims.update('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
memo: 'Photos received from the customer',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/claims/{id} -d '{"memo":"Photos
received from the customer"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Claim prefixed ID
schema:
type: string
responses:
'200':
description: claim updated
content:
application/json:
example:
id: claim_UkLWZg9DAJ
number: CLM1001
status: open
resolution:
order_id: or_UkLWZg9DAJ
reason_id: clr_UkLWZg9DAJ
refund_total: '10.00'
approved_at:
resolved_at:
denied_at:
canceled_at:
memo: Customer sent photos
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Claim"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ClaimUpdateParams"
required: true
"/api/v3/admin/orders/{order_id}/claims/{id}/approve":
patch:
summary: Approve a claim
tags:
- Orders
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 claim = await client.orders.claims.approve('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/claims/{id}/approve -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Accepts an open claim, the step before resolving it with a refund, a replacement or both. Only an open claim can be approved; deny it to turn it down.
**Required scope:** `write_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Claim prefixed ID
schema:
type: string
responses:
'200':
description: claim approved
content:
application/json:
example:
id: claim_UkLWZg9DAJ
number: CLM1001
status: approved
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
approved_at: '2026-01-15T12:00:00Z'
resolved_at:
denied_at:
canceled_at:
memo: Arrived with a cracked screen
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
schema:
"$ref": "#/components/schemas/Claim"
"/api/v3/admin/orders/{order_id}/claims/{id}/resolve":
patch:
summary: Resolve a claim
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Settles an approved claim with money back, a replacement shipment, or both.
**Required scope:** `write_orders`, plus `write_refunds` for a resolution that 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 claim = await client.orders.claims.resolve('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
resolution: 'refund_and_replacement',
refund_method: 'original_payment',
amount: '5.00',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/claims/{id}/resolve -d '{"resolution":"refund_and_replacement","refund_method":"original_payment","amount":"5.00"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Claim prefixed ID
schema:
type: string
responses:
'200':
description: claim resolved
content:
application/json:
example:
id: claim_UkLWZg9DAJ
number: CLM1001
status: resolved
resolution: refund
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
approved_at: '2026-01-15T12:00:00Z'
resolved_at: '2026-01-15T12:00:00Z'
denied_at:
canceled_at:
memo: Arrived with a cracked screen
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Claim"
'422':
description: unknown resolution
content:
application/json:
example:
error:
code: processing_error
message: Invalid resolution
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ClaimResolveParams"
required: true
"/api/v3/admin/orders/{order_id}/claims/{id}/deny":
patch:
summary: Deny a claim
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Turns down an open claim, recording why for the customer.
**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 claim = await client.orders.claims.deny('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
reason: 'Damage is not covered after 30 days',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/claims/{id}/deny -d '{"reason":"Damage
is not covered after 30 days"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Claim prefixed ID
schema:
type: string
responses:
'200':
description: claim denied
content:
application/json:
example:
id: claim_UkLWZg9DAJ
number: CLM1001
status: denied
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
approved_at:
resolved_at:
denied_at: '2026-01-15T12:00:00Z'
canceled_at:
memo: |-
Arrived with a cracked screen
Outside warranty
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Claim"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ClaimDenyParams"
"/api/v3/admin/orders/{order_id}/claims/{id}/cancel":
patch:
summary: Cancel a claim
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Withdraws a claim that has not been resolved.
**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 claim = await client.orders.claims.cancel('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ', {
reason: 'Opened by mistake',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/claims/{id}/cancel -d '{"reason":"Opened
by mistake"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Claim prefixed ID
schema:
type: string
responses:
'200':
description: claim canceled
content:
application/json:
example:
id: claim_UkLWZg9DAJ
number: CLM1001
status: canceled
resolution:
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
approved_at:
resolved_at:
denied_at:
canceled_at: '2026-01-15T12:00:00Z'
memo: |-
Arrived with a cracked screen
Customer found the missing item
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Claim"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ClaimCancelParams"
"/api/v3/admin/orders/{order_id}/custom_fields":
get:
summary: List order custom fields
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Returns the order's custom field values.
**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: customFields } = await client.orders.customFields.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomField"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/digital_links":
get:
summary: List digital links
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Returns the download links issued for digital products bought in this store, newest first.
**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: digitalLinks } = await client.digitalLinks.list({
sort: '-created_at',
})
- lang: bash
label: Spree CLI
source: spree api get /digital_links -d '{"sort":"-created_at"}'
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: DigitalLink
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: digital links found
content:
application/json:
example:
data:
- id: dl_UkLWZg9DAJ
access_counter: 0
filename: thinking-cat.jpg
content_type: image/jpeg
download_url: "/api/v3/store/digital_links/Sh7B5YVQvB8N7t2mhgUnL9Lv"
expires_at: '2026-01-22T12:00:00Z'
authorizable: true
expired: false
access_limit_exceeded: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/DigitalLink"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/digital_links/{id}":
parameters:
- name: id
in: path
required: true
description: Digital link ID
schema:
type: string
get:
summary: Get a digital link
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single download link with its download count and expiry.
**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 digitalLink = await client.digitalLinks.retrieve('dl_xxx')
- lang: bash
label: Spree CLI
source: spree api get /digital_links/{id}
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
responses:
'200':
description: digital link found
content:
application/json:
example:
id: dl_UkLWZg9DAJ
access_counter: 0
filename: thinking-cat.jpg
content_type: image/jpeg
download_url: "/api/v3/store/digital_links/ks9F16gjTLQPCzwFDpj2ifrJ"
expires_at: '2026-01-22T12:00:00Z'
authorizable: true
expired: false
access_limit_exceeded: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/DigitalLink"
'404':
description: digital link not found
content:
application/json:
example:
error:
code: record_not_found
message: Digital link not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/digital_links/{id}/reset":
parameters:
- name: id
in: path
required: true
description: Digital link ID
schema:
type: string
patch:
summary: Reset a digital link
tags:
- Orders
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 digitalLink = await client.digitalLinks.reset('dl_xxx')
- lang: bash
label: Spree CLI
source: spree api patch /digital_links/{id}/reset -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Gives the customer their full download allowance back and restarts the
link's expiry clock. Use it when a download failed, or the file was
replaced after the customer had used up their attempts.
**Required scope:** `write_orders` (for API-key authentication).
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
responses:
'200':
description: digital link reset
content:
application/json:
example:
id: dl_UkLWZg9DAJ
access_counter: 0
filename: thinking-cat.jpg
content_type: image/jpeg
download_url: "/api/v3/store/digital_links/tPqch4JvZidezkNn2YoqxDLc"
expires_at: '2026-01-22T12:00:00Z'
authorizable: true
expired: false
access_limit_exceeded: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/DigitalLink"
"/api/v3/admin/exchanges":
get:
summary: List exchanges
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Every exchange in the store, across all orders.
**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: exchanges } = await client.exchanges.list({
status_eq: 'received',
sort: '-created_at',
})
- lang: bash
label: Spree CLI
source: spree api get /exchanges -d '{"status_eq":"received","sort":"-created_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Exchange
sortable:
- created_at
- id
- number
- status
- updated_at
responses:
'200':
description: exchanges listed
content:
application/json:
example:
data:
- id: exch_UkLWZg9DAJ
number: EX1001
status: requested
order_id: or_UkLWZg9DAJ
reason_id:
price_difference: '9.99'
approved_at:
received_at:
fulfilled_at:
canceled_at:
memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Exchange"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/orders/{order_id}/exchanges":
get:
summary: List order exchanges
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
The exchanges opened on one 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: exchanges } = await client.orders.exchanges.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/exchanges
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Exchange
sortable:
- created_at
- id
- number
- status
- updated_at
responses:
'200':
description: exchanges listed
content:
application/json:
example:
data:
- id: exch_UkLWZg9DAJ
number: EX1001
status: requested
order_id: or_UkLWZg9DAJ
reason_id:
price_difference: '9.99'
approved_at:
received_at:
fulfilled_at:
canceled_at:
memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Exchange"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create an exchange
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Opens an exchange on a completed order: items coming back, and the variant that goes out in place of each.
**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 exchange = await client.orders.exchanges.create('or_UkLWZg9DAJ', {
reason_id: 'rar_UkLWZg9DAJ',
stock_location_id: 'sloc_UkLWZg9DAJ',
items: [
{ fulfillment_item_id: 'fi_UkLWZg9DAJ', new_variant_id: 'variant_k5nR8xLq', quantity: 1 },
],
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/exchanges -d '{"reason_id":"rar_UkLWZg9DAJ","stock_location_id":"sloc_UkLWZg9DAJ","items":[{"fulfillment_item_id":"fi_UkLWZg9DAJ","new_variant_id":"variant_k5nR8xLq","quantity":1}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
responses:
'201':
description: exchange opened
content:
application/json:
example:
id: exch_gbHJdmfrXB
number: EX1002
status: requested
order_id: or_gbHJdmfrXB
reason_id:
price_difference: '9.99'
approved_at:
received_at:
fulfilled_at:
canceled_at:
memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
schema:
"$ref": "#/components/schemas/Exchange"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ExchangeCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/exchanges/{id}":
patch:
summary: Update an exchange
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Edits the warehouse, reason, memo or metadata of an exchange. Its status moves only through the approve, receive, fulfill and cancel actions.
**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 exchange = await client.orders.exchanges.update('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
memo: 'Customer prefers the larger size',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/exchanges/{id} -d '{"memo":"Customer
prefers the larger size"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Exchange prefixed ID
schema:
type: string
responses:
'200':
description: exchange updated
content:
application/json:
example:
id: exch_UkLWZg9DAJ
number: EX1001
status: requested
order_id: or_UkLWZg9DAJ
reason_id: rar_UkLWZg9DAJ
price_difference: '9.99'
approved_at:
received_at:
fulfilled_at:
canceled_at:
memo: Customer wants a larger size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Exchange"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ExchangeUpdateParams"
required: true
"/api/v3/admin/orders/{order_id}/exchanges/{id}/approve":
patch:
summary: Approve an exchange
tags:
- Orders
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 exchange = await client.orders.exchanges.approve('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/exchanges/{id}/approve -d '{ ...
}'
security:
- api_key: []
bearer_auth: []
description: |-
Accepts a requested exchange so the customer can send the goods back for their replacement. Only a requested exchange can be approved; receive it once the goods arrive.
**Required scope:** `write_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Exchange prefixed ID
schema:
type: string
responses:
'200':
description: exchange approved
content:
application/json:
example:
id: exch_UkLWZg9DAJ
number: EX1001
status: approved
order_id: or_UkLWZg9DAJ
reason_id:
price_difference: '9.99'
approved_at: '2026-01-15T12:00:00Z'
received_at:
fulfilled_at:
canceled_at:
memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
schema:
"$ref": "#/components/schemas/Exchange"
'422':
description: the exchange is not requested
content:
application/json:
example:
error:
code: processing_error
message: Not requested
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/orders/{order_id}/exchanges/{id}/receive":
patch:
summary: Receive an exchange
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Records the goods that came back on an approved exchange. Omit `items` to receive everything as requested and resellable.
**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',
})
// Omit `items` to receive everything as requested and resellable.
const exchange = await client.orders.exchanges.receive('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
items: [{ exchange_line_item_id: 'eli_UkLWZg9DAJ', quantity: 1, resellable: false }],
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/exchanges/{id}/receive -d '{"items":[{"exchange_line_item_id":"eli_UkLWZg9DAJ","quantity":1,"resellable":false}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Exchange prefixed ID
schema:
type: string
responses:
'200':
description: exchange received
content:
application/json:
example:
id: exch_UkLWZg9DAJ
number: EX1001
status: received
order_id: or_UkLWZg9DAJ
reason_id:
price_difference: '9.99'
approved_at: '2026-01-15T12:00:00Z'
received_at: '2026-01-15T12:00:00Z'
fulfilled_at:
canceled_at:
memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Exchange"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ExchangeReceiveParams"
"/api/v3/admin/orders/{order_id}/exchanges/{id}/fulfill":
patch:
summary: Fulfill an exchange
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Ships the replacements for a received exchange and settles any price difference.
**Required scope:** `write_orders` and `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 exchange = await client.orders.exchanges.fulfill('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
refund_method: 'store_credit',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/exchanges/{id}/fulfill -d '{"refund_method":"store_credit"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Exchange prefixed ID
schema:
type: string
responses:
'200':
description: exchange fulfilled
content:
application/json:
example:
id: exch_UkLWZg9DAJ
number: EX1001
status: fulfilled
order_id: or_UkLWZg9DAJ
reason_id:
price_difference: '9.99'
approved_at: '2026-01-14T12:00:00Z'
received_at: '2026-01-15T12:00:00Z'
fulfilled_at: '2026-01-15T12:00:00Z'
canceled_at:
memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Exchange"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ExchangeFulfillParams"
"/api/v3/admin/orders/{order_id}/exchanges/{id}/cancel":
patch:
summary: Cancel an exchange
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Withdraws an exchange whose goods have not been received.
**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 exchange = await client.orders.exchanges.cancel('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ', {
reason: 'Customer kept the original item',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/exchanges/{id}/cancel -d '{"reason":"Customer
kept the original item"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Exchange prefixed ID
schema:
type: string
responses:
'200':
description: exchange canceled
content:
application/json:
example:
id: exch_UkLWZg9DAJ
number: EX1001
status: canceled
order_id: or_UkLWZg9DAJ
reason_id:
price_difference: '9.99'
approved_at:
received_at:
fulfilled_at:
canceled_at: '2026-01-15T12:00:00Z'
memo: |-
Wrong size
Customer kept the original
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
schema:
"$ref": "#/components/schemas/Exchange"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ExchangeCancelParams"
"/api/v3/admin/orders/{order_id}/tax_lines":
get:
summary: List tax lines
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Typed tax rows on the order. Read-only — written exclusively by the tax provider.
**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: taxLines } = await client.orders.taxLines.list('or_abc123')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/tax_lines
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[provider_id_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `country_code` | One of the `CountryCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `included` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `provider_id` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `taxability_reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `country_code`, `created_at`, `id`, `included`, `provider_id`, `state_code`, `taxability_reason`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: TaxLine
sortable:
- country_code
- created_at
- id
- included
- provider_id
- state_code
- taxability_reason
- updated_at
responses:
'200':
description: tax lines found
content:
application/json:
example:
data:
- id: tl_UkLWZg9DAJ
label: VAT 15%
included: false
credit: false
rate: '0.15'
tax_rate_id:
line_item_id: li_UkLWZg9DAJ
fulfillment_id:
fee_id:
return_line_item_id:
claim_line_item_id:
exchange_line_item_id:
amount: '1.50'
provider_id: internal
metadata: {}
taxability_reason:
country_code:
state_code:
data: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_tax_line_id:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
"/api/v3/admin/orders/{order_id}/discounts":
get:
summary: List discounts
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Typed discount rows (promotion-sourced and manual) on the 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: discounts } = await client.orders.discounts.list('or_abc123')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/discounts
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Discount
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: discounts found
content:
application/json:
example:
data:
- id: disc_UkLWZg9DAJ
label: Loyalty
kind: manual
code:
value_type:
value:
promotion_id:
line_item_id: li_UkLWZg9DAJ
fulfillment_id:
amount: "-2.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create manual discount
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.
**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',
})
// Line-item discount; omit line_item_id to distribute across the order.
const { data: discounts } = await client.orders.discounts.create('or_abc123', {
label: 'Customer appeasement',
value: '10',
value_type: 'flat',
line_item_id: 'item_abc123',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/discounts -d '{"label":"Customer
appeasement","value":"10","value_type":"flat","line_item_id":"item_abc123"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
responses:
'201':
description: discount created
content:
application/json:
example:
data:
- id: disc_UkLWZg9DAJ
label: Appeasement
kind: manual
code:
value_type: flat
value: '3.00'
promotion_id:
line_item_id: li_UkLWZg9DAJ
fulfillment_id:
amount: "-3.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
'422':
description: invalid discount
content:
application/json:
example:
error:
code: invalid_money_format
message: value must be a decimal string like "19.99"
details:
value:
- must be a decimal string like "19.99"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/DiscountCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/discounts/{id}":
patch:
summary: Update manual discount
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Edits the label or amount of a manual discount and re-sums the order totals. Promotion-sourced rows are owned by recalculation and respond 422.
**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 discount = await client.orders.discounts.update('or_UkLWZg9DAJ', 'disc_UkLWZg9DAJ', {
label: 'Customer appeasement',
amount: '15.00',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/discounts/{id} -d '{"label":"Customer
appeasement","amount":"15.00"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Discount prefixed ID
schema:
type: string
responses:
'200':
description: discount updated
content:
application/json:
example:
id: disc_UkLWZg9DAJ
label: Loyalty reward
kind: manual
code:
value_type:
value:
promotion_id:
line_item_id: li_UkLWZg9DAJ
fulfillment_id:
amount: "-5.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/DiscountUpdateParams"
required: true
"/api/v3/admin/orders/{order_id}/fees":
get:
summary: List fees
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Returns the order's fees, such as surcharges, handling and gift wrap, on the whole order or on one item or delivery.
**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: fees } = await client.orders.fees.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/fees
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Fee
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: fees found
content:
application/json:
example:
data:
- id: fee_UkLWZg9DAJ
label: Gift wrap
kind: gift_wrap
line_item_id:
fulfillment_id:
amount: '4.00'
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Fee"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create fee
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.
**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 fee = await client.orders.fees.create('or_abc123', {
label: 'Gift wrap',
amount: '4.00',
kind: 'gift_wrap',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":"4.00","kind":"gift_wrap"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
responses:
'201':
description: fee created
content:
application/json:
example:
id: fee_UkLWZg9DAJ
label: Gift wrap
kind: gift_wrap
line_item_id:
fulfillment_id:
amount: '4.00'
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
'422':
description: invalid fee
content:
application/json:
example:
error:
code: validation_error
message: Kind is not included in the list
details:
kind:
- value: nonsense
code: inclusion
message: is not included in the list
specific: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FeeCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/fees/{id}":
patch:
summary: Update fee
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Edits the label, amount or kind of a fee and re-sums the order totals. Works on completed orders.
**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 fee = await client.orders.fees.update('or_UkLWZg9DAJ', 'fee_UkLWZg9DAJ', {
label: 'Gift wrap',
amount: '5.00',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/fees/{id} -d '{"label":"Gift wrap","amount":"5.00"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Fee prefixed ID
schema:
type: string
responses:
'200':
description: fee updated
content:
application/json:
example:
id: fee_UkLWZg9DAJ
label: Handling
kind: handling
line_item_id:
fulfillment_id:
amount: '8.00'
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Fee"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/FeeUpdateParams"
required: true
"/api/v3/admin/order_groups":
get:
summary: List order groups
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Returns checkouts split into one order per seller, grouping the orders placed together.
**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: orderGroups } = await client.orderGroups.list({
email_cont: '[email protected]',
sort: '-created_at',
})
- lang: bash
label: Spree CLI
source: spree api get /order_groups -d '{"email_cont":"[email protected]","sort":"-created_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `currency`, `email`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: OrderGroup
sortable:
- created_at
- currency
- email
- id
- number
- updated_at
responses:
'200':
description: order groups found
content:
application/json:
example:
data:
- id: ogrp_UkLWZg9DAJ
number: R1001
email: [email protected]
currency: USD
item_total: '0.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '0.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '0.00'
amount_due: '0.00'
covered_by_store_credit: false
payments: []
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
billing_address:
shipping_address:
orders: []
customer_id: cust_UkLWZg9DAJ
cart_id:
seller_count: 0
includes_first_party: false
confirmation_delivered: false
store_owner_notification_delivered: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/OrderGroup"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/orders/{order_id}/discount_codes":
post:
summary: Apply a discount code
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Applies a discount code to a draft order and returns the order. A real code the order does not yet qualify for is kept and applies once it does. Completed orders refuse codes; change their discounts through manual discounts instead.
**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.discountCodes.create('or_UkLWZg9DAJ', {
code: 'SUMMER20',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/discount_codes -d '{"code":"SUMMER20"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
responses:
'201':
description: discount code applied
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code: save5
fulfillment_status:
payment_status:
completed_at:
item_total: '50.00'
discount_total: "-5.00"
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '145.00'
amount_due: '145.00'
covered_by_store_credit: false
adjustment_total: "-5.00"
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
'422':
description: unknown discount code
content:
application/json:
example:
error:
code: processing_error
message: The coupon code you entered doesn't exist. Please try again.
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/DiscountCodeApplyParams"
required: true
"/api/v3/admin/orders/{order_id}/gift_cards":
post:
summary: Apply a gift card to an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'
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 ID
schema:
type: string
responses:
'201':
description: gift card applied
content:
application/json:
example:
id: gc_UkLWZg9DAJ
code: "************2F41"
status: active
currency: USD
amount: '10.00'
amount_used: '10.00'
amount_authorized: '0.00'
amount_remaining: '0.00'
expires_at:
redeemed_at:
expired: false
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
customer_id:
created_by_id:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/GiftCardApplyParams"
required: true
"/api/v3/admin/orders/{order_id}/gift_cards/{id}":
delete:
summary: Remove a gift card from an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /orders/{order_id}/gift_cards/{id}
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Gift card ID
schema:
type: string
responses:
'204':
description: gift card removed
"/api/v3/admin/orders/{order_id}/items":
get:
summary: List order items
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/items
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 ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., variant, variant.product).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., quantity,price,total).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[additional_tax_total_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `additional_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `discount_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `included_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `non_taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `pre_tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
| `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
</Accordion>
**Sort by:** `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: LineItem
sortable:
- additional_tax_total
- adjustment_total
- cost_price
- created_at
- discount_total
- id
- included_tax_total
- non_taxable_adjustment_total
- order_id
- pre_tax_amount
- price
- quantity
- tax_category_id
- taxable_adjustment_total
- updated_at
- variant_id
responses:
'200':
description: items found
content:
application/json:
example:
data:
- id: li_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
seller_id:
preorder: false
preorder_ships_at:
quantity: 2
currency: USD
name: Product 779180
slug: product-779180
options_text: 'Size: S'
price: '10.00'
total: '20.00'
adjustment_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
discount_total: '0.00'
pre_tax_amount: '20.00'
discounted_amount: '20.00'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
name: size-13
label: S
position: 1
color_code:
option_type_name: foo-size-23
option_type_label: Size
image_url:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
digital_links: []
external_references: {}
metadata: {}
price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
price_list_id:
price_list_name:
catalog_id:
catalog_name:
cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Add an item
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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,
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'
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 ID
schema:
type: string
responses:
'201':
description: item added
content:
application/json:
example:
id: li_gbHJdmfrXB
variant_id: variant_VqXmZF31wY
seller_id:
preorder: false
preorder_ships_at:
quantity: 3
currency: USD
name: Product 7999
slug: product-7999
options_text: 'Size: S'
price: '19.99'
total: '59.97'
adjustment_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
discount_total: '0.00'
pre_tax_amount: '59.97'
discounted_amount: '59.97'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_gbHJdmfrXB
option_type_id: opt_gbHJdmfrXB
name: size-15
label: S
position: 1
color_code:
option_type_name: foo-size-25
option_type_label: Size
image_url:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
digital_links: []
external_references: {}
metadata: {}
price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
price_list_id:
price_list_name:
catalog_id:
catalog_name:
cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/LineItemCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/items/{id}":
get:
summary: Show an item
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/items/{id}
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Item ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., variant, variant.product).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., quantity,price,total).
id is always included.
schema:
type: string
responses:
'200':
description: item found
content:
application/json:
example:
id: li_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
seller_id:
preorder: false
preorder_ships_at:
quantity: 2
currency: USD
name: Product 802714
slug: product-802714
options_text: 'Size: S'
price: '10.00'
total: '20.00'
adjustment_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
discount_total: '0.00'
pre_tax_amount: '20.00'
discounted_amount: '20.00'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
name: size-16
label: S
position: 1
color_code:
option_type_name: foo-size-26
option_type_label: Size
image_url:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
digital_links: []
external_references: {}
metadata: {}
price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
price_list_id:
price_list_name:
catalog_id:
catalog_name:
cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
summary: Update an item
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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,
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/items/{id} -d '{"quantity":5}'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Item ID
schema:
type: string
responses:
'200':
description: item updated
content:
application/json:
example:
id: li_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
seller_id:
preorder: false
preorder_ships_at:
quantity: 5
currency: USD
name: Product 819758
slug: product-819758
options_text: 'Size: S'
price: '19.99'
total: '99.95'
adjustment_total: '0.00'
additional_tax_total: '0.00'
included_tax_total: '0.00'
discount_total: '0.00'
pre_tax_amount: '99.95'
discounted_amount: '99.95'
compare_at_amount:
thumbnail_url:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
name: size-17
label: S
position: 1
color_code:
option_type_name: foo-size-27
option_type_label: Size
image_url:
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
digital_links: []
external_references: {}
metadata: {}
price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
price_list_id:
price_list_name:
catalog_id:
catalog_name:
cost_price: '17.00'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/LineItemUpdateParams"
required: true
delete:
summary: Remove an item
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /orders/{order_id}/items/{id}
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Item ID
schema:
type: string
responses:
'204':
description: line item removed
"/api/v3/admin/orders/{order_id}/store_credits":
post:
summary: Apply customer's store credit to an order
tags:
- 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.
**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',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'
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 ID
schema:
type: string
responses:
'201':
description: store credit applied
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code:
fulfillment_status:
payment_status:
completed_at:
item_total: '10.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '50.00'
total: '110.00'
amount_due: '60.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/StoreCreditApplyParams"
required: true
delete:
summary: Remove store credit from an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /orders/{order_id}/store_credits
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 ID
schema:
type: string
responses:
'204':
description: store credit removed
"/api/v3/admin/orders":
get:
summary: List orders
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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,
})
- lang: bash
label: Spree CLI
source: spree api get /orders -d '{"status_eq":"complete","completed_at_gt":"2026-01-01","sort":"-completed_at","limit":25}'
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: q[search]
in: query
required: false
schema:
type: string
description: Matches order number or purchase order number (partial), the
billing first or last name, or the exact email.
- name: q[complete]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `complete`.
- name: q[incomplete]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `incomplete`.
- name: q[partially_refunded]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `partially_refunded`.
- name: q[refunded]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `refunded`.
- 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
- name: sort
in: query
required: false
description: Sort field (e.g., created_at, -created_at, completed_at)
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., items, fulfillments,
payments, customer, discounts, billing_address, shipping_address). Use dot
notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., number,total,status,completed_at).
id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `considered_risky` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `coupon_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `delivery_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `fulfillment_status` | One of `backorder`, `canceled`, `partial`, `unfulfilled`, `fulfilled`, `delivered`, `pending`, `ready`, `shipped` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `item_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `locale` | One of the `LocaleCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `market_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `order_group_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `payment_status` | One of `none`, `authorized`, `partially_paid`, `paid`, `partially_refunded`, `refunded`, `overcharged`, `voided`, `balance_due`, `credit_owed`, `failed`, `void` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `po_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `status` | One of `draft`, `placed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `total_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[bill_address_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `line_items_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
| `line_items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_group_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `promotions_coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |
| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `store_` | `created_at`, `id`, `name`, `updated_at` |
| `tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Order
sortable:
- channel_id
- completed_at
- considered_risky
- coupon_code
- created_at
- currency
- customer_id
- delivery_total
- email
- fulfillment_status
- id
- item_total
- locale
- market_id
- number
- order_group_id
- payment_state
- payment_status
- po_number
- seller_id
- shipment_state
- status
- total
- total_quantity
- updated_at
responses:
'200':
description: orders found
content:
application/json:
example:
data:
- id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 0
coupon_code:
fulfillment_status:
payment_status:
completed_at:
item_total: '0.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '0.00'
fee_total:
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '0.00'
amount_due: '0.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a draft order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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, channel,
// 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',
channel_id: 'ch_UkLWZg9DAJ', // Optional — defaults to the store's primary channel
locale: 'en-US',
// Pin the order's preferred fulfillment location. Order Routing's
// built-in PreferredLocation rule ranks this location first when
// it stocks the cart's items; if it doesn't, routing falls back
// to the next rule (Minimize Splits → Default Location).
preferred_stock_location_id: 'sloc_UkLWZg9DAJ',
customer_note: 'Please leave at the front desk.',
// Rich text: send HTML. Reads return this as plain text, plus
// `internal_note_html` with the markup.
internal_note: '<p>VIP customer — handle with care.</p>',
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_code: 'US',
state_code: '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_code: 'US',
state_code: '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',
})
- lang: bash
label: Spree CLI
source: spree api post /orders -d '{"email":"[email protected]","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please
leave at the front desk.","internal_note":"<p>VIP customer — handle with
care.</p>","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350
Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350
Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
212 555 1234"},"coupon_code":"WELCOME10"}'
description: |-
Creates a new draft order in one shot. Customer, items, addresses, currency,
market, channel, locale, notes, metadata, and a coupon code can all be
provided inline.
Setting `preferred_stock_location_id` pins the order's preferred fulfillment
location — Order Routing's built-in `PreferredLocation` rule consumes it
when picking which stock location ships each shipment.
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
required: true
schema:
type: string
- name: Authorization
in: header
required: true
description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
description: order created with preferred_stock_location_id
content:
application/json:
example:
id: or_gbHJdmfrXB
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1002
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 0
coupon_code:
fulfillment_status:
payment_status:
completed_at:
item_total: '0.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '0.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '0.00'
amount_due: '0.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id: sloc_UkLWZg9DAJ
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
cancel_reason_id:
cancel_reason_name:
customer_id:
freight_summary:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OrderCreateParams"
required: true
"/api/v3/admin/orders/{id}":
get:
summary: Show an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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'],
})
- lang: bash
label: Spree CLI
source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'
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: id
in: path
required: true
description: Order ID (e.g., or_xxx)
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., items, fulfillments,
payments, customer, discounts, billing_address, shipping_address). Use dot
notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., number,total,status,completed_at).
id is always included.
schema:
type: string
responses:
'200':
description: order found
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 0
coupon_code:
fulfillment_status:
payment_status:
completed_at:
item_total: '0.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '0.00'
fee_total:
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '0.00'
amount_due: '0.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
'404':
description: order not found
content:
application/json:
example:
error:
code: order_not_found
message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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: '<p>VIP — gift wrap on next order</p>',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"<p>VIP
— gift wrap on next order</p>"}'
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: order updated
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 0
coupon_code:
fulfillment_status:
payment_status: none
completed_at:
item_total: '0.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '0.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '0.00'
amount_due: '0.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OrderUpdateParams"
required: true
delete:
summary: Delete a draft order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /orders/{id}
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'204':
description: order deleted
"/api/v3/admin/orders/{id}/complete":
patch:
summary: Complete an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Completes an order in the `confirm` state, marking it as placed.
Set `notify_customer: true` to send the order confirmation email.
On a marketplace, an order holding several sellers' goods becomes one
order per seller, and the response is the order group they belong to
with those orders nested inside it.
**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 result = await client.orders.complete('or_UkLWZg9DAJ', {
notify_customer: true,
})
// An order holding several sellers' goods becomes one order per seller.
const orders = isOrderGroup(result) ? result.orders : [result]
- lang: bash
label: Spree CLI
source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: order completed
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: true
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code:
fulfillment_status: unfulfilled
payment_status: paid
completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '110.00'
amount_due: '0.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: placed
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '110.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
'422':
description: order cannot be completed
content:
application/json:
example:
error:
code: order_cannot_complete
message: No payment found
details:
base:
- code:
message: No payment found
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OrderCompleteParams"
required: true
"/api/v3/admin/orders/{id}/cancel":
patch:
summary: Cancel an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Cancels a completed order.
`cancel_reason_id` records why, from the store's own cancellation-reason
vocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a
staff-facing note; both are shown on the order afterwards.
Stock is always released — the goods are not going out either way — and
every payment is settled at the gateway, which releases an
authorization it never drew on and refunds a charge it cannot release.
`refund_payments` and `refund_amount` govern the shared payment of a
split checkout, where one payment covers several orders: they decide
whether this order's share comes back, and how much of it. A
`refund_amount` on an ordinary order is refused with a 422.
Set `notify_customer: true` to send the order cancellation email.
**Required scope:** `write_orders`, plus `write_refunds` with `refund_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',
})
// A split checkout: the payment is shared, so what comes back is this order's
// own share. refund_amount names part of that share, keeping the rest back.
const order = await client.orders.cancel('or_UkLWZg9DAJ', {
cancel_reason_id: 'ocr_UkLWZg9DAJ',
cancel_note: 'Supplier could not deliver in time',
refund_payments: true,
refund_amount: '25.00',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{id}/cancel -d '{"cancel_reason_id":"ocr_UkLWZg9DAJ","cancel_note":"Supplier
could not deliver in time","refund_payments":true,"refund_amount":"25.00"}'
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: order canceled
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: false
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code:
fulfillment_status: canceled
payment_status: none
completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '110.00'
amount_due: '0.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: canceled
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at: '2026-01-15T12:00:00.000Z'
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id: adm_UkLWZg9DAJ
canceler_type: admin_user
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/OrderCancelParams"
required: true
"/api/v3/admin/orders/{id}/approve":
patch:
summary: Approve an order
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{id}/approve -d '{ ... }'
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: order approved
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: true
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '110.00'
amount_due: '110.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: placed
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id: adm_UkLWZg9DAJ
approver_type: admin_user
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
"/api/v3/admin/orders/{id}/resend_confirmation":
post:
summary: Resend confirmation email
tags:
- Orders
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api post /orders/{id}/resend_confirmation -d '{ ... }'
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: confirmation resent
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: true
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '110.00'
amount_due: '110.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
status: placed
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
"/api/v3/admin/orders/{id}/resend_digital_links":
post:
summary: Resend digital download links
tags:
- Orders
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.resendDigitalLinks('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api post /orders/{id}/resend_digital_links -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Emails the customer their download links for the digital products on
this order again. Nothing is sent when the order has no digital links or
the store does not send transactional emails. Use it when the original
email was lost; to restore used-up downloads or an expired link, reset
the digital link instead.
**Required scope:** `write_orders` (for API-key authentication).
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: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: digital links resent
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
within_withdrawal_period: true
shipping_eq_billing_address: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
company_name:
po_document_filename:
po_document_byte_size:
number: R1001
email: [email protected]
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
coupon_code:
fulfillment_status:
payment_status:
completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.00'
discount_total: '0.00'
tax_total: '0.00'
included_tax_total: '0.00'
additional_tax_total: '0.00'
delivery_total: '100.00'
fee_total: '0.00'
gift_card_total: '0.00'
store_credit_total: '0.00'
total: '110.00'
amount_due: '110.00'
covered_by_store_credit: false
adjustment_total: '0.00'
gift_card:
market:
id: mkt_UkLWZg9DAJ
name: United States
currency: USD
default_locale: en
tax_inclusive: false
default: true
country_codes:
- US
supported_locales:
- en
created_at: '2026-11-03T16:44:09.130Z'
updated_at: '2026-11-03T16:44:09.130Z'
tax_provider:
external_references: {}
status: placed
last_ip_address:
considered_risky: false
confirmation_delivered: false
store_owner_notification_delivered:
metadata: {}
cancel_note:
canceled_at:
approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
commission_amount_total: '0.00'
commission_tax_total: '0.00'
commission_total: '0.00'
preferred_stock_location_id:
po_document_url:
seller_id:
order_group_id:
tags: []
internal_note:
internal_note_html:
approver_id:
approver_type:
canceler_id:
canceler_type:
created_by_id:
created_by_type:
cancel_reason_id:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
schema:
"$ref": "#/components/schemas/Order"
"/api/v3/admin/returns":
get:
summary: List returns
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Every return in the store, across all orders.
**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: returns } = await client.returns.list({
status_eq: 'requested',
sort: '-created_at',
})
- lang: bash
label: Spree CLI
source: spree api get /returns -d '{"status_eq":"requested","sort":"-created_at"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Return
sortable:
- created_at
- id
- number
- status
- updated_at
responses:
'200':
description: returns listed
content:
application/json:
example:
data:
- id: ret_UkLWZg9DAJ
number: RET1001
status: requested
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at:
received_at:
refunded_at:
canceled_at:
external_references: {}
memo: Item did not fit
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Return"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/orders/{order_id}/returns":
get:
summary: List order returns
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
The returns opened on one 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: returns } = await client.orders.returns.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/returns
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of number (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Return
sortable:
- created_at
- id
- number
- status
- updated_at
responses:
'200':
description: returns listed
content:
application/json:
example:
data:
- id: ret_UkLWZg9DAJ
number: RET1001
status: requested
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at:
received_at:
refunded_at:
canceled_at:
external_references: {}
memo: Item did not fit
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Return"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a return
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Opens a return on a completed order for fulfilled units the customer is sending back.
**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 orderReturn = await client.orders.returns.create('or_UkLWZg9DAJ', {
reason_id: 'rar_UkLWZg9DAJ',
items: [{ fulfillment_item_id: 'fi_UkLWZg9DAJ', quantity: 1 }],
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/returns -d '{"reason_id":"rar_UkLWZg9DAJ","items":[{"fulfillment_item_id":"fi_UkLWZg9DAJ","quantity":1}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
responses:
'201':
description: return opened
content:
application/json:
example:
id: ret_gbHJdmfrXB
number: RET1002
status: requested
order_id: or_gbHJdmfrXB
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at:
received_at:
refunded_at:
canceled_at:
external_references: {}
memo: Too small
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
schema:
"$ref": "#/components/schemas/Return"
'422':
description: more returned than was fulfilled
content:
application/json:
example:
error:
code: processing_error
message: Only 1 of Product 1792493 can be returned
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReturnCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/returns/{id}":
patch:
summary: Update a return
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Edits the warehouse, reason, memo or metadata of a return. Its status moves only through the approve, receive, refund and cancel actions.
**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 orderReturn = await client.orders.returns.update('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
stock_location_id: 'sloc_UkLWZg9DAJ',
memo: 'Send to the returns warehouse',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/returns/{id} -d '{"stock_location_id":"sloc_UkLWZg9DAJ","memo":"Send
to the returns warehouse"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Return prefixed ID
schema:
type: string
responses:
'200':
description: return updated
content:
application/json:
example:
id: ret_UkLWZg9DAJ
number: RET1001
status: requested
order_id: or_UkLWZg9DAJ
reason_id: rar_UkLWZg9DAJ
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at:
received_at:
refunded_at:
canceled_at:
external_references: {}
memo: Customer shipped it back with a tracking number
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
schema:
"$ref": "#/components/schemas/Return"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReturnUpdateParams"
required: true
"/api/v3/admin/orders/{order_id}/returns/{id}/approve":
patch:
summary: Approve a return
tags:
- Orders
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 orderReturn = await client.orders.returns.approve('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/returns/{id}/approve -d '{ ...
}'
security:
- api_key: []
bearer_auth: []
description: |-
Accepts a requested return so the customer can send the goods back. Only a requested return can be approved; receive it once the goods arrive.
**Required scope:** `write_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Return prefixed ID
schema:
type: string
responses:
'200':
description: return approved
content:
application/json:
example:
id: ret_UkLWZg9DAJ
number: RET1001
status: approved
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at: '2026-01-15T12:00:00Z'
received_at:
refunded_at:
canceled_at:
external_references: {}
memo: Item did not fit
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
created_by_type: admin_user
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
schema:
"$ref": "#/components/schemas/Return"
'422':
description: the return is not requested
content:
application/json:
example:
error:
code: processing_error
message: Not requested
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/orders/{order_id}/returns/{id}/receive":
patch:
summary: Receive a return
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Records what arrived on an approved return. Omit `items` to receive everything as requested and resellable; send rows for a partial or damaged receipt.
**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',
})
// Omit `items` to receive everything as requested and resellable.
const orderReturn = await client.orders.returns.receive('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
items: [{ return_line_item_id: 'rli_UkLWZg9DAJ', quantity: 1, resellable: false }],
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/returns/{id}/receive -d '{"items":[{"return_line_item_id":"rli_UkLWZg9DAJ","quantity":1,"resellable":false}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Return prefixed ID
schema:
type: string
responses:
'200':
description: return received
content:
application/json:
example:
id: ret_UkLWZg9DAJ
number: RET1001
status: received
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at: '2026-01-15T12:00:00Z'
received_at: '2026-01-15T12:00:00Z'
refunded_at:
canceled_at:
external_references: {}
memo: Item did not fit
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
schema:
"$ref": "#/components/schemas/Return"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReturnReceiveParams"
"/api/v3/admin/orders/{order_id}/returns/{id}/refund":
patch:
summary: Refund a return
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Pays the customer back for a received return, to store credit or through the original payment.
**Required scope:** `write_orders` and `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 orderReturn = await client.orders.returns.refund('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
amount: '29.99',
refund_method: 'original_payment',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/returns/{id}/refund -d '{"amount":"29.99","refund_method":"original_payment"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Return prefixed ID
schema:
type: string
responses:
'200':
description: return refunded
content:
application/json:
example:
id: ret_UkLWZg9DAJ
number: RET1001
status: refunded
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at: '2026-01-14T12:00:00Z'
received_at: '2026-01-15T12:00:00Z'
refunded_at: '2026-01-15T12:00:00Z'
canceled_at:
external_references: {}
memo: Item did not fit
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
refunded_total: '10.00'
refundable_total: '0.00'
documents: []
labels: []
deliveries: []
schema:
"$ref": "#/components/schemas/Return"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReturnRefundParams"
"/api/v3/admin/orders/{order_id}/returns/{id}/cancel":
patch:
summary: Cancel a return
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
Withdraws a return whose goods have not been received.
**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 orderReturn = await client.orders.returns.cancel('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
reason: 'Customer decided to keep the item',
})
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/returns/{id}/cancel -d '{"reason":"Customer
decided to keep the item"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Return prefixed ID
schema:
type: string
responses:
'200':
description: return canceled
content:
application/json:
example:
id: ret_UkLWZg9DAJ
number: RET1001
status: canceled
order_id: or_UkLWZg9DAJ
reason_id:
refund_total: '10.00'
refund_tax_total: '0.00'
approved_at:
received_at:
refunded_at:
canceled_at: '2026-01-15T12:00:00Z'
external_references: {}
memo: |-
Item did not fit
Customer changed their mind
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_id: sloc_UkLWZg9DAJ
created_by_id:
created_by_type:
refunded_total: '0.00'
refundable_total: '10.00'
documents: []
labels: []
deliveries: []
schema:
"$ref": "#/components/schemas/Return"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReturnCancelParams"
"/api/v3/admin/orders/{order_id}/returns/{return_id}/labels":
get:
summary: List return labels
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
The shipping labels issued for sending one return back to the 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: labels } = await client.orders.returns.labels.list('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/returns/{return_id}/labels
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: return_id
in: path
required: true
description: Return 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `carrier`, `created_at`, `id`, `source`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: ShippingLabel
sortable:
- carrier
- created_at
- id
- source
- status
- tracking_number
- updated_at
responses:
'200':
description: labels listed
content:
application/json:
example:
data:
- id: lbl_UkLWZg9DAJ
source: purchased
status: purchased
carrier: ups
carrier_name: UPS
service: Ground
tracking_number: 1Z879E930346830006
currency: USD
format: pdf
external_id: shp_3
metadata: {}
refunded_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
owner_id: ret_UkLWZg9DAJ
owner_type: return
cost: '7.25'
integration_id:
file_pending: false
download_url:
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/ShippingLabel"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/orders/{order_id}/returns/{return_id}/labels/{id}/refund":
patch:
summary: Refund a return label
tags:
- Orders
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 label = await client.orders.returns.labels.refund(
'or_UkLWZg9DAJ',
'ret_UkLWZg9DAJ',
'lbl_UkLWZg9DAJ',
)
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/returns/{return_id}/labels/{id}/refund
-d '{ ... }'
operationId: return_labels_refund
security:
- api_key: []
bearer_auth: []
description: |-
Asks the carrier to refund a purchased return label the customer never used, such as when the return is canceled. An uploaded label has nothing to refund.
**Required scope:** `write_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: order_id
in: path
required: true
description: Order prefixed ID
schema:
type: string
- name: return_id
in: path
required: true
description: Return prefixed ID
schema:
type: string
- name: id
in: path
required: true
description: Shipping label prefixed ID
schema:
type: string
responses:
'200':
description: refund filed
content:
application/json:
example:
id: lbl_UkLWZg9DAJ
source: purchased
status: refunded
carrier: ups
carrier_name: UPS
service: Ground
tracking_number: 1Z879E930346830007
currency: USD
format: pdf
external_id: shp_4
metadata: {}
refunded_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
owner_id: ret_UkLWZg9DAJ
owner_type: return
cost: '7.25'
integration_id:
file_pending: false
download_url:
schema:
"$ref": "#/components/schemas/ShippingLabel"
'422':
description: uploaded labels cannot be refunded
content:
application/json:
example:
error:
code: processing_error
message: An uploaded label was not bought through Spree and cannot
be refunded — delete it instead
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/payment_methods/{payment_method_id}/custom_fields":
get:
summary: List payment method custom fields
tags:
- Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
Returns the payment method's custom field values.
**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: customFields } = await client.customFields('payment_method', 'pm_UkLWZg9DAJ').list()
- lang: bash
label: Spree CLI
source: spree api get /payment_methods/{payment_method_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: payment_method_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/CustomField"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
"/api/v3/admin/payment_methods":
get:
summary: List payment methods
tags:
- Payment Methods
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.
**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()
- lang: bash
label: Spree CLI
source: spree api get /payment_methods
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name (partial, case-insensitive).
- name: expand
in: query
required: false
description: Comma-separated associations to expand. Use dot notation for
nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., name,type,active).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: PaymentMethod
sortable:
- active
- created_at
- id
- name
- position
- storefront_visible
- type
- updated_at
responses:
'200':
description: payment methods found
content:
application/json:
example:
data:
- id: pm_UkLWZg9DAJ
name: Check 3
description:
type: check
session_required: false
source_required: false
metadata: {}
active: true
capture_method:
resolved_capture_method: checkout
storefront_visible: true
position: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
preferences: {}
logo_url:
docs_url:
third_party: false
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create a payment method
tags:
- Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
Adds a payment method to the store. `type` is a shorthand from the
payment method types endpoint, and `preferences` takes the values its
preference schema declares (gateway credentials among them).
**Required scope:** `write_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.create({
type: 'check',
name: 'Bank transfer',
description: 'Pay by bank transfer within 14 days.',
active: true,
storefront_visible: true,
capture_method: 'manual',
})
- lang: bash
label: Spree CLI
source: spree api post /payment_methods -d '{"type":"check","name":"Bank transfer","description":"Pay
by bank transfer within 14 days.","active":true,"storefront_visible":true,"capture_method":"manual"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: payment method created
content:
application/json:
example:
id: pm_gbHJdmfrXB
name: Bank transfer
description: Pay by bank transfer within 14 days.
type: check
session_required: false
source_required: false
metadata: {}
active: true
capture_method: manual
resolved_capture_method: manual
storefront_visible: true
position: 2
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
preferences: {}
logo_url:
docs_url:
third_party: false
'422':
description: unknown payment method type
content:
application/json:
example:
error:
code: unknown_payment_method_type
message: Unknown type
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PaymentMethodCreateParams"
required: true
"/api/v3/admin/payment_methods/types":
get:
summary: List available payment provider types
tags:
- Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
Returns every registered payment provider with the JSON Schema of its `preferences`. `installed` marks a provider the store already has, which a "Provider" picker leaves out.
**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: types } = await client.paymentMethods.types()
- lang: bash
label: Spree CLI
source: spree api get /payment_methods/types
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: provider types found
content:
application/json:
example:
data:
- type: bogus
label: Bogus
description:
schema:
type: object
properties:
dummy_key:
type: string
default: PUBLICKEY123
dummy_secret_key:
type:
- string
- 'null'
x-spree-secret: true
additionalProperties: false
logo_url:
docs_url:
third_party: true
installed: false
- type: check
label: Check
description:
schema:
type: object
properties: {}
additionalProperties: false
logo_url:
docs_url:
third_party: false
installed: true
- type: custom_payment_source_method
label: Custom Payment Source Method
description:
schema:
type: object
properties: {}
additionalProperties: false
logo_url:
docs_url:
third_party: false
installed: false
- type: store_credit
label: Store Credit
description:
schema:
type: object
properties: {}
additionalProperties: false
logo_url:
docs_url:
third_party: false
installed: true
"/api/v3/admin/payment_methods/{id}":
get:
summary: Show a payment method
tags:
- Payment Methods
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')
- lang: bash
label: Spree CLI
source: spree api get /payment_methods/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand. Use dot notation for
nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., name,type,active).
id is always included.
schema:
type: string
responses:
'200':
description: payment method found
content:
application/json:
example:
id: pm_UkLWZg9DAJ
name: Check 7
description:
type: check
session_required: false
source_required: false
metadata: {}
active: true
capture_method:
resolved_capture_method: checkout
storefront_visible: true
position: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
preferences: {}
logo_url:
docs_url:
third_party: false
patch:
summary: Update a payment method
tags:
- Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
Updates a payment method. Its `type` is fixed once created.
**Required scope:** `write_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.update('pm_UkLWZg9DAJ', {
name: 'Cheque',
storefront_visible: false,
position: 2,
})
- lang: bash
label: Spree CLI
source: spree api patch /payment_methods/{id} -d '{"name":"Cheque","storefront_visible":false,"position":2}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: payment method updated
content:
application/json:
example:
id: pm_UkLWZg9DAJ
name: Cheque
description:
type: check
session_required: false
source_required: false
metadata: {}
active: true
capture_method:
resolved_capture_method: checkout
storefront_visible: false
position: 2
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
preferences: {}
logo_url:
docs_url:
third_party: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PaymentMethodUpdateParams"
required: true
"/api/v3/admin/orders/{order_id}/payments":
get:
summary: List payments
tags:
- Payments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/payments
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 ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., payment_method,
source). Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., amount,status,number,response_code).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[avs_response_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `avs_response` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `cvv_response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `cvv_response_message` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `state` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `status` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `locale`, `market_id`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |
| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
| `payment_method_` | `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at` |
</Accordion>
**Sort by:** `amount`, `avs_response`, `created_at`, `cvv_response_code`, `cvv_response_message`, `id`, `response_code`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Payment
sortable:
- amount
- avs_response
- created_at
- cvv_response_code
- cvv_response_message
- id
- response_code
- state
- status
- updated_at
responses:
'200':
description: payments found
content:
application/json:
example:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code: BGS-343039b69b86
number: R1001-P1
status: completed
amount: '110.00'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
brand: visa
last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/BGS-343039b69b86
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
avs_risky: false
cvv_risky: false
can_void: true
can_capture: false
captured_amount: '0.00'
order_id: or_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create a payment
tags:
- Payments
security:
- api_key: []
bearer_auth: []
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',
})
- lang: bash
label: Spree CLI
source: spree api post /orders/{order_id}/payments -d '{"payment_method_id":"pm_UkLWZg9DAJ","amount":"99.99","source_id":"cc_UkLWZg9DAJ"}'
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 ID
schema:
type: string
responses:
'201':
description: payment created
content:
application/json:
example:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
number: R1002-P1
status: checkout
amount: '110.00'
source_type:
source_id:
source:
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
gateway_dashboard_payment_url:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
avs_risky: false
cvv_risky: false
can_void: true
can_capture: true
captured_amount: '0.00'
order_id: or_gbHJdmfrXB
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PaymentCreateParams"
required: true
"/api/v3/admin/orders/{order_id}/payments/{id}":
get:
summary: Show a payment
tags:
- Payments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api get /orders/{order_id}/payments/{id}
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Payment ID
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., payment_method,
source). Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., amount,status,number,response_code).
id is always included.
schema:
type: string
responses:
'200':
description: payment found
content:
application/json:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code: BGS-4a236d40ef07
number: R1001-P1
status: completed
amount: '110.00'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
brand: visa
last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/BGS-4a236d40ef07
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
avs_risky: false
cvv_risky: false
can_void: true
can_capture: false
captured_amount: '0.00'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
patch:
summary: Capture a payment
tags:
- Payments
security:
- api_key: []
bearer_auth: []
description: |-
Captures a pending payment, in full or for part of the authorized amount.
**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')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...
}'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Payment ID
schema:
type: string
responses:
'200':
description: payment captured
content:
application/json:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code: BGS-ccc19f06b194
number: R1001-P1
status: completed
amount: '110.00'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
brand: visa
last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/BGS-ccc19f06b194
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
avs_risky: false
cvv_risky: false
can_void: true
can_capture: false
captured_amount: '110.00'
order_id: or_UkLWZg9DAJ
'422':
description: capture failed
content:
application/json:
example:
error:
code: processing_error
message: 'Bogus Gateway: Forced failure'
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PaymentCaptureParams"
"/api/v3/admin/orders/{order_id}/payments/{id}/void":
patch:
summary: Void a payment
tags:
- Payments
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api patch /orders/{order_id}/payments/{id}/void -d '{ ... }'
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 ID
schema:
type: string
- name: id
in: path
required: true
description: Payment ID
schema:
type: string
responses:
'200':
description: payment voided
content:
application/json:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code: void-BGS-11f2e975ba0c
number: R1001-P1
status: void
amount: '110.00'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
id: card_UkLWZg9DAJ
brand: visa
last4: '1111'
month: 12
year: 2027
name: Spree Commerce
default: false
gateway_payment_profile_id:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
gateway_dashboard_payment_url: https://dashboard.bogus.example/payments/void-BGS-11f2e975ba0c
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
avs_risky: false
cvv_risky: false
can_void: false
can_capture: false
captured_amount: '0.00'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
get:
summary: List price lists
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Returns the price lists configured 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: priceLists } = await client.priceLists.list()
- lang: bash
label: Spree CLI
source: spree api get /price_lists
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name (partial, case-insensitive).
- name: page
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
schema:
type: string
- name: expand
in: query
required: false
description: 'Comma-separated associations to embed. Supported: `price_rules`.'
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `catalog_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `ends_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `match_policy` | One of `all`, `any` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `status` | One of `draft`, `active`, `inactive`, `scheduled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: PriceList
sortable:
- catalog_id
- created_at
- ends_at
- id
- match_policy
- name
- position
- starts_at
- status
- updated_at
responses:
'200':
description: price lists found
content:
application/json:
example:
data:
- id: pl_UkLWZg9DAJ
name: Wholesale
description:
status: draft
position: 1
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: false
products_count: 0
prices_count: 0
price_adjustment_tiers: []
- id: pl_gbHJdmfrXB
name: Holiday
description:
status: draft
position: 2
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: false
products_count: 0
prices_count: 0
price_adjustment_tiers: []
meta:
page: 1
limit: 25
count: 2
pages: 1
from: 1
to: 2
in: 2
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/PriceList"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a price list
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Creates a new draft price list.
**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',
})
// Server-to-server one-shot create. Ship the rules that gate the list
// and the exact per-variant prices in a single request — variants in
// `prices` implicitly become part of the list (upserted on the unique
// key `(variant_id, currency, price_list_id)`). Curating whole products
// goes through `client.priceLists.products` instead.
const priceList = await client.priceLists.create({
name: 'EU wholesale',
description: 'Tiered pricing for verified B2B customers',
match_policy: 'all',
starts_at: '2026-06-01T00:00:00Z',
ends_at: '2026-09-01T00:00:00Z',
rules: [
{
type: 'customer_group_rule',
preferences: { customer_group_ids: ['cg_aBc123'] },
},
{
type: 'volume_rule',
preferences: { min_quantity: 10 },
},
],
prices: [
{
variant_id: 'variant_xY9',
currency: 'USD',
amount: '19.99',
compare_at_amount: '24.99',
},
{
variant_id: 'variant_aB7',
currency: 'USD',
amount: '21.99',
},
],
})
- lang: bash
label: Spree CLI
source: spree api post /price_lists -d '{"name":"EU wholesale","description":"Tiered
pricing for verified B2B customers","match_policy":"all","starts_at":"2026-06-01T00:00:00Z","ends_at":"2026-09-01T00:00:00Z","rules":[{"type":"customer_group_rule","preferences":{"customer_group_ids":["cg_aBc123"]}},{"type":"volume_rule","preferences":{"min_quantity":10}}],"prices":[{"variant_id":"variant_xY9","currency":"USD","amount":"19.99","compare_at_amount":"24.99"},{"variant_id":"variant_aB7","currency":"USD","amount":"21.99"}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: price list created (server-to-server — rules + prices)
content:
application/json:
example:
id: pl_EfhxLZ9ck8
name: EU wholesale
description:
status: draft
position: 3
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: false
products_count: 1
prices_count: 2
price_adjustment_tiers: []
schema:
"$ref": "#/components/schemas/PriceList"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PriceListCreateParams"
required: true
"/api/v3/admin/price_lists/{id}":
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
summary: Get a price list
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: "**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 priceList = await client.priceLists.get('pl_xxx')
- lang: bash
label: Spree CLI
source: spree api get /price_lists/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: expand
in: query
required: false
schema:
type: string
responses:
'200':
description: price list found
content:
application/json:
example:
id: pl_UkLWZg9DAJ
name: Wholesale
description:
status: draft
position: 1
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: false
products_count: 0
prices_count: 0
price_adjustment_tiers: []
schema:
"$ref": "#/components/schemas/PriceList"
'404':
description: price list not found
content:
application/json:
example:
error:
code: record_not_found
message: Price list not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a price list
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Updates a price list. The optional `rules:` array reconciles nested
STI-typed price rules in a single round-trip — existing rules update
by `id`, new rules build, missing rules destroy. Mirrors the
promotion editor's "save the whole thing on Save" pattern.
**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 priceList = await client.priceLists.update('pl_xxx', {
name: 'Wholesale (Q3)',
})
- lang: bash
label: Spree CLI
source: spree api patch /price_lists/{id} -d '{"name":"Wholesale (Q3)"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: price list updated with nested rules
content:
application/json:
example:
id: pl_UkLWZg9DAJ
name: Wholesale (Q3)
description:
status: draft
position: 1
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: false
products_count: 0
prices_count: 0
price_adjustment_tiers: []
schema:
"$ref": "#/components/schemas/PriceList"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PriceListUpdateParams"
required: true
delete:
summary: Delete a price list
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Soft-deletes the price list. Associated prices are removed asynchronously.
**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.priceLists.delete('pl_xxx')
- lang: bash
label: Spree CLI
source: spree api delete /price_lists/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: price list deleted
"/api/v3/admin/price_lists/{id}/activate":
parameters:
- name: id
in: path
required: true
schema:
type: string
patch:
summary: Activate a price list
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Transitions a draft / inactive list to `active`. If `starts_at` is
in the future the list is marked `scheduled` instead, matching the
legacy admin behaviour.
**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 priceList = await client.priceLists.activate('pl_xxx')
- lang: bash
label: Spree CLI
source: spree api patch /price_lists/{id}/activate -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: price list activated
content:
application/json:
example:
id: pl_UkLWZg9DAJ
name: Wholesale
description:
status: active
position: 1
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: true
products_count: 0
prices_count: 0
price_adjustment_tiers: []
schema:
"$ref": "#/components/schemas/PriceList"
"/api/v3/admin/price_lists/{id}/deactivate":
parameters:
- name: id
in: path
required: true
schema:
type: string
patch:
summary: Deactivate a price list
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: "**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 priceList = await client.priceLists.deactivate('pl_xxx')
- lang: bash
label: Spree CLI
source: spree api patch /price_lists/{id}/deactivate -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: price list deactivated
content:
application/json:
example:
id: pl_UkLWZg9DAJ
name: Price List 2
description:
status: inactive
position: 1
match_policy: all
adjust_compare_at: false
starts_at:
ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
price_adjustment_percentage:
automatic_pricing: false
currently_active: false
products_count: 0
prices_count: 0
price_adjustment_tiers: []
schema:
"$ref": "#/components/schemas/PriceList"
"/api/v3/admin/prices":
get:
summary: List prices
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Generic prices endpoint covering both base prices and price-list
overrides. Filter with Ransack: `q[price_list_id_eq]=…`,
`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).
The admin spreadsheet uses this with server-side pagination so it
scales past the metadata-PATCH path on `/price_lists/: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 { data: prices } = await client.prices.list({
price_list_id_eq: 'pl_xxx',
currency_eq: 'USD',
expand: ['variant'],
})
- lang: bash
label: Spree CLI
source: spree api get /prices -d '{"price_list_id_eq":"pl_xxx","currency_eq":"USD","expand":["variant"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: q[search]
in: query
required: false
schema:
type: string
description: Matches the variant's SKU, option value or product name, as variant
search does.
- name: page
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.
schema:
type: string
- name: expand
in: query
required: false
description: 'Comma-separated associations to embed. Supported: `variant`.'
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[amount_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `compare_at_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `currency` | One of the `CurrencyCode` codes | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `min_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `price_list_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[price_list_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |
| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
</Accordion>
**Sort by:** `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Price
sortable:
- amount
- compare_at_amount
- created_at
- currency
- id
- min_quantity
- price_list_id
- updated_at
- variant_id
responses:
'200':
description: prices found
content:
application/json:
example:
data:
- id: price_UkLWZg9DAJ
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_UkLWZg9DAJ
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- id: price_EfhxLZ9ck8
currency: USD
amount: '5.00'
compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 3
pages: 1
from: 1
to: 3
in: 3
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Price"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a price
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Creates a single price. Omit `price_list_id` to create a base price.
For more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.
**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 price = await client.prices.create({
variant_id: 'variant_xxx',
currency: 'USD',
amount: '19.99',
})
- lang: bash
label: Spree CLI
source: spree api post /prices -d '{"variant_id":"variant_xxx","currency":"USD","amount":"19.99"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: price created
content:
application/json:
example:
id: price_uw2YK1rnl0
currency: EUR
amount: '9.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_EfhxLZ9ck8
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PriceCreateParams"
required: true
"/api/v3/admin/prices/{id}":
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
summary: Get a price
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: "**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 price = await client.prices.get('price_xxx')
- lang: bash
label: Spree CLI
source: spree api get /prices/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: price found
content:
application/json:
example:
id: price_EfhxLZ9ck8
currency: USD
amount: '5.00'
compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
description: price not found
content:
application/json:
example:
error:
code: record_not_found
message: Price not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a price
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: "**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 price = await client.prices.update('price_xxx', {
amount: '12.34',
})
- lang: bash
label: Spree CLI
source: spree api patch /prices/{id} -d '{"amount":"12.34"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: price updated
content:
application/json:
example:
id: price_EfhxLZ9ck8
currency: USD
amount: '12.34'
compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PriceUpdateParams"
required: true
delete:
summary: Delete a price
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Soft-deletes the price (acts_as_paranoid).
**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.prices.delete('price_xxx')
- lang: bash
label: Spree CLI
source: spree api delete /prices/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'204':
description: price deleted
"/api/v3/admin/prices/bulk_upsert":
post:
summary: Bulk-upsert prices
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Upserts a batch of prices in a single SQL round trip.
Each row either:
* targets an existing price by `id`, OR
* matches on the unique key `(variant_id, currency, price_list_id)` —
updating the existing row if one exists, creating one otherwise.
Model callbacks (e.g. PriceHistory) are bypassed; this is a
bulk-write fast path for the admin spreadsheet. The response
carries `price_count` — the number of rows touched.
**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 { price_count } = await client.prices.bulkUpsert({
prices: [
{
variant_id: 'variant_xxx',
currency: 'USD',
price_list_id: 'pl_xxx',
amount: '11.11',
},
{
variant_id: 'variant_yyy',
currency: 'USD',
price_list_id: 'pl_xxx',
amount: '22.22',
},
],
})
- lang: bash
label: Spree CLI
source: spree api post /prices/bulk_upsert -d '{"prices":[{"variant_id":"variant_xxx","currency":"USD","price_list_id":"pl_xxx","amount":"11.11"},{"variant_id":"variant_yyy","currency":"USD","price_list_id":"pl_xxx","amount":"22.22"}]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: prices upserted
content:
application/json:
example:
price_count: 2
schema:
type: object
properties:
price_count:
type: integer
'422':
description: missing prices key
content:
application/json:
example:
error:
code: missing_prices
message: prices is required (send an empty array to no-op).
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PriceBulkUpsertParams"
required: true
"/api/v3/admin/prices/bulk_destroy":
delete:
x-spree-agent: false
x-spree-agent-reason: Deletes many prices in one call behind a single confirmation;
delete_resource removes them one at a time.
summary: Bulk-delete prices
tags:
- Pricing
security:
- api_key: []
bearer_auth: []
description: |-
Soft-deletes each price in `ids`. Returns the count actually destroyed.
**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 { price_count } = await client.prices.bulkDestroy({
ids: ['price_xxx', 'price_yyy'],
})
- lang: bash
label: Spree CLI
source: spree api delete /prices/bulk_destroy -d '{"ids":["price_xxx","price_yyy"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: prices deleted
content:
application/json:
example:
price_count: 1
schema:
type: object
properties:
price_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PriceBulkDestroyParams"
required: true
"/api/v3/admin/products/{product_id}/custom_fields":
get:
summary: List product custom fields
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Returns the product's custom field 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 { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /products/{product_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: product_id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: custom fields found
content:
application/json:
example:
data:
- id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
post:
summary: Create a product custom field
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.
**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 customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
custom_field_definition_id: 'cfdef_AbC123XyZ',
value: 'wool',
})
- lang: bash
label: Spree CLI
source: spree api post /products/{product_id}/custom_fields -d '{"custom_field_definition_id":"cfdef_AbC123XyZ","value":"wool"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: product_id
in: path
required: true
schema:
type: string
responses:
'201':
description: custom field created
content:
application/json:
example:
id: cf_gbHJdmfrXB
label: Description
field_type: long_text
key: custom.description
value: A longer description
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
description: duplicate definition for the same product
content:
application/json:
example:
error:
code: validation_error
message: Custom field definition has already been taken
details:
custom_field_definition_id:
- value: 1
code: taken
message: has already been taken
specific: false
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomFieldCreateParams"
required: true
"/api/v3/admin/products/{product_id}/custom_fields/{id}":
get:
summary: Show a product custom field
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: "**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 customField = await client.products.customFields.get('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
- lang: bash
label: Spree CLI
source: spree api get /products/{product_id}/custom_fields/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: product_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., custom_field_definition).
Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., key,value,namespace).
id is always included.
schema:
type: string
responses:
'200':
description: custom field found
content:
application/json:
example:
id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
summary: Update a product custom field
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.
**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 customField = await client.products.customFields.update('prod_UkLWZg9DAJ', 'cf_AbC123XyZ', {
value: 'cotton',
})
- lang: bash
label: Spree CLI
source: spree api patch /products/{product_id}/custom_fields/{id} -d '{"value":"cotton"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: product_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: custom field updated
content:
application/json:
example:
id: cf_UkLWZg9DAJ
label: Title
field_type: short_text
key: custom.title
value: cotton
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CustomFieldUpdateParams"
required: true
delete:
summary: Delete a product custom field
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: "**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.customFields.delete('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
- lang: bash
label: Spree CLI
source: spree api delete /products/{product_id}/custom_fields/{id}
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: product_id
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: custom field deleted
"/api/v3/admin/products/{product_id}/digital_assets":
parameters:
- name: product_id
in: path
required: true
description: Product ID
schema:
type: string
get:
summary: List product digital assets
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Returns the downloadable files attached to the product's variants, oldest first.
**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: digitalAssets } = await client.products.digitalAssets.list('prod_86Rf07xd4z')
- lang: bash
label: Spree CLI
source: spree api get /products/{product_id}/digital_assets
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: DigitalAsset
sortable:
- created_at
- id
- updated_at
responses:
'200':
description: digital assets found
content:
application/json:
example:
data:
- id: dig_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
filename: thinking-cat.jpg
content_type: image/jpeg
authorized_clicks:
authorized_days:
byte_size: 18090
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
provider_type:
provider_name: File
download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJ0Z252N2l0MG55YnkwbHhkczg5Y2hteTd6aXlvIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--06a160c64f398ed4eb70327ef6932eaf662f98d7/thinking-cat.jpg
effective_authorized_clicks: 5
effective_authorized_days: 7
provider_settings: {}
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/DigitalAsset"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
summary: Create a product digital asset
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Attaches a downloadable file to one of the product's variants (the
default variant when `variant_id` is omitted). Upload the file first
through `POST /api/v3/admin/files` with `visibility: 'private'`, then
send its `signed_id` here. A provider-backed asset sends
`provider_type` and `provider_settings` instead of a file.
**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',
})
// `signed_id` comes from `files.upload()` with `visibility: 'private'`.
const digitalAsset = await client.products.digitalAssets.create('prod_86Rf07xd4z', {
signed_id: 'eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0=--abc123',
authorized_clicks: 5,
authorized_days: 30,
})
- lang: bash
label: Spree CLI
source: spree api post /products/{product_id}/digital_assets -d '{"signed_id":"eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0=--abc123","authorized_clicks":5,"authorized_days":30}'
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
responses:
'201':
description: digital asset created
content:
application/json:
example:
id: dig_gbHJdmfrXB
variant_id: variant_UkLWZg9DAJ
filename: manual.pdf
content_type: image/jpeg
authorized_clicks: 5
authorized_days: 30
byte_size: 18090
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
provider_type:
provider_name: File
download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJhOXR0cGNpbmxxbThvbmtlNHM1NmI2Y3gxMWVzIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cIm1hbnVhbC5wZGZcIjsgZmlsZW5hbWUqPVVURi04JydtYW51YWwucGRmIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--0df5c2167c42cdda6a5f6639d3ddc1b4473c5a81/manual.pdf
effective_authorized_clicks: 5
effective_authorized_days: 30
provider_settings: {}
schema:
"$ref": "#/components/schemas/DigitalAsset"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/DigitalAssetCreateParams"
required: true
"/api/v3/admin/products/{product_id}/digital_assets/{id}":
parameters:
- name: product_id
in: path
required: true
description: Product ID
schema:
type: string
- name: id
in: path
required: true
description: Digital asset ID
schema:
type: string
patch:
summary: Update a product digital asset
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Changes an asset's download limits, or replaces its file with a new
private `signed_id`. Links customers already received keep working and
serve the new file.
**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',
})
// `null` falls back to the store's download settings.
const digitalAsset = await client.products.digitalAssets.update(
'prod_86Rf07xd4z',
'dig_k5nR8xLqPz',
{ authorized_clicks: 10, authorized_days: null },
)
- lang: bash
label: Spree CLI
source: spree api patch /products/{product_id}/digital_assets/{id} -d '{"authorized_clicks":10,"authorized_days":null}'
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
responses:
'200':
description: digital asset updated
content:
application/json:
example:
id: dig_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
filename: thinking-cat.jpg
content_type: image/jpeg
authorized_clicks: 10
authorized_days:
byte_size: 18090
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
provider_type:
provider_name: File
download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiIwZXp6d3IzMzE3ajRoem9kc3Awc2czN3EzMnhzIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--da799713969a4775b10b6055f685e92f410f5176/thinking-cat.jpg
effective_authorized_clicks: 10
effective_authorized_days: 7
provider_settings: {}
schema:
"$ref": "#/components/schemas/DigitalAsset"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/DigitalAssetUpdateParams"
required: true
"/api/v3/admin/products/{product_id}/translations":
get:
summary: List product translations
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.
**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',
})
// Source values and every locale's translations, including the product's variants and options.
const translations = await client.products.translations.get('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /products/{product_id}/translations
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: product_id
in: path
required: true
schema:
type: string
responses:
'200':
description: translations found
content:
application/json:
example:
data:
resource_id: prod_UkLWZg9DAJ
resource_type: product
translations:
de:
name: Espressomaschine
description:
slug: espressomaschine
meta_description:
meta_title:
translated_field_count: 2
fr:
name:
description:
slug:
meta_description:
meta_title:
translated_field_count: 0
fields:
- key: name
type: string
source: Espresso Machine
- key: description
type: html
source: |-
Atque esse occaecati recusandae quam sit blanditiis accusamus. Et temporibus optio quos est esse nobis odit nihil. Magnam quo illum voluptas dolorum quidem. Modi rerum labore praesentium laborum veritatis iusto.
Tempora exercitationem sed vero itaque nihil odio distinctio explicabo. Corporis nesciunt minus veritatis beatae quaerat facilis similique eius. Esse dolores suscipit iusto totam velit ipsa.
Aut saepe quibusdam mollitia amet. Eius beatae facilis asperiores maiores. Fuga doloremque provident perspiciatis natus a quaerat reprehenderit occaecati. Eius deserunt commodi placeat delectus.
Consequatur quas ipsum voluptas quis. Vel cumque molestiae magnam optio. Recusandae eum cum sequi autem fugiat animi tenetur.
- key: slug
type: string
source: espresso-machine
- key: meta_description
type: string
source:
- key: meta_title
type: string
source:
default_locale: en
supported_locales:
- de
- en
- fr
"/api/v3/admin/products":
get:
summary: List products
tags:
- Products
security:
- api_key: []
bearer_auth: []
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({
search: 'shirt',
status_eq: 'active',
sort: '-created_at',
limit: 25,
})
- lang: bash
label: Spree CLI
source: spree api get /products -d '{"search":"shirt","status_eq":"active","sort":"-created_at","limit":25}'
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: q[search]
in: query
required: false
schema:
type: string
description: Matches product name or variant SKU (partial, case-insensitive),
and the store's searchable custom fields.
- name: q[ascend_by_price]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `ascend_by_price`.
- name: q[descend_by_price]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `descend_by_price`.
- name: q[in_categories][]
in: query
required: false
schema:
type: array
items:
type: string
description: Applies `in_categories` to the given value.
- name: q[in_category]
in: query
required: false
schema:
type: string
description: Applies `in_category` to the given value.
- name: q[in_collection]
in: query
required: false
schema:
type: string
description: Applies `in_collection` to the given value.
- name: q[in_stock]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `in_stock`.
- name: q[in_taxon]
in: query
required: false
schema:
type: string
description: Applies `in_taxon` to the given value.
- name: q[not_discontinued]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `not_discontinued`.
- name: q[out_of_stock]
in: query
required: false
schema:
type: boolean
description: Set to `true` to apply `out_of_stock`.
- name: q[price_between][]
in: query
required: false
schema:
type: array
items:
type: number
minItems: 2
maxItems: 2
description: Applies `price_between` to the given value.
- name: q[price_gte]
in: query
required: false
schema:
type: number
description: Applies `price_gte` to the given value.
- name: q[price_lte]
in: query
required: false
schema:
type: number
description: Applies `price_lte` to the given value.
- name: q[search_by_name]
in: query
required: false
schema:
type: string
description: Applies `search_by_name` to the given value.
- name: q[with_option_value_ids][]
in: query
required: false
schema:
type: array
items:
type: string
description: Applies `with_option_value_ids` to the given value.
- 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
- name: sort
in: query
required: false
description: Sort field (e.g., name, -name, price, -price, best_selling)
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., variants, media,
option_types, categories). Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., name,slug,price,status).
id is always included.
schema:
type: string
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
| `labels_` | `created_at`, `id`, `name`, `updated_at` |
| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
| `product_type_` | `created_at`, `id`, `name`, `updated_at` |
| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `store_` | `created_at`, `id`, `name`, `updated_at` |
| `tags_` | `created_at`, `id`, `name`, `updated_at` |
| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |
| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
</Accordion>
Also filters and sorts on the store's searchable custom fields, as `q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.
**Sort by:** `available_on`, `best_selling`, `created_at`, `description`, `discontinue_on`, `id`, `manual`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Product
sortable:
- available_on
- best_selling
- created_at
- description
- discontinue_on
- id
- manual
- name
- price
- seller_id
- slug
- status
- updated_at
custom_fields: true
responses:
'200':
description: products found
content:
application/json:
example:
data:
- id: prod_UkLWZg9DAJ
name: Product 1296550
slug: product-1296550
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: true
description: Saepe quas nemo facilis nam. Voluptatem facere nam
impedit sunt minus possimus totam ullam. Pariatur ullam sed tenetur
quibusdam deleniti.
description_html: Saepe quas nemo facilis nam. Voluptatem facere
nam impedit sunt minus possimus totam ullam. Pariatur ullam sed
tenetur quibusdam deleniti.
default_variant_id: variant_UkLWZg9DAJ
buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
id: price_UkLWZg9DAJ
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_UkLWZg9DAJ
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: active
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Product"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a product
tags:
- Products
security:
- api_key: []
bearer_auth: []
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',
// Rich text: send HTML. Reads return this as plain text, plus
// `description_html` with the markup.
description: '<p>Soft, organic cotton.</p>',
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_levels: [{ 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_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 30 }],
},
],
})
- lang: bash
label: Spree CLI
source: spree api post /products -d '{"name":"Premium T-Shirt","description":"<p>Soft,
organic cotton.</p>","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_levels":[{"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_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":30}]}]}'
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
responses:
'201':
description: product created
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: New Product
slug: new-product
meta_title:
meta_description:
meta_keywords:
variant_count: 0
available_on:
preorder_ships_at:
purchasable: false
preorder: false
in_stock: false
backorderable: false
available: false
description:
description_html:
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
original_price:
seller_id:
external_references: {}
status: draft
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id:
schema:
"$ref": "#/components/schemas/Product"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductCreateParams"
required: true
"/api/v3/admin/products/{id}":
get:
summary: Get a product
tags:
- Products
security:
- api_key: []
bearer_auth: []
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'],
})
- lang: bash
label: Spree CLI
source: spree api get /products/{id} -d '{"expand":["variants","option_types"]}'
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: id
in: path
required: true
description: Product ID (e.g., prod_xxx)
schema:
type: string
- name: expand
in: query
required: false
description: Comma-separated associations to expand (e.g., variants, media,
option_types, categories). Use dot notation for nested expand (max 4 levels).
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to include (e.g., name,slug,price,status).
id is always included.
schema:
type: string
responses:
'200':
description: product found
content:
application/json:
example:
id: prod_UkLWZg9DAJ
name: Product 1332061
slug: product-1332061
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: true
description: Illo error explicabo cupiditate consequatur. Et expedita
velit laborum iure. Harum sit eaque nam ipsam maiores.
description_html: Illo error explicabo cupiditate consequatur. Et
expedita velit laborum iure. Harum sit eaque nam ipsam maiores.
default_variant_id: variant_UkLWZg9DAJ
buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
id: price_UkLWZg9DAJ
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_UkLWZg9DAJ
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: active
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
'404':
description: product not found
content:
application/json:
example:
error:
code: record_not_found
message: Product not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a product
tags:
- Products
security:
- api_key: []
bearer_auth: []
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'],
})
- lang: bash
label: Spree CLI
source: spree api patch /products/{id} -d '{"name":"Updated Name","status":"active","tags":["eco","sale"]}'
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: id
in: path
required: true
description: Product ID
schema:
type: string
responses:
'200':
description: product updated
content:
application/json:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
slug: product-1355339
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: true
description: Laborum nostrum nemo fugit temporibus consectetur omnis.
Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias
at perspiciatis laborum similique. Fugit adipisci iure porro architecto
odit. Alias enim quis rem reprehenderit temporibus. Hic quae rem
aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam
est tempore doloribus cumque inventore vero laborum minus. Reiciendis
autem quia eligendi possimus beatae enim. Impedit nemo quae odit
dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae.
Corporis ipsa alias tempora accusantium. Adipisci sapiente illum
id voluptatum aut illo tempora.
description_html: |-
Laborum nostrum nemo fugit temporibus consectetur omnis. Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias at perspiciatis laborum similique. Fugit adipisci iure porro architecto odit.
Alias enim quis rem reprehenderit temporibus. Hic quae rem aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam est tempore doloribus cumque inventore vero laborum minus. Reiciendis autem quia eligendi possimus beatae enim.
Impedit nemo quae odit dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae. Corporis ipsa alias tempora accusantium. Adipisci sapiente illum id voluptatum aut illo tempora.
default_variant_id: variant_UkLWZg9DAJ
buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
id: price_UkLWZg9DAJ
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_UkLWZg9DAJ
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: active
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductUpdateParams"
required: true
delete:
summary: Delete a product
tags:
- Products
security:
- api_key: []
bearer_auth: []
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')
- lang: bash
label: Spree CLI
source: spree api delete /products/{id}
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: id
in: path
required: true
description: Product ID
schema:
type: string
responses:
'204':
description: product deleted
'422':
description: deletion refused by a store rule
content:
application/json:
example:
error:
code: validation_error
message: This product is under an active supplier contract.
details:
base:
- code: under_contract
message: This product is under an active supplier contract.
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/products/{id}/clone":
parameters:
- name: id
in: path
required: true
description: Product ID
schema:
type: string
post:
summary: Clone a product
tags:
- Products
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 copy = await client.products.clone('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api post /products/{id}/clone -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Creates a draft copy of a product, named "COPY OF …", with its variants,
prices, stock locations, images, categories, channels and tags; stock on
hand starts at zero. Use it to start a similar product from an existing
one instead of building it from scratch.
**Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'201':
description: product cloned
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: COPY OF Product 1462357
slug: copy-of-product-1462357
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: false
description: Dolore facere hic laboriosam sapiente nobis. Doloribus
deleniti quasi esse aliquid voluptatem. Rem voluptate omnis suscipit
adipisci laudantium. Deleniti error dolorum ratione dolor assumenda
iusto. Laborum non rem sapiente temporibus quam inventore. Voluptatum
magnam hic molestias laudantium necessitatibus. Totam ducimus provident
aliquam repellendus nam maxime error natus. Ex aspernatur nostrum
deserunt maxime quis occaecati expedita dolore. Debitis est laboriosam
modi aspernatur cumque. Sapiente ab corrupti quos doloremque eius.
Laborum officiis culpa voluptate fuga sed. Nemo possimus vel architecto
quo modi. Velit aut non iusto exercitationem nostrum nemo. Velit
illo nisi quaerat perspiciatis facilis temporibus quae esse.
description_html: |-
Dolore facere hic laboriosam sapiente nobis. Doloribus deleniti quasi esse aliquid voluptatem. Rem voluptate omnis suscipit adipisci laudantium.
Deleniti error dolorum ratione dolor assumenda iusto. Laborum non rem sapiente temporibus quam inventore. Voluptatum magnam hic molestias laudantium necessitatibus. Totam ducimus provident aliquam repellendus nam maxime error natus.
Ex aspernatur nostrum deserunt maxime quis occaecati expedita dolore. Debitis est laboriosam modi aspernatur cumque. Sapiente ab corrupti quos doloremque eius.
Laborum officiis culpa voluptate fuga sed. Nemo possimus vel architecto quo modi. Velit aut non iusto exercitationem nostrum nemo. Velit illo nisi quaerat perspiciatis facilis temporibus quae esse.
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: draft
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
"/api/v3/admin/products/bulk_status_update":
post:
x-spree-agent: false
x-spree-agent-reason: Writes the status column for many products at once, skipping
the status workflows and their events; products_activate, products_archive and
products_draft run them.
summary: Bulk-update product status
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Sets `status` on each product in `ids`. Reindexes the affected products
for search. Cross-store IDs are silently dropped. Returns counts.
**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 result = await client.products.bulkStatusUpdate({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
status: 'archived',
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_status_update -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"status":"archived"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: cross-store products silently dropped
content:
application/json:
example:
product_count: 0
status: archived
schema:
type: object
properties:
product_count:
type: integer
status:
type: string
'422':
description: invalid status
content:
application/json:
example:
error:
code: invalid_status
message: Invalid status
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkStatusParams"
required: true
"/api/v3/admin/products/bulk_add_to_categories":
post:
summary: Bulk-add products to categories
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Attaches each product in `ids` to every category (category) in `category_ids`.
Categories from sibling stores are silently ignored.
**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 result = await client.products.bulkAddToCategories({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
category_ids: ['cat_AbC123XyZ'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_add_to_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products added to categories
content:
application/json:
example:
product_count: 1
category_count: 1
schema:
type: object
properties:
product_count:
type: integer
category_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkCategoriesParams"
required: true
"/api/v3/admin/products/bulk_remove_from_categories":
post:
summary: Bulk-remove products from categories
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Detaches each product in `ids` from every category in `category_ids`.
**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 result = await client.products.bulkRemoveFromCategories({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
category_ids: ['cat_AbC123XyZ'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_remove_from_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products removed from categories
content:
application/json:
example:
product_count: 1
category_count: 1
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkCategoriesParams"
required: true
"/api/v3/admin/products/bulk_add_to_collections":
post:
summary: Bulk-add products to collections
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Attaches each product in `ids` to every manual collection in `collection_ids`.
Automatic (rule-based) and sibling-store collections are silently ignored.
**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 result = await client.products.bulkAddToCollections({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
collection_ids: ['coll_AbC123XyZq'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_add_to_collections -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"collection_ids":["coll_AbC123XyZq"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products added to collections
content:
application/json:
example:
product_count: 1
collection_count: 1
schema:
type: object
properties:
product_count:
type: integer
collection_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkCollectionsParams"
required: true
"/api/v3/admin/products/bulk_remove_from_collections":
post:
summary: Bulk-remove products from collections
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Detaches each product in `ids` from every collection in `collection_ids`.
**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 result = await client.products.bulkRemoveFromCollections({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
collection_ids: ['coll_AbC123XyZq'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_remove_from_collections -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"collection_ids":["coll_AbC123XyZq"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products removed from collections
content:
application/json:
example:
product_count: 1
collection_count: 1
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkCollectionsParams"
required: true
"/api/v3/admin/products/bulk_add_to_channels":
post:
summary: Bulk-add products to channels
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —
re-publishing on an existing channel is a no-op. Channels from sibling stores
are silently ignored.
**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 result = await client.products.bulkAddToChannels({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
channel_ids: ['channel_AbC123XyZ'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_add_to_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products published on channels
content:
application/json:
example:
product_count: 1
channel_count: 1
schema:
type: object
properties:
product_count:
type: integer
channel_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkChannelsParams"
required: true
"/api/v3/admin/products/bulk_remove_from_channels":
post:
summary: Bulk-remove products from channels
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Unpublishes each product in `ids` from every channel in `channel_ids`.
**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 result = await client.products.bulkRemoveFromChannels({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
channel_ids: ['channel_AbC123XyZ'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_remove_from_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products unpublished from channels
content:
application/json:
example:
product_count: 1
channel_count: 1
removed: 1
schema:
type: object
properties:
product_count:
type: integer
channel_count:
type: integer
removed:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkChannelsParams"
required: true
"/api/v3/admin/products/bulk_add_tags":
post:
summary: Bulk-add tags to products
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Adds each tag name in `tags` to every product in `ids`. Tags are upserted 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 result = await client.products.bulkAddTags({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
tags: ['summer', 'sale'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_add_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer","sale"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: tags added
content:
application/json:
example:
product_count: 1
tag_count: 2
schema:
type: object
properties:
product_count:
type: integer
tag_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/BulkTagsParams"
required: true
"/api/v3/admin/products/bulk_remove_tags":
post:
summary: Bulk-remove tags from products
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Removes each tag in `tags` from every product in `ids`.
**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 result = await client.products.bulkRemoveTags({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
tags: ['summer'],
})
- lang: bash
label: Spree CLI
source: spree api post /products/bulk_remove_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: tags removed
content:
application/json:
example:
product_count: 1
tag_count: 1
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/BulkTagsParams"
required: true
"/api/v3/admin/products/bulk_destroy":
delete:
x-spree-agent: false
x-spree-agent-reason: Deletes many products in one call behind a single confirmation;
delete_resource removes them one at a time.
summary: Bulk-delete products
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Soft-deletes each product in `ids`. Returns the count actually destroyed.
**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 result = await client.products.bulkDestroy({
ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
})
- lang: bash
label: Spree CLI
source: spree api delete /products/bulk_destroy -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: products deleted
content:
application/json:
example:
product_count: 1
schema:
type: object
properties:
product_count:
type: integer
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductBulkDestroyParams"
required: true
"/api/v3/admin/products/{id}/approve":
parameters:
- name: id
in: path
required: true
description: Product ID
schema:
type: string
patch:
summary: Approve a submitted product
tags:
- Products
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.approve('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /products/{id}/approve -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Puts a product a seller submitted for review on sale, and closes the
submission. Only a product awaiting review can be approved.
**Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: product approved
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: Product 1538682
slug: product-1538682
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: true
description: Eligendi minus placeat hic culpa. Explicabo ea et earum
dolor facilis pariatur dolores recusandae. Placeat ut qui optio
a veritatis. Ipsam ex delectus reiciendis dolorum cupiditate. Consectetur
perferendis blanditiis sunt itaque. Velit odio aliquid hic accusamus
ipsa autem quasi. Repellat deserunt officia nobis aliquid sint iusto
officiis. Repudiandae natus vitae dolore quam accusamus magnam.
Itaque maxime voluptatem cupiditate ratione odit porro sed. Asperiores
aliquid dicta consequuntur eum quo. Deleniti recusandae laborum
cumque mollitia nisi exercitationem dignissimos.
description_html: |-
Eligendi minus placeat hic culpa. Explicabo ea et earum dolor facilis pariatur dolores recusandae. Placeat ut qui optio a veritatis.
Ipsam ex delectus reiciendis dolorum cupiditate. Consectetur perferendis blanditiis sunt itaque. Velit odio aliquid hic accusamus ipsa autem quasi.
Repellat deserunt officia nobis aliquid sint iusto officiis. Repudiandae natus vitae dolore quam accusamus magnam. Itaque maxime voluptatem cupiditate ratione odit porro sed. Asperiores aliquid dicta consequuntur eum quo. Deleniti recusandae laborum cumque mollitia nisi exercitationem dignissimos.
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: active
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
'422':
description: the product is not awaiting review
content:
application/json:
example:
error:
code: processing_error
message: This product is not awaiting review.
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/products/{id}/reject":
parameters:
- name: id
in: path
required: true
description: Product ID
schema:
type: string
patch:
summary: Reject a submitted product
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Turns down a product a seller submitted for review. The `reason` is
sent back to the seller, who can fix the product and submit it again.
**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',
})
// The seller sees the reason, fixes the product and submits it again.
const product = await client.products.reject('prod_86Rf07xd4z', {
reason: 'Photos are too dark',
})
- lang: bash
label: Spree CLI
source: spree api patch /products/{id}/reject -d '{"reason":"Photos are too
dark"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: product rejected
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: Product 1564387
slug: product-1564387
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: false
description: Iste blanditiis quos vero ipsam reprehenderit quae. Culpa
recusandae ut quisquam facilis enim dolorum eius. Sapiente explicabo
animi necessitatibus perspiciatis doloribus aspernatur nobis. Labore
similique ipsa debitis voluptate a. Nemo occaecati magnam quos voluptatibus
amet. Facilis quis aperiam corporis corrupti enim. Voluptate dignissimos
alias exercitationem repudiandae eligendi rerum hic. Facilis sed
doloremque dicta porro saepe. Ipsam alias et ipsum voluptatum aperiam
molestiae aliquam tempora. Quod ipsa quas eos hic corrupti dignissimos
dolorum occaecati. Commodi quis animi at possimus laborum beatae.
Aliquam vero suscipit reiciendis dolor placeat. Deleniti corporis
tempora accusamus quae nesciunt animi. Numquam occaecati sapiente
accusantium amet illum. Vero odio reprehenderit ipsa esse aliquid
autem ad.
description_html: |-
Iste blanditiis quos vero ipsam reprehenderit quae. Culpa recusandae ut quisquam facilis enim dolorum eius. Sapiente explicabo animi necessitatibus perspiciatis doloribus aspernatur nobis. Labore similique ipsa debitis voluptate a.
Nemo occaecati magnam quos voluptatibus amet. Facilis quis aperiam corporis corrupti enim. Voluptate dignissimos alias exercitationem repudiandae eligendi rerum hic.
Facilis sed doloremque dicta porro saepe. Ipsam alias et ipsum voluptatum aperiam molestiae aliquam tempora. Quod ipsa quas eos hic corrupti dignissimos dolorum occaecati. Commodi quis animi at possimus laborum beatae.
Aliquam vero suscipit reiciendis dolor placeat. Deleniti corporis tempora accusamus quae nesciunt animi. Numquam occaecati sapiente accusantium amet illum. Vero odio reprehenderit ipsa esse aliquid autem ad.
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: rejected
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ProductRejectParams"
required: true
"/api/v3/admin/products/{id}/activate":
parameters:
- name: id
in: path
required: true
description: Product ID
schema:
type: string
patch:
summary: Activate a product
tags:
- Products
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.activate('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /products/{id}/activate -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Puts one product on sale. Runs the activation workflow, so its hooks and the `product.activated` event fire, which `bulk_status_update` does not. A product awaiting review is refused: approve or reject it instead.
**Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: product active
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: Product 1604119
slug: product-1604119
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: true
description: Tempora doloribus sit consectetur cumque omnis. Quod
fugit dicta ullam omnis. Hic dolorem asperiores nemo est sed nihil
quia deleniti. Saepe aperiam eos nulla quia porro minima officiis
cum. Eius dignissimos laudantium sequi incidunt. Sed nihil voluptate
aliquid nisi. Veritatis tenetur quos aspernatur modi perspiciatis
quaerat. Voluptas harum neque labore fuga reprehenderit unde quasi.
Omnis quam autem in ipsam aspernatur architecto alias recusandae.
Repudiandae ratione vel expedita corporis et pariatur rem sapiente.
Velit laboriosam nulla quibusdam fugit minus itaque ut repellat.
Incidunt est fugiat totam ipsa quod deserunt. Natus sequi numquam
laudantium non similique saepe ipsam quos. Ad impedit necessitatibus
quo nesciunt blanditiis id similique recusandae. Ut occaecati debitis
aliquam accusantium sed distinctio neque. Labore quos quam optio
aperiam dolores aspernatur vitae odio. Eius nam adipisci corrupti
incidunt quod sapiente tempora dicta.
description_html: |-
Tempora doloribus sit consectetur cumque omnis. Quod fugit dicta ullam omnis. Hic dolorem asperiores nemo est sed nihil quia deleniti.
Saepe aperiam eos nulla quia porro minima officiis cum. Eius dignissimos laudantium sequi incidunt. Sed nihil voluptate aliquid nisi.
Veritatis tenetur quos aspernatur modi perspiciatis quaerat. Voluptas harum neque labore fuga reprehenderit unde quasi. Omnis quam autem in ipsam aspernatur architecto alias recusandae. Repudiandae ratione vel expedita corporis et pariatur rem sapiente.
Velit laboriosam nulla quibusdam fugit minus itaque ut repellat. Incidunt est fugiat totam ipsa quod deserunt. Natus sequi numquam laudantium non similique saepe ipsam quos. Ad impedit necessitatibus quo nesciunt blanditiis id similique recusandae.
Ut occaecati debitis aliquam accusantium sed distinctio neque. Labore quos quam optio aperiam dolores aspernatur vitae odio. Eius nam adipisci corrupti incidunt quod sapiente tempora dicta.
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: active
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
'422':
description: the product is awaiting review
content:
application/json:
example:
error:
code: product_in_review
message: A product awaiting review is approved or rejected, not
moved to another status
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/products/{id}/archive":
parameters:
- name: id
in: path
required: true
description: Product ID
schema:
type: string
patch:
summary: Archive a product
tags:
- Products
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.archive('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /products/{id}/archive -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Takes one product off sale and archives it; activating it puts it back on sale. Runs the archive workflow, so its hooks and its event fire. A product awaiting review is refused: approve or reject it instead.
**Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: product archived
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: Product 1644768
slug: product-1644768
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: false
description: In exercitationem nobis illo accusamus non quibusdam.
Minus corporis commodi magni maxime cumque beatae. Exercitationem
provident tempore est corrupti eius at dolor. Rerum delectus id
aspernatur consequuntur quod enim. Quis omnis amet inventore alias
minima praesentium. Quaerat reprehenderit deleniti atque inventore.
Nemo quas nam qui architecto eligendi vel pariatur. Veritatis accusantium
molestias deleniti omnis autem modi. Officiis optio quidem iste
nihil delectus commodi. Aperiam amet omnis eum praesentium natus
recusandae suscipit.
description_html: |-
In exercitationem nobis illo accusamus non quibusdam. Minus corporis commodi magni maxime cumque beatae. Exercitationem provident tempore est corrupti eius at dolor. Rerum delectus id aspernatur consequuntur quod enim.
Quis omnis amet inventore alias minima praesentium. Quaerat reprehenderit deleniti atque inventore. Nemo quas nam qui architecto eligendi vel pariatur.
Veritatis accusantium molestias deleniti omnis autem modi. Officiis optio quidem iste nihil delectus commodi. Aperiam amet omnis eum praesentium natus recusandae suscipit.
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: archived
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
'422':
description: the product is awaiting review
content:
application/json:
example:
error:
code: product_in_review
message: A product awaiting review is approved or rejected, not
moved to another status
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/products/{id}/draft":
parameters:
- name: id
in: path
required: true
description: Product ID
schema:
type: string
patch:
summary: Move a product back to draft
tags:
- Products
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.draft('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api patch /products/{id}/draft -d '{ ... }'
security:
- api_key: []
bearer_auth: []
description: |-
Takes one product off sale, back to a draft. Runs the draft workflow, so its hooks and its event fire. A product awaiting review is refused: approve or reject it instead.
**Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
responses:
'200':
description: product draft
content:
application/json:
example:
id: prod_gbHJdmfrXB
name: Product 1682527
slug: product-1682527
meta_title:
meta_description:
meta_keywords:
variant_count: 1
available_on:
preorder_ships_at:
purchasable: true
preorder: false
in_stock: false
backorderable: true
available: false
description: Temporibus fugiat ducimus quae voluptas error. Iure repellat
labore aperiam harum magni. Fuga ullam possimus ad repudiandae atque.
Excepturi quidem est expedita molestiae delectus. Optio tempora
sed minus voluptatum doloremque. Laborum esse voluptate nostrum
nesciunt. Ipsum ducimus a dolor nostrum quis corrupti quae illum.
Fuga provident deleniti minima ea vel. Cupiditate architecto omnis
reprehenderit iusto suscipit corrupti quia cumque. Voluptatem nisi
dignissimos aut nostrum distinctio quo explicabo fugiat. Unde minima
ratione enim minus officia rerum odio reiciendis. Fugiat perferendis
nulla voluptates voluptatum alias. Voluptatem cumque voluptatibus
in sint assumenda ad neque. Inventore error consequuntur exercitationem
officia consequatur earum iure autem. Odit iure porro reiciendis
placeat. Animi minus vel asperiores maiores error tempora. Dolorum
esse sapiente voluptatem iste culpa suscipit. Nulla sapiente sit
deserunt iste totam dolores. Tempora magni eveniet natus nemo optio.
Aliquid quis ullam illo minus. Atque distinctio sapiente voluptatibus
adipisci consectetur repellendus culpa dolor. Dolor pariatur tempora
ab repellat unde aliquam sequi. Necessitatibus aliquid fugit molestias
facilis ratione.
description_html: |-
Temporibus fugiat ducimus quae voluptas error. Iure repellat labore aperiam harum magni. Fuga ullam possimus ad repudiandae atque. Excepturi quidem est expedita molestiae delectus. Optio tempora sed minus voluptatum doloremque.
Laborum esse voluptate nostrum nesciunt. Ipsum ducimus a dolor nostrum quis corrupti quae illum. Fuga provident deleniti minima ea vel. Cupiditate architecto omnis reprehenderit iusto suscipit corrupti quia cumque. Voluptatem nisi dignissimos aut nostrum distinctio quo explicabo fugiat.
Unde minima ratione enim minus officia rerum odio reiciendis. Fugiat perferendis nulla voluptates voluptatum alias. Voluptatem cumque voluptatibus in sint assumenda ad neque. Inventore error consequuntur exercitationem officia consequatur earum iure autem.
Odit iure porro reiciendis placeat. Animi minus vel asperiores maiores error tempora. Dolorum esse sapiente voluptatem iste culpa suscipit. Nulla sapiente sit deserunt iste totam dolores.
Tempora magni eveniet natus nemo optio. Aliquid quis ullam illo minus. Atque distinctio sapiente voluptatibus adipisci consectetur repellendus culpa dolor. Dolor pariatur tempora ab repellat unde aliquam sequi. Necessitatibus aliquid fugit molestias facilis ratione.
default_variant_id: variant_gbHJdmfrXB
buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
id: price_gbHJdmfrXB
currency: USD
amount: '19.99'
compare_at_amount:
price_list_id:
min_quantity: 1
variant_id: variant_gbHJdmfrXB
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
original_price:
seller_id:
external_references: {}
status: draft
metadata: {}
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
'422':
description: the product is awaiting review
content:
application/json:
example:
error:
code: product_in_review
message: A product awaiting review is approved or rejected, not
moved to another status
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/translations":
get:
summary: Translation coverage for a resource type
tags:
- Products
security:
- api_key: []
bearer_auth: []
description: |-
Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.
**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',
})
// How much of each product is translated into each of the store's other languages.
const { data: coverage } = await client.translations.coverage('product', {
search: 'espresso',
limit: 25,
})
- lang: bash
label: Spree CLI
source: spree api get /translations -d '{"search":"espresso","limit":25}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: resource_type
in: query
required: true
description: A translatable resource type, e.g. `product`, `category`, `option_type`.
schema:
type: string
- name: page
in: query
required: false
schema:
type: integer
- name: limit
in: query
required: false
schema:
type: integer
- name: search
in: query
required: false
description: Free-text term, applied through whichever predicate the resource
type whitelists (reported back as `search_field`).
schema:
type: string
responses:
'200':
description: coverage found
content:
application/json:
example:
data:
resource_type: product
default_locale: en
locales:
- de
field_count: 5
search_field: name_cont
coverage:
- locale: de
translated: 0
total: 1
coverage: 0.0
records:
- id: prod_UkLWZg9DAJ
label: Espresso Machine
locales:
de: 2
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'404':
description: resource type is not translatable
content:
application/json:
example:
error:
code: record_not_found
message: record not found
"/api/v3/admin/policies":
get:
summary: List policies
tags:
- Policies
security:
- api_key: []
bearer_auth: []
description: |-
Returns the store's policy documents — terms of service, privacy
policy, returns policy, shipping policy, and any others the merchant
has written. Every store is created with the four standard policies,
named but empty.
A marketplace seller's own policies are managed by the seller and are
not listed here.
**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: policies } = await client.policies.list()
- lang: bash
label: Spree CLI
source: spree api get /policies
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: q[search]
in: query
required: false
schema:
type: string
description: Matches any of name (partial, case-insensitive).
- 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `owner_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `owner_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `created_at`, `id`, `name`, `owner_id`, `owner_type`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: Policy
sortable:
- created_at
- id
- name
- owner_id
- owner_type
- updated_at
responses:
'200':
description: policies listed
content:
application/json:
example:
data:
- id: pol_gbHJdmfrXB
name: Privacy Policy
slug: privacy-policy
body: ''
body_html: ''
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
- id: pol_uw2YK1rnl0
name: Restocking Policy
slug: restocking-policy
body: Return anything unopened within 30 days.
body_html: "<p>Return anything unopened within 30 days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
- id: pol_EfhxLZ9ck8
name: Returns Policy
slug: returns-policy
body: ''
body_html: ''
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
- id: pol_VqXmZF31wY
name: Shipping Policy
slug: shipping-policy
body: ''
body_html: ''
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
- id: pol_UkLWZg9DAJ
name: Terms of Service
slug: terms-of-service
body: ''
body_html: ''
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
count: 5
pages: 1
from: 1
to: 5
in: 5
previous:
next:
schema:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/Policy"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a policy
tags:
- Policies
security:
- api_key: []
bearer_auth: []
description: |-
Creates a policy. `body` accepts HTML and is sanitized before it is
stored; the stored markup is returned as `body_html`, and `body` reads
back as plain text.
The slug is derived from the name when one is not given, and is what
the storefront addresses the policy by.
**Required scope:** `write_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 policy = await client.policies.create({
name: 'Wholesale Policy',
body: '<p>Trade orders ship within five working days.</p>',
})
- lang: bash
label: Spree CLI
source: spree api post /policies -d '{"name":"Wholesale Policy","body":"<p>Trade
orders ship within five working days.</p>"}'
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
responses:
'201':
description: policy created
content:
application/json:
example:
id: pol_OIJLhNcSbf
name: Wholesale Policy
slug: wholesale-policy
body: Trade orders ship within five working days.
body_html: "<p>Trade orders ship within five working days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Policy"
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PolicyCreateParams"
required: true
"/api/v3/admin/policies/{id}":
parameters:
- name: id
in: path
required: true
description: Policy prefixed ID or slug
schema:
type: string
get:
summary: Get a policy
tags:
- Policies
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single policy, addressed by prefixed ID or by slug.
**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',
})
// Addressable by slug as well as prefixed id.
const policy = await client.policies.get('returns-policy')
- lang: bash
label: Spree CLI
source: spree api get /policies/{id}
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
responses:
'200':
description: policy found
content:
application/json:
example:
id: pol_uw2YK1rnl0
name: Restocking Policy
slug: restocking-policy
body: Return anything unopened within 30 days.
body_html: "<p>Return anything unopened within 30 days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Policy"
'404':
description: policy not found
content:
application/json:
example:
error:
code: record_not_found
message: Policy not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a policy
tags:
- Policies
security:
- api_key: []
bearer_auth: []
description: |-
Updates a policy. `body` accepts HTML and is sanitized before it is stored.
**Required scope:** `write_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 policy = await client.policies.update('returns-policy', {
body: '<p>Return anything unopened within 60 days.</p>',
})
- lang: bash
label: Spree CLI
source: spree api patch /policies/{id} -d '{"body":"<p>Return anything unopened
within 60 days.</p>"}'
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
responses:
'200':
description: policy updated
content:
application/json:
example:
id: pol_uw2YK1rnl0
name: Restocking Policy
slug: restocking-policy
body: Return anything unopened within 60 days.
body_html: "<p>Return anything unopened within 60 days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
schema:
"$ref": "#/components/schemas/Policy"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/PolicyUpdateParams"
required: true
delete:
summary: Delete a policy
tags:
- Policies
security:
- api_key: []
bearer_auth: []
description: |-
Deletes a policy. The four policies a store is created with can be
deleted like any other — they are conventions, not fixtures.
**Required scope:** `write_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',
})
await client.policies.delete('wholesale-policy')
- lang: bash
label: Spree CLI
source: spree api delete /policies/{id}
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
responses:
'204':
description: policy deleted
"/api/v3/admin/claim_reasons":
get:
summary: List claim reasons
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.
The vocabulary is the merchant's own — seeded with a starting set and
edited from the dashboard. Inactive rows stay for the records that
already reference them, but are not offered on new ones.
**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: reasons } = await client.claimReasons.list()
- lang: bash
label: Spree CLI
source: spree api get /claim_reasons
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: ClaimReason
sortable:
- active
- created_at
- id
- name
- updated_at
responses:
'200':
description: claim reasons found
content:
application/json:
example:
data:
- id: clr_UkLWZg9DAJ
name: Arrived damaged
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a claim reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Adds a claim reason to this store. Names are unique per store, ignoring case.
**Required scope:** `write_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 reason = await client.claimReasons.create({
name: 'Arrived damaged',
})
- lang: bash
label: Spree CLI
source: spree api post /claim_reasons -d '{"name":"Arrived damaged"}'
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
responses:
'201':
description: claim reason created
content:
application/json:
example:
id: clr_gbHJdmfrXB
name: A new reason
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonCreateParams"
required: true
"/api/v3/admin/claim_reasons/{id}":
parameters:
- name: id
in: path
required: true
description: Claim reason ID
schema:
type: string
get:
summary: Get a claim reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single claim reason by prefixed 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 reason = await client.claimReasons.get('clr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /claim_reasons/{id}
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
responses:
'200':
description: claim reason found
content:
application/json:
example:
id: clr_UkLWZg9DAJ
name: Arrived damaged
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'404':
description: claim reason not found
content:
application/json:
example:
error:
code: record_not_found
message: Claim reason not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a claim reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Renames a claim reason or retires it. Deactivating keeps it on the records
that already carry it while removing it from the pickers.
**Required scope:** `write_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 reason = await client.claimReasons.update('clr_UkLWZg9DAJ', {
active: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /claim_reasons/{id} -d '{"active":false}'
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
responses:
'200':
description: claim reason updated
content:
application/json:
example:
id: clr_UkLWZg9DAJ
name: Arrived damaged
active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonUpdateParams"
required: true
delete:
summary: Delete a claim reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Removes a claim reason the store no longer uses. A reason already recorded
on a document is refused — deactivate it instead, so the history it
explains stays readable.
**Required scope:** `write_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',
})
await client.claimReasons.delete('clr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /claim_reasons/{id}
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
responses:
'204':
description: claim reason deleted
"/api/v3/admin/order_cancellation_reasons":
get:
summary: List order cancellation reasons
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Why an order was called off before it shipped. Staff pick one when canceling.
The vocabulary is the merchant's own — seeded with a starting set and
edited from the dashboard. Inactive rows stay for the records that
already reference them, but are not offered on new ones.
**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: reasons } = await client.orderCancellationReasons.list()
- lang: bash
label: Spree CLI
source: spree api get /order_cancellation_reasons
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: OrderCancellationReason
sortable:
- active
- created_at
- id
- name
- updated_at
responses:
'200':
description: order cancellation reasons found
content:
application/json:
example:
data:
- id: ocr_UkLWZg9DAJ
name: Out of stock
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a order cancellation reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Adds a order cancellation reason to this store. Names are unique per store, ignoring case.
**Required scope:** `write_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 reason = await client.orderCancellationReasons.create({
name: 'Out of stock',
})
- lang: bash
label: Spree CLI
source: spree api post /order_cancellation_reasons -d '{"name":"Out of stock"}'
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
responses:
'201':
description: order cancellation reason created
content:
application/json:
example:
id: ocr_gbHJdmfrXB
name: A new reason
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonCreateParams"
required: true
"/api/v3/admin/order_cancellation_reasons/{id}":
parameters:
- name: id
in: path
required: true
description: Order cancellation reason ID
schema:
type: string
get:
summary: Get a order cancellation reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single order cancellation reason by prefixed 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 reason = await client.orderCancellationReasons.get('ocr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /order_cancellation_reasons/{id}
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
responses:
'200':
description: order cancellation reason found
content:
application/json:
example:
id: ocr_UkLWZg9DAJ
name: Out of stock
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'404':
description: order cancellation reason not found
content:
application/json:
example:
error:
code: record_not_found
message: Order cancellation reason not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a order cancellation reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Renames a order cancellation reason or retires it. Deactivating keeps it on the records
that already carry it while removing it from the pickers.
**Required scope:** `write_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 reason = await client.orderCancellationReasons.update('ocr_UkLWZg9DAJ', {
active: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /order_cancellation_reasons/{id} -d '{"active":false}'
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
responses:
'200':
description: order cancellation reason updated
content:
application/json:
example:
id: ocr_UkLWZg9DAJ
name: Out of stock
active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonUpdateParams"
required: true
delete:
summary: Delete a order cancellation reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Removes a order cancellation reason the store no longer uses. A reason already recorded
on a document is refused — deactivate it instead, so the history it
explains stays readable.
**Required scope:** `write_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',
})
await client.orderCancellationReasons.delete('ocr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /order_cancellation_reasons/{id}
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
responses:
'204':
description: order cancellation reason deleted
"/api/v3/admin/refund_reasons":
get:
summary: List refund reasons
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.
The vocabulary is the merchant's own — seeded with a starting set and
edited from the dashboard. Inactive rows stay for the records that
already reference them, but are not offered on new ones.
**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: reasons } = await client.refundReasons.list()
- lang: bash
label: Spree CLI
source: spree api get /refund_reasons
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: RefundReason
sortable:
- active
- created_at
- id
- name
- updated_at
responses:
'200':
description: refund reasons found
content:
application/json:
example:
data:
- id: rr_UkLWZg9DAJ
name: Goodwill gesture
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a refund reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Adds a refund reason to this store. Names are unique per store, ignoring case.
**Required scope:** `write_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 reason = await client.refundReasons.create({
name: 'Goodwill gesture',
})
- lang: bash
label: Spree CLI
source: spree api post /refund_reasons -d '{"name":"Goodwill gesture"}'
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
responses:
'201':
description: refund reason created
content:
application/json:
example:
id: rr_gbHJdmfrXB
name: A new reason
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonCreateParams"
required: true
"/api/v3/admin/refund_reasons/{id}":
parameters:
- name: id
in: path
required: true
description: Refund reason ID
schema:
type: string
get:
summary: Get a refund reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single refund reason by prefixed 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 reason = await client.refundReasons.get('rr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /refund_reasons/{id}
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
responses:
'200':
description: refund reason found
content:
application/json:
example:
id: rr_UkLWZg9DAJ
name: Goodwill gesture
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'404':
description: refund reason not found
content:
application/json:
example:
error:
code: record_not_found
message: Refund reason not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a refund reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Renames a refund reason or retires it. Deactivating keeps it on the records
that already carry it while removing it from the pickers.
**Required scope:** `write_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 reason = await client.refundReasons.update('rr_UkLWZg9DAJ', {
active: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /refund_reasons/{id} -d '{"active":false}'
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
responses:
'200':
description: refund reason updated
content:
application/json:
example:
id: rr_UkLWZg9DAJ
name: Goodwill gesture
active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonUpdateParams"
required: true
delete:
summary: Delete a refund reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Removes a refund reason the store no longer uses. A reason already recorded
on a document is refused — deactivate it instead, so the history it
explains stays readable.
**Required scope:** `write_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',
})
await client.refundReasons.delete('rr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /refund_reasons/{id}
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
responses:
'204':
description: refund reason deleted
"/api/v3/admin/return_reasons":
get:
summary: List return reasons
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Why a customer is sending items back. Shared by returns and exchanges.
The vocabulary is the merchant's own — seeded with a starting set and
edited from the dashboard. Inactive rows stay for the records that
already reference them, but are not offered on new ones.
**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: reasons } = await client.returnReasons.list()
- lang: bash
label: Spree CLI
source: spree api get /return_reasons
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: ReturnReason
sortable:
- active
- created_at
- id
- name
- updated_at
responses:
'200':
description: return reasons found
content:
application/json:
example:
data:
- id: rar_UkLWZg9DAJ
name: Damaged in transit
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a return reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Adds a return reason to this store. Names are unique per store, ignoring case.
**Required scope:** `write_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 reason = await client.returnReasons.create({
name: 'Damaged in transit',
})
- lang: bash
label: Spree CLI
source: spree api post /return_reasons -d '{"name":"Damaged in transit"}'
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
responses:
'201':
description: return reason created
content:
application/json:
example:
id: rar_gbHJdmfrXB
name: A new reason
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonCreateParams"
required: true
"/api/v3/admin/return_reasons/{id}":
parameters:
- name: id
in: path
required: true
description: Return reason ID
schema:
type: string
get:
summary: Get a return reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single return reason by prefixed 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 reason = await client.returnReasons.get('rar_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /return_reasons/{id}
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
responses:
'200':
description: return reason found
content:
application/json:
example:
id: rar_UkLWZg9DAJ
name: Damaged in transit
active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'404':
description: return reason not found
content:
application/json:
example:
error:
code: record_not_found
message: Return reason not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a return reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Renames a return reason or retires it. Deactivating keeps it on the records
that already carry it while removing it from the pickers.
**Required scope:** `write_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 reason = await client.returnReasons.update('rar_UkLWZg9DAJ', {
active: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /return_reasons/{id} -d '{"active":false}'
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
responses:
'200':
description: return reason updated
content:
application/json:
example:
id: rar_UkLWZg9DAJ
name: Damaged in transit
active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/ReasonUpdateParams"
required: true
delete:
summary: Delete a return reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Removes a return reason the store no longer uses. A reason already recorded
on a document is refused — deactivate it instead, so the history it
explains stays readable.
**Required scope:** `write_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',
})
await client.returnReasons.delete('rar_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api delete /return_reasons/{id}
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
responses:
'204':
description: return reason deleted
"/api/v3/admin/tax_exemption_reasons":
get:
summary: List tax exemption reasons
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Why a business buys without tax — the reasons a merchant can record on a
tax exemption certificate. Each has the merchant's own `name` and a `code`,
which certificates record and the tax provider receives.
The vocabulary is the merchant's own — seeded with a starting set and
edited from the dashboard. A provider whose engine reads the code lists
the codes it understands on `GET /tax_providers`. Inactive rows stay on the
certificates that already record them, but are not offered on new ones.
**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: reasons } = await client.taxExemptionReasons.list()
- lang: bash
label: Spree CLI
source: spree api get /tax_exemption_reasons
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: 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
- name: q
in: query
required: false
style: deepObject
explode: true
schema:
type: object
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- name: sort
in: query
required: false
description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
x-mint:
content: |-
## Filters
Filter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).
| Attribute | Kind | Predicates |
|---|---|---|
| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
**Sort by:** `active`, `code`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
table: TaxExemptionReason
sortable:
- active
- code
- created_at
- id
- name
- updated_at
responses:
'200':
description: tax exemption reasons found
content:
application/json:
example:
data:
- id: txr_UkLWZg9DAJ
name: Reseller (wholesale)
code: G
active: true
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous:
next:
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
summary: Create a tax exemption reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Adds a tax exemption reason to this store. Names and codes are unique per store.
**Required scope:** `write_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',
})
// `code` is what certificates record and the tax engine receives — on
// Avalara, an entity use code such as `G` (resale).
const reason = await client.taxExemptionReasons.create({
name: 'Reseller (wholesale)',
code: 'G',
})
- lang: bash
label: Spree CLI
source: spree api post /tax_exemption_reasons -d '{"name":"Reseller (wholesale)","code":"G"}'
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
responses:
'201':
description: tax exemption reason created
content:
application/json:
example:
id: txr_gbHJdmfrXB
name: Federal government
code: A
active: true
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Name can't be blank and Code can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
code:
- code: blank
message: can't be blank
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/TaxExemptionReasonCreateParams"
required: true
"/api/v3/admin/tax_exemption_reasons/{id}":
parameters:
- name: id
in: path
required: true
description: Tax exemption reason ID
schema:
type: string
get:
summary: Get a tax exemption reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Returns a single tax exemption reason by prefixed 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 reason = await client.taxExemptionReasons.get('txr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
source: spree api get /tax_exemption_reasons/{id}
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
responses:
'200':
description: tax exemption reason found
content:
application/json:
example:
id: txr_UkLWZg9DAJ
name: Reseller (wholesale)
code: G
active: true
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
can_be_deleted: true
'404':
description: tax exemption reason not found
content:
application/json:
example:
error:
code: record_not_found
message: Tax exemption reason not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
summary: Update a tax exemption reason
tags:
- Reasons
security:
- api_key: []
bearer_auth: []
description: |-
Renames a tax exemption reason or retires it. Deactivating keeps it on the
certificates that already record it while removing it from the pickers. The
code can change at any time, and every certificate holding the reason sends
the new code to the tax provider from then on.
**Required scope:** `write_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 reason = await client.taxExemptionReasons.update('txr_UkLWZg9DAJ', {
active: false,
})
- lang: bash
label: Spree CLI
source: spree api patch /tax_exemption_reasons/{id} -d '{"active":false}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
File truncated at 1 MB.