spree-api-v3

Spree API v3

Spree 6 has three REST surfaces under /api/v3/, and they share one set of conventions:

Surface	Path	Caller	Auth	Authorization
Store API	/api/v3/store/*	Storefronts, mobile apps, shoppers	X-Spree-Api-Key: pk_… + optional Authorization: Bearer <jwt> (aud: store_api) + guest X-Spree-Token	Ownership (see spree-auth-permissions)
Admin API	/api/v3/admin/*	Integrations, back-office apps, the dashboard	X-Spree-Api-Key: sk_… or Authorization: Bearer <jwt> (aud: admin_api)	Key scopes / role permission keys
Seller API	/api/v3/seller/*	Marketplace seller panel	Seller JWT (aud: seller_api) + X-Spree-Seller-Id	Seller role keys + current_seller scoping (see spree-marketplace)

A token issued for one audience is rejected on the other surfaces. The v2 Storefront/Platform APIs don't exist in Spree 6. If you're migrating an old integration, see node_modules/@spree/docs/dist/api-reference/store-api/migrating-from-storefront-api-v2.md.

Store API

• Anonymous browsing needs only X-Spree-Api-Key: pk_…. Publishable keys are safe in client code.
• Guest cart/checkout/order: also send X-Spree-Token: <cart.token>.
• Signed-in customer: also send Authorization: Bearer <jwt> from POST /api/v3/store/auth/login. The response body contains token, refresh_token and user. Rotate with POST /auth/refresh and { "refresh_token": "…" }.
• Context headers:
  • X-Spree-Country resolves the market, which sets the default locale and currency.
  • X-Spree-Locale and X-Spree-Currency override those defaults.
  • X-Spree-Channel: <code> selects the channel; the store default is used if it's absent. A publishable key bound to a channel decides the channel itself, and a conflicting header returns channel_mismatch.
• Responses are customer-safe: no cost prices, no internal notes. On channels that hide prices from guests, money fields come back null, so type them string | null.
• The Store API is read-only by default. Writes are limited to carts, checkout, the customer's own account (/customers/me/*), wishlists, returns/claims on the customer's own orders, and newsletter/company self-service.

curl -H "X-Spree-Api-Key: pk_xxx" -H "X-Spree-Country: DE" \
     "https://shop.example.com/api/v3/store/products?q[name_cont]=shirt&expand=default_variant"

Carts and orders are different resources

A cart (cart_…, /api/v3/store/carts) is mutable and has no status. Completing it creates an immutable order (or_…).

POST   /carts                         → cart (token in response)
POST   /carts/{id}/items              { variant_id, quantity }
PATCH  /carts/{id}                    { email, shipping_address, billing_address, use_shipping, … }
PATCH  /carts/{id}/fulfillments/{id}  { selected_delivery_rate_id }
POST   /carts/{id}/payment_sessions   … gateway flow …
POST   /carts/{id}/complete           → the Order (or an OrderGroup for split marketplace checkouts)
GET    /orders/{id}                   → order by or_ id, OR by the original cart_ id

• After completion, GET /carts/{id} returns 404 (cart_not_found), because completed carts drop out of cart lookups. Read the result with GET /orders/{cart_id}. The order endpoint accepts the cart's prefixed ID and resolves it to the order created from it (order.cart_id). Guests keep using the same X-Spree-Token.
• POST /carts/{id}/complete is safe to retry: if a payment webhook already completed the cart, the retry returns the existing order.
• requirements[] on the cart lists what still blocks completion, as { step, field, code, message } (e.g. { "step": "delivery", "field": "delivery_method", "code": "delivery_method_required" }). Steps are only advisory; completion is the one hard gate. Drive the checkout UI from requirements, not from a state name. See spree-checkout.
• Coupons: POST /carts/{id}/discount_codes { code }. Both carts and orders expose coupon_code.
• A signed-in customer's history is at GET /customers/me/orders.

Order fields you'll use

• status (Admin API): draft | placed | canceled. Filter with q[status_eq]=placed.
• payment_status: none, authorized, partially_paid, paid, partially_refunded, refunded, overcharged, voided.
• fulfillment_status: unfulfilled, partial, fulfilled, delivered, backorder, canceled (legacy pending / ready / shipped can appear on migrated orders).
• Totals: item_total, delivery_total, discount_total, tax_total (included_/additional_), fee_total, gift_card_total, store_credit_total, total, amount_due, each paired with display_*.
• withdrawal_period_ends_at / within_withdrawal_period (EU right of withdrawal).

There is no state, payment_state or shipment_state, and no ship_total/promo_total/adjustment rows. Money is itemized as tax lines, discounts and fees (see spree-order-totals).

Admin API

Secret key (integrations): X-Spree-Api-Key: sk_…. The key selects its store. JWT (people): POST /api/v3/admin/auth/login { email, password } (or { provider, … } for SSO). The response body is { token, user }. The refresh token is set as an HttpOnly cookie scoped to /api/v3/admin/auth, and POST /auth/refresh takes no body. Admin JWTs expire after 5 minutes by default. For multi-store hosts, send X-Spree-Store-Id.

If a request carries both credentials, the JWT wins.

Permissions

Every Admin controller maps its actions to one key: index/show → read_<resource>, everything else (including member actions like /orders/{id}/cancel) → write_<resource>. write_* implies read_*.

• A secret key is checked against its scopes. Failure is 403 access_denied with details.required_scope.
• JWT staff are checked against their roles' permission keys on this store. Failure is 403 with details.required_permission. A 403 without that detail means a record-level rule refused — those rules come from Spree.ability_class (swappable via Spree::Dependencies.ability_class; secret keys use Spree::ApiKeyAbility instead). See spree-auth-permissions.
• Keys never decide which rows you see: every endpoint scopes through the current store.
• Secret-key scopes are fixed at creation. To change them, mint a new key and revoke the old one.

The full scope list with groups and covered resources is in references/scopes.md. At runtime, GET /api/v3/admin/permissions returns the same list, and Spree::ApiKey.known_scopes gives it in Ruby. Common picks:

Order sync out ............ read_orders (+ read_payments, read_fulfillments)
Warehouse / 3PL ........... read_orders, write_fulfillments, write_stock
ERP product feed .......... write_products (+ write_categories / write_collections)
Refund automation ......... read_orders, write_refunds
Staff provisioning ........ write_staff
Everything (avoid) ........ write_all

Staff roles are data (/api/v3/admin/roles). See spree-auth-permissions.

Admin-only response traits

• Timestamps, internal notes, cost prices, status, and custom fields that aren't storefront-visible.
• Actor pairs. Records that remember who acted (canceler, approver, created_by, refunder, …) expose *_id plus *_type. The ID is adm_… for staff or key_… for a secret key, and *_type is admin_user or api_key. Treat *_type as an open list. expand=canceler returns { id, type, label }.

Shared conventions

Prefixed IDs

IDs are always Stripe-style prefixed strings, on both reads and writes ("variant_id": "variant_k5nR8xLq"). Never send or expect integer IDs. Common prefixes:

Prefix	Resource	Prefix	Resource
prod_	Product	variant_	Variant
cart_	Cart	or_	Order
ogrp_	OrderGroup (split checkout)	li_	LineItem
py_	Payment	re_	Refund
ful_	Fulfillment	ret_	Return
tl_	TaxLine	disc_	Discount
fee_	Fee	cust_	Customer
adm_	AdminUser	addr_	Address
ctg_	Category	coll_	Collection
sl_	StockLevel	sloc_	StockLocation
mkt_	Market	ch_	Channel
sel_	Seller	media_	Media
cf_	CustomField	promo_	Promotion
gc_	GiftCard	role_	Role
key_	ApiKey record (not the pk_/sk_ token)	store_	Store

The prefix identifies the resource type, so there is no type field on the envelope. Verify any others with grep -rn has_prefix_id spree/core/app/models. There is no adj_, because Adjustment doesn't exist in Spree 6.

Envelope, pagination, sorting

Lists return { data: [...], meta: { page, limit, count, pages, from, to, in, previous, next } }. A single record is returned as a bare object. Pagination: ?page=2&limit=50 (default 25, max 100). Sort: ?sort=-completed_at,number.

Expand and fields

• ?expand=default_variant,media,variants.prices sideloads associations; dot notation reaches nested ones. Allowed keys vary per resource (see the OpenAPI spec).
• Admin API expansions are permission-checked per segment: order(s) needs read_orders, payment(s)/payment_splits read_payments, customer(s) read_customers, gift_card(s) read_gift_cards, store_credit(s) read_store_credits (so orders.payments needs both). A path the caller can't cover is silently dropped, not a 403. Gift card code is masked (all but the last four characters) unless the caller holds read_gift_cards.
• ?fields=name,slug returns a sparse response (id is always included).

Filtering (Ransack)

q[<attr>_<predicate>]=value, e.g. q[name_cont]=shirt, q[status_eq]=placed, q[completed_at_gteq]=2026-09-01. Predicates include _eq, _not_eq, _in, _cont, _start, _gt, _gteq, _lt, _lteq, _present, _blank. Attributes outside the model's ransack allowlist are silently ignored: you get 200 with that filter dropped. Allowlist them with Spree.ransack.add_attribute(Spree::Product, :brand_id).

The allowlists are narrowed per audience (Ransack auth_object: nil for Admin, :store, :seller):

• Store API follows only a model's storefront_ransackable_associations (products: tags, categories, collections; empty for every other model) and drops the model's private_ransackable_attributes[:store] (e.g. order email, considered_risky, coupon_code and the search/multi_search scopes; variant cost_price; store credit memo).
• Seller API follows no associations and drops private_ransackable_attributes[:seller] (order email, considered_risky, coupon_code; plus the search/multi_search scopes).
• Admin API gets the full allowlist. So Spree.ransack.add_association(Spree::Product, :brand) makes q[brand_name_eq] work for staff only — to let shoppers filter through it too, add Spree::Product.storefront_ransackable_associations |= %w[brand] (only for associations whose data the storefront may see). Attributes added with add_attribute reach every audience unless listed as private.

Addresses

Use first_name, last_name, address1, city, postal_code, country_code (ISO2), state_code. On carts, use_shipping: true copies shipping to billing. country_iso/state_abbr still appear in responses but are deprecated.

Rich text

Rich-text attributes come back twice: description as plain text and description_html as sanitized HTML. Render *_html and write to the plain name (the value you send is HTML). Spree sanitizes it on save.

Money

Amounts are decimal strings ("29.99"), each paired with a display_* formatted string. When prices are hidden they're null. On writes, prices are arrays: "prices": [{ "currency": "USD", "amount": "29.99" }].

Idempotency

Send Idempotency-Key: <uuid> (max 255 chars) on POST/PUT/PATCH/DELETE. For 24 hours a retry with the same key and body replays the stored response (header Idempotent-Replayed: true). Reusing a key with a different body returns 422 idempotency_key_reused. 5xx responses aren't cached. The SDKs and the CLI add the key automatically.

Errors

{ "error": { "code": "validation_error", "message": "Email can't be blank",
             "details": { "email": ["can't be blank"] } } }

Status	Typical code
401	authentication_required, invalid_token, authentication_failed, invalid_refresh_token
403	access_denied (details.required_scope / required_permission), channel_mismatch
404	record_not_found, cart_not_found, order_not_found, line_item_not_found, variant_not_found
422	validation_error (per-attribute details, with base for form-level errors), cart_cannot_complete, insufficient_stock, payment_failed, idempotency_key_reused
413	request_too_large (body > max_request_body_size, 100 KB)
429	rate_limit_exceeded

Rate limits

Built on Rails rate_limit, with counters in Rails.cache. That cache must be shared (Solid Cache or Redis) across processes. Configure through Spree::Api::Config or the env vars:

Preference (env)	Default	Bucket
rate_limit_per_key (SPREE_RATE_LIMIT_PER_KEY)	300 / window	Publishable key + client IP (per visitor); client IP when no key is sent
rate_limit_per_secret_key (SPREE_RATE_LIMIT_PER_SECRET_KEY)	600 / window	Per secret key, across the whole API
rate_limit_window (SPREE_RATE_LIMIT_WINDOW)	60 s
rate_limit_login	5	Per IP: store/admin/seller login, invitation acceptance
rate_limit_register	3	Per IP: customer registration, newsletter subscribe
rate_limit_refresh	10	Per IP: refresh, logout, admin auth providers
rate_limit_password_reset	3	Per IP

Responses include X-RateLimit-Limit, X-RateLimit-Remaining and, when limited, Retry-After. Inbound payment/fulfillment webhook endpoints have their own fixed limit of 120/min.

Debugging recipes

• 401 everywhere: a pk_ key sent to the Admin API or an sk_ key to the Store API; a revoked key; an admin JWT older than 5 minutes (refresh via the cookie); a customer token sent to the Admin API (wrong aud).
• 403 on Admin: read details.required_scope / required_permission. For a key, mint a new one with that scope. For staff, add the key to their role on this store.
• Cart 404 right after checkout: expected. Fetch GET /orders/{cart_id}.
• Empty list but records exist: wrong channel (X-Spree-Channel or a channel-bound key), product not published on that channel, no price in the requested currency or market, or a silently dropped Ransack filter.
• Probe from a terminal: spree api get /orders/or_xxx --expand payments,fulfillments (see spree-cli).

Where to read further

• OpenAPI specs (authoritative): node_modules/@spree/docs/dist/api-reference/store.yaml, admin.yaml, seller.yaml
• Store API guides: node_modules/@spree/docs/dist/api-reference/store-api/ (authentication, localization, idempotency, rate limiting, querying, relations)
• Admin API guides: node_modules/@spree/docs/dist/api-reference/admin-api/ (authentication, errors, querying)
• Webhook events: node_modules/@spree/docs/dist/api-reference/webhooks-events.md
• Related skills: spree-auth-permissions, spree-typescript-sdk, spree-cli, spree-resource (add endpoints), spree-checkout, spree-marketplace (Seller API), spree-events-webhooks.