Skip to main content

Documentation Index

Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

Developer Preview. The Admin API is in active development and may change between major versions.
The Admin API is a REST API for managing a Spree stores programmatically — products, orders, customers, fulfillments, payments, and more. It is intended for backend integrations, custom admin tooling, and automation. All routes are prefixed with /api/v3/admin. During development the API is available under http://localhost:3000/api/v3/admin. For production, replace http://localhost:3000 with your Spree application URL.

​
Admin API vs Store API

Admin APIStore API
PurposeManage store dataPower storefronts
AudienceStaff users, backend integrationsCustomers, storefronts
AuthenticationSecret API key (sk_…) or admin JWTPublishable API key (pk_…), customer JWT, order token
PermissionsAPI key scopes (API key authentication) or Admin Staff permission setsCustomer can only read/modify their own data
Write operationsFull CRUD on most resourcesLimited to the current customer’s cart, addresses, profile
If you’re building a storefront, use the Store API. The Admin API exposes administrative operations that should never be invoked from a browser.

​
Using the SDK

We recommend using @spree/admin-sdk to interact with the Admin API. It provides typed clients, automatic retries, and idempotency support.

​
Installation

npm install @spree/admin-sdk
# or
yarn add @spree/admin-sdk
# or
pnpm add @spree/admin-sdk

​
Quick start

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'http://localhost:3000',
  secretKey: 'sk_xxx',
})

const { data: orders } = await client.orders.list({
  status_eq: 'complete',
  limit: 25,
})

​
What’s covered

The Admin API today (in Spree 5.5) covers:
  • Catalog — products, variants, prices
  • Orders — list, create, update, items, complete, cancel, approve, resume; nested fulfillments, payments, refunds, gift cards, store credits
  • Customers — full CRUD, addresses, store credits, credit cards
See the Endpoints section in the sidebar for the complete reference, generated from the OpenAPI spec. Before integrating, read:
  • Authentication — secret API keys, scopes, and JWT tokens
  • Errors — error format and admin-specific codes
  • Querying — filtering, sorting, pagination, and expand