Overview

The StateSet One API — base URL, authentication, your first request, errors, and pagination.

StateSet One API

StateSet One is the commerce operating system underneath orders, inventory, returns, logistics, and finance. Everything the platform does is available over this API.

This page is the contract: how to authenticate, what a response looks like, and what happens when something goes wrong.

Base URL

https://api.stateset.com/v1

Authenticate

Every request needs an API key in the Authorization header.

curl https://api.stateset.com/api/v1/orders \
  -H "Authorization: Bearer $STATESET_API_KEY"

API keys, JWT tokens, and OAuth 2.0 are all supported — see Authentication for when to use which.

Treat a key as a credential for your whole account. Keep it server-side, never in browser or mobile code, and issue a separate key per consumer so you can revoke one without breaking everything else.

Your first request

List recent orders:

curl "https://api.stateset.com/api/v1/orders?limit=5" \
  -H "Authorization: Bearer $STATESET_API_KEY"

Create one:

curl -X POST https://api.stateset.com/api/v1/orders \
  -H "Authorization: Bearer $STATESET_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customer_id": "cus_1042",
    "line_items": [{ "sku": "SHOE-RED-10", "quantity": 1 }]
  }'

Send an Idempotency-Key on every write. A retried request with the same key replays the original result instead of creating a second order — which matters more than usual when an agent is doing the retrying.

Errors

Failures return a structured envelope, not a bare string:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "type": "error_type",
    "details": { },
    "request_id": "req_1NXWPnCo6bFb1KQto6C8OWvE",
    "timestamp": "2024-01-15T10:30:00Z",
    "documentation_url": "https://docs.stateset.com/errors/ERROR_CODE"
  }
}

Branch on code, not on message — messages are for humans and may be reworded. Log request_id; it’s what support needs to trace a specific call.

Full catalogue in Errors.

Rate limits

Responses carry your current budget:

Header	Meaning
X-RateLimit-Limit	Requests allowed in the window
X-RateLimit-Remaining	Requests left
X-RateLimit-Reset	When the window resets
X-RateLimit-Retry	How long to wait after a 429
X-RateLimit-Bucket	Which bucket the limit applies to

Read X-RateLimit-Remaining and back off before you’re throttled rather than after. Details in Rate limiting.

Beyond REST

Interface	Use for
GraphQL — queries, mutations, subscriptions	Fetching exactly the shape you need, and live subscriptions
gRPC	Low-latency service-to-service calls
Webhooks	Reacting to events instead of polling
Events	The event catalogue

GraphQL supports remote data joins, so a single query can span sources that live in different systems.

What the platform covers

Domain	Endpoints
Orders and checkout	Order management · Checkouts
Returns and warranties	Returns · Warranties
Inventory and warehouse	Inventory · Packing lists
Manufacturing	BOM · Work orders
Suppliers and purchasing	Purchase orders · Suppliers
CRM	Leads · Accounts · Contacts

Workflow orchestration runs on Temporal, so long-running operations are durable rather than best-effort.

SDKs

Official clients wrap auth, retries, and pagination — see SDKs.

Next

Quickstart

A working request in a few minutes.

Authentication

Keys, JWT, and OAuth 2.0.

Errors

Every code and what to do about it.

Integrations

186 native integrations.