Spree Commerce Settings API
Store-level settings — store profile, tags, store credit categories
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/spree-settings-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.0.3
info:
title: Admin Account / Address Settings API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: hello@spreecommerce.org
description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n"
version: v3
servers:
- url: http://{defaultHost}
variables:
defaultHost:
default: localhost:3000
tags:
- name: Settings
description: Store-level settings — store profile, tags, store credit categories
paths:
/api/v3/admin/store_credit_categories:
get:
summary: List store credit categories
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: 'Returns the configured store credit categories. Categories classify
store credits (e.g., "Goodwill", "Gift Card", "Refund") and surface
in the admin UI as a dropdown when issuing or editing a store
credit. Category names matching `Spree::Config[:non_expiring_credit_types]`
are flagged via `non_expiring: true`.
**Required scope:** `read_settings` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst { data: categories } = await client.storeCreditCategories.list()"
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[name_cont]
in: query
required: false
description: Filter by name (contains)
schema:
type: string
- 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
responses:
'200':
description: store credit categories found
content:
application/json:
example:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
created_at: '2026-06-12T17:25:17.833Z'
updated_at: '2026-06-12T17:25:17.833Z'
non_expiring: false
meta:
page: 1
limit: 25
count: 1
pages: 1
from: 1
to: 1
in: 1
previous: null
next: null
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/StoreCreditCategory'
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'
/api/v3/admin/store_credit_categories/{id}:
parameters:
- name: id
in: path
required: true
description: Store credit category ID
schema:
type: string
get:
summary: Get a store credit category
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: 'Returns a single store credit category 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'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst category = await client.storeCreditCategories.get('sccat_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: fields
in: query
required: false
description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
description: store credit category found
content:
application/json:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
created_at: '2026-06-12T17:25:18.145Z'
updated_at: '2026-06-12T17:25:18.145Z'
non_expiring: false
schema:
$ref: '#/components/schemas/StoreCreditCategory'
'404':
description: store credit category not found
content:
application/json:
example:
error:
code: record_not_found
message: Store credit category not found
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v3/admin/store:
get:
summary: Get the current store
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: 'Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.
**Required scope:** `read_settings` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst store = await client.store.get()"
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 store
content:
application/json:
example:
id: store_UkLWZg9DAJ
metadata: {}
name: Spree Test Store
default_currency: USD
default_locale: en
mail_from_address: no-reply@example.com
customer_support_email: support@example.com
new_order_notifications_email: store-owner@example.com
preferred_send_consumer_transactional_emails: true
preferred_admin_locale: null
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
created_at: '2026-06-12T17:23:41.091Z'
updated_at: '2026-06-12T17:25:18.763Z'
url: http://www.example.com:3000
supported_currencies:
- USD
supported_locales:
- en
logo_url: null
mailer_logo_url: null
schema:
$ref: '#/components/schemas/Store'
'401':
description: unauthorized
content:
application/json:
example:
error:
code: authentication_required
message: Authentication required
schema:
$ref: '#/components/schemas/ErrorResponse'
patch:
summary: Update the current store
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: 'Updates the current store configuration.
**Required scope:** `write_settings` (for API-key authentication).'
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst store = await client.store.update({\n name: 'My Store'\n})"
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: store updated
content:
application/json:
example:
id: store_UkLWZg9DAJ
metadata: {}
name: Renamed Store
default_currency: USD
default_locale: en
mail_from_address: no-reply@example.com
customer_support_email: support@example.com
new_order_notifications_email: store-owner@example.com
preferred_send_consumer_transactional_emails: true
preferred_admin_locale: null
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
created_at: '2026-06-12T17:23:41.091Z'
updated_at: '2026-06-12T17:25:19.408Z'
url: http://www.example.com:3000
supported_currencies:
- USD
supported_locales:
- en
logo_url: null
mailer_logo_url: null
schema:
$ref: '#/components/schemas/Store'
'422':
description: validation error
content:
application/json:
example:
error:
code: validation_error
message: Site Name can't be blank
details:
name:
- can't be blank
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: My Store
preferred_admin_locale:
type: string
example: en
preferred_timezone:
type: string
example: UTC
preferred_weight_unit:
type: string
example: kg
preferred_unit_system:
type: string
example: metric
/api/v3/admin/tags:
get:
summary: List tags
tags:
- Settings
security:
- api_key: []
bearer_auth: []
description: Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: "import { createAdminClient } from '@spree/admin-sdk'\n\nconst client = createAdminClient({\n baseUrl: 'https://your-store.com',\n secretKey: 'sk_xxx',\n})\n\nconst { data: tags } = await client.tags.list({\n taggable_type: 'Spree::User',\n q: 'vip',\n})"
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
schema:
type: string
- name: taggable_type
in: query
required: true
description: Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)
schema:
type: string
- name: q
in: query
required: false
description: Optional case-insensitive substring filter
schema:
type: string
responses:
'200':
description: tags found
content:
application/json:
example:
data:
- name: vip
- name: wholesale
'422':
description: invalid taggable type
content:
application/json:
example:
error:
code: invalid_taggable_type
message: taggable_type must be one of Spree::Product, Spree::Order, Spree::LegacyUser
components:
schemas:
Store:
type: object
properties:
id:
type: string
metadata:
type: object
name:
type: string
default_currency:
type: string
default_locale:
type: string
mail_from_address:
type: string
nullable: true
customer_support_email:
type: string
nullable: true
new_order_notifications_email:
type: string
nullable: true
preferred_send_consumer_transactional_emails:
type: boolean
preferred_admin_locale:
type: string
nullable: true
preferred_timezone:
type: string
preferred_weight_unit:
type: string
preferred_unit_system:
type: string
created_at:
type: string
updated_at:
type: string
url:
type: string
supported_currencies:
type: array
items:
type: string
supported_locales:
type: array
items:
type: string
logo_url:
type: string
nullable: true
mailer_logo_url:
type: string
nullable: true
required:
- id
- metadata
- name
- default_currency
- default_locale
- mail_from_address
- customer_support_email
- new_order_notifications_email
- preferred_send_consumer_transactional_emails
- preferred_admin_locale
- preferred_timezone
- preferred_weight_unit
- preferred_unit_system
- created_at
- updated_at
- url
- supported_currencies
- supported_locales
- logo_url
- mailer_logo_url
x-typelizer: true
StoreCreditCategory:
type: object
properties:
id:
type: string
name:
type: string
created_at:
type: string
updated_at:
type: string
non_expiring:
type: boolean
required:
- id
- name
- created_at
- updated_at
- non_expiring
x-typelizer: true
PaginationMeta:
type: object
properties:
page:
type: integer
example: 1
limit:
type: integer
example: 25
count:
type: integer
example: 100
description: Total number of records
pages:
type: integer
example: 4
description: Total number of pages
from:
type: integer
example: 1
description: Index of first record on this page
to:
type: integer
example: 25
description: Index of last record on this page
in:
type: integer
example: 25
description: Number of records on this page
previous:
type: integer
nullable: true
example: null
description: Previous page number
next:
type: integer
nullable: true
example: 2
description: Next page number
required:
- page
- limit
- count
- pages
- from
- to
- in
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: record_not_found
message:
type: string
example: Record not found
details:
type: object
description: Field-specific validation errors
nullable: true
example:
name:
- is too short
- is required
email:
- is invalid
required:
- code
- message
required:
- error
example:
error:
code: validation_error
message: Validation failed
details:
name:
- is too short
email:
- is invalid
securitySchemes:
api_key:
type: apiKey
name: x-spree-api-key
in: header
description: Secret API key for admin access
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
tags:
- Authentication
- name: Products & Catalog
tags:
- Products
- Variants
- Option Types
- Custom Fields
- Channels
- name: Pricing
tags:
- Pricing
- Markets
- name: Orders & Fulfillment
tags:
- Orders
- Payments
- Fulfillments
- Refunds
- name: Customers
tags:
- Customers
- Customer Groups
- name: Promotions & Gift Cards
tags:
- Promotions
- Gift Cards
- name: Data
tags:
- Exports
- name: Configuration
tags:
- Settings
- Stock Locations
- Payment Methods
- Staff
- API Keys
- Allowed Origins
- Webhooks