API reference

Four API surfaces

Surface	Path	Auth	Use case
v1 admin API	`/api/v1/...`	Bearer token	Server-to-server programmatic
Public endpoints	`/api/public/...`	CORS or `pk_*`	Storefront-side fetches
Inbound webhooks	various	HMAC verified	Shopify / WA / marketplace events
Outbound webhooks	(your URL)	HMAC signed	Notify your systems

Each linked from intro and detailed on its own page.

Conventions

Base URL

https://api.sumeru.systems

EU customers can opt for eu.api.sumeru.systems (Enterprise + data-residency requirement).

Versioning

The v1 admin API is semver versioned. Breaking changes get a major bump (v2) with 12-month deprecation of v1.

Public endpoints + webhooks: backwards-compatible additions ship continuously; breaking changes follow same v1→v2 model.

HTTP methods

Method	Used for
GET	Read
POST	Create or trigger action
PATCH	Partial update
DELETE	Remove
PUT	Full replace (rare; used only where relevant)

Pagination

Cursor-based; consistent across endpoints:

GET /api/v1/customers?limit=50&cursor=eyJpZCI6ImN1c19hYmMxMjMifQ==

Response includes pagination:

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImN1c19kZWY0NTYifQ==",
    "has_next": true
  }
}

Filtering + sorting

GET /api/v1/customers?filter[lifecycle_stage]=loyal&sort=-last_order_at

- prefix = descending. Filter syntax: filter[field]=value. Multiple filters AND together.

Sparse fieldsets

GET /api/v1/customers?fields=id,email,total_spent

Only requested fields returned (smaller payload, faster).

Includes (for relations)

GET /api/v1/customers/cus_abc123?include=orders,attributions

Bundles related objects into the response.

Error model

Uniform across all surfaces. Errors are JSON; HTTP status codes follow REST conventions:

{
  "error": {
    "code": "validation_failed",
    "message": "email format invalid",
    "details": {
      "field": "email",
      "value": "not-an-email"
    },
    "request_id": "req_abc123"
  }
}

Code	HTTP	Meaning
`unauthenticated`	401	No or invalid token
`forbidden`	403	Token lacks scope
`not_found`	404	Resource doesn't exist
`validation_failed`	422	Bad request body
`rate_limited`	429	Too many requests
`idempotency_conflict`	409	Same key, different body
`internal_error`	500	Sumeru-side issue
`service_unavailable`	503	Maintenance / overload

request_id should be cited when contacting support.

Idempotency

POST + PATCH endpoints accept Idempotency-Key header:

POST /api/v1/campaigns HTTP/1.1
Authorization: Bearer copt_...
Idempotency-Key: my-key-2026-05-10-launch-spring

{ ... }

Same key + same body in 24h → returns original response (safe to retry)
Same key + different body in 24h → 409 idempotency_conflict
Keys auto-expire after 24h

Use UUIDs or your own ULIDs for keys.

Rate limits

See Rate limits for full table. Headers on every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 421
X-RateLimit-Reset: 1715346000

When limited, response includes Retry-After header.

Stability guarantees per endpoint

Each endpoint declares stability:

Stability	Meaning
stable	Production-ready, semver-versioned
beta	Functionally complete; may have minor changes
experimental	Subject to breaking changes; not for prod
deprecated	Will be removed; alternative listed

Header on every response:

X-Sumeru-Stability: stable

Specifications

OpenAPI 3.1 specs available:

v1 admin API: https://api.sumeru.systems/openapi/v1-admin.yaml
Public endpoints: https://api.sumeru.systems/openapi/public.yaml

Both rendered as full reference at /developers/api/v1-admin/ and /developers/api/public-api/ (auto-generated from spec).

SDKs

Maintained:

Language	Repo
Node.js / TypeScript	`npm install @sumeru/sdk`
Python	`pip install sumeru`
PHP	`composer require sumeru/sdk`
Ruby	`gem install sumeru_es`
Go	`go get github.com/sumeru/sdk-go`

Each SDK wraps the v1 admin API with type-safe methods + auto-retry + idempotency.

Four API surfaces​

Conventions​

Base URL​

Versioning​

HTTP methods​

Pagination​

Filtering + sorting​

Sparse fieldsets​

Includes (for relations)​

Error model​

Idempotency​

Rate limits​

Stability guarantees per endpoint​

Specifications​

SDKs​

See also​