Spree Seller API introduction and SDK quick start

The Seller API is a REST API for the marketplace seller panel — where a seller runs their own shop inside someone else’s marketplace. It powers a seller’s catalog, their team, their stock locations, and the onboarding checklist the marketplace asks them to complete. All routes are prefixed with /api/v3/seller. During development the API is available under http://localhost:3000/api/v3/seller. For production, replace http://localhost:3000 with your Spree application URL.

A branch of its own, not a narrowing of the Admin API

Sellers never call the Admin API. Every Seller API endpoint is scoped server-side to the seller the request acts as, which makes cross-seller access impossible by construction rather than by rule: a product ID belonging to another seller answers 404, not 403. The store is derived from the seller, never sent alongside it, so no header a seller controls can widen what they reach.

	Seller API	Admin API
Purpose	Run one seller’s shop	Run the whole marketplace
Audience	Marketplace sellers and their staff	The marketplace operator’s staff
Authentication	Seller JWT only (`seller_api` audience)	Secret API key (`sk_…`) or admin JWT
Tenancy	Scoped to the acting seller	Scoped to the store
Server-to-server credential	None, by design	Secret API keys

The marketplace operator manages sellers — approving them, reviewing what they submit, setting commission — through the Admin API’s own seller endpoints, not through this API.

Using the SDK

We recommend @spree/seller-sdk for interacting with the Seller API. It provides typed clients, automatic retries, and handles the seller header for you.

Installation

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

Quick start

import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'http://localhost:3000',
})

// Sign in, then pick which seller to act as
const { token, sellers } = await client.auth.login({
  email: 'seller@example.com',
  password: 'password123',
})

client.setToken(token)
client.setSeller(sellers[0].id)

const { data: products } = await client.products.list({ limit: 25 })

What a seller can do

Catalog

List, create, update, and delete the products they own outright, picking a product type and a delivery profile from the marketplace’s lists.

Profile

Maintain presentation, contact details, addresses, and tax registration.

Team

Invite colleagues, list the team, and revoke access.

Onboarding

Read the marketplace’s checklist and submit against each requirement.

Stock locations

Manage where they keep stock, and so where returns are sent.

Uploads

Presign direct uploads for the documents onboarding asks for.

What a seller cannot do

Some fields are readable but never writable, because they belong to the marketplace rather than the seller:

status — the seller lifecycle belongs to the operator’s workflows. A seller says they are ready via POST /api/v3/seller/onboarding/submit_for_review; the operator decides.
slug — renaming a storefront address would break every link pointing at it.
Settlement and commission terms — what the marketplace charges is the marketplace’s to set.
Tax category and promotionability on products — marketplace-wide merchandising settings. A product’s type and delivery profile, by contrast, are the seller’s to assign — the marketplace defines the list, the seller picks from it.

Sending these fields is not an error; they are simply ignored.

API basics

Endpoints

Spree Seller API introduction and SDK quick start

A branch of its own, not a narrowing of the Admin API

Using the SDK

Installation

Quick start

What a seller can do

Catalog

Profile

Team

Onboarding

Stock locations

Uploads

What a seller cannot do

​A branch of its own, not a narrowing of the Admin API

​Using the SDK

​Installation

​Quick start

​What a seller can do

Catalog

Profile

Team

Onboarding

Stock locations

Uploads

​What a seller cannot do

A branch of its own, not a narrowing of the Admin API

Using the SDK

Installation

Quick start

What a seller can do

What a seller cannot do