Skip to main content
Developer Preview. The Admin API is in active development and may change between major versions.
The Admin API is a REST API for managing 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