Spree Admin SDK

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

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// Asks every seller for a business registration before they can be approved.
// The wording is yours — `document` is one of the open-ended kinds, so a store
// can add as many as it needs, each with its own instructions.
const sellerRequirement = await client.sellerRequirements.create({
  type: 'document',
  name: 'Business registration',
  description: 'A copy of your certificate of incorporation.',
  required: true,
  preferences: { accepted_content_types: ['application/pdf'] },
})

spree api post /seller_requirements -d '{"type":"document","name":"Business registration","description":"A copy of your certificate of incorporation.","required":true,"preferences":{"accepted_content_types":["application/pdf"]}}'

{
  "id": "selreq_UkLWZg9DAJ",
  "position": 1,
  "active": true,
  "required": true,
  "metadata": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "kind": "document",
  "name": "Business registration",
  "description": "Upload this document for the marketplace to review",
  "preferences": {},
  "custom_field_definition_ids": [],
  "allow_multiple": true,
  "accepts_submissions": true,
  "reviewed_by_operator": true
}

{
  "error": {
    "code": "unknown_seller_requirement_type",
    "message": "Unknown type"
  }
}

Add a seller requirement

Adds something the marketplace asks of its sellers.

type comes from GET /seller_requirements/types, which also describes the configuration each kind takes. Most kinds answer one question and can be added once; the open-ended ones — a seller confirmation, a manual check, a document — carry the question in your own name and description, so a store may add as many as it needs.

A kind that reads the seller’s own data (their addresses, their products, whether they accepted the terms) needs nothing from the seller beyond doing it. The others wait for the seller to submit something, and the ones you review wait for you.

Required scope: write_sellers (for API-key authentication).

POST

api

admin

seller_requirements

Spree Admin SDK

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

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// Asks every seller for a business registration before they can be approved.
// The wording is yours — `document` is one of the open-ended kinds, so a store
// can add as many as it needs, each with its own instructions.
const sellerRequirement = await client.sellerRequirements.create({
  type: 'document',
  name: 'Business registration',
  description: 'A copy of your certificate of incorporation.',
  required: true,
  preferences: { accepted_content_types: ['application/pdf'] },
})

spree api post /seller_requirements -d '{"type":"document","name":"Business registration","description":"A copy of your certificate of incorporation.","required":true,"preferences":{"accepted_content_types":["application/pdf"]}}'

{
  "id": "selreq_UkLWZg9DAJ",
  "position": 1,
  "active": true,
  "required": true,
  "metadata": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "kind": "document",
  "name": "Business registration",
  "description": "Upload this document for the marketplace to review",
  "preferences": {},
  "custom_field_definition_ids": [],
  "allow_multiple": true,
  "accepts_submissions": true,
  "reviewed_by_operator": true
}

{
  "error": {
    "code": "unknown_seller_requirement_type",
    "message": "Unknown type"
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Body

application/json

type

string

required

The kind, from the seller requirement types endpoint.

Example:

"document"

name

string

What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself.

Example:

"Business registration"

description

string

Instructions shown to the seller.

Example:

"A copy of your certificate of incorporation."

position

integer

Place in the checklist.

Example:

1

active

boolean

Example:

true

required

boolean

Whether this blocks approval. Off means recommended.

Example:

true

preferences

object

Configuration for this kind, per its type's schema.

Example:

{
  "accepted_content_types": ["application/pdf"]
}

metadata

object

custom_field_definition_ids

string[]

Custom field definitions this requirement asks the seller to fill in (required_custom_fields kind).

Response

seller requirement created

string

required

position

number

required

active

boolean

required

boolean

required

metadata

object | null

required

created_at

string

required

updated_at

string

required

kind

string

required

Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more.

name

string

required

description

string | null

required

preferences

object

required

Settings of a seller requirement, shaped by its type (see x-spree-preferences-by-type). A type an extension registers is a plain object, described by the schema its /types entry carries.

Show child attributes

custom_field_definition_ids

string[]

required

allow_multiple

boolean

required

accepts_submissions

boolean

required

reviewed_by_operator

boolean

required

⌘I

API basics

Endpoints

Add a seller requirement

Authorizations

Headers

Body

Response