Manage your store via API

The Admin API (/api/v1/admin/*) exposes complete store management: catalog, pricing, stock, orders, customers, content, marketing, reports, settings. It’s designed for backends, integrations (ERP/PIM/billing), and automations — including AI agents via MCP.

Authentication & permissions

You need a staff token with the appropriate permissions:

Authorization: Bearer <staff_access_token>

Permissions are granular: catalog, sales, customers, content, marketing, reports, tax, users, system. A token can read/write only in the areas allowed by its role, and every call is scoped to its own store (the tenant_id claim).

The Admin API is server-side. Never embed a staff token in a public client.

Examples

# list products (includes inactive ones, for management)
curl "$BASE/api/v1/admin/products?page=1&page_size=24" -H "Authorization: Bearer $STAFF"

# create a product
curl -X POST "$BASE/api/v1/admin/products" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "name":"...", "slug":"...", ... }'

# orders + status change (with validated transitions)
curl "$BASE/api/v1/admin/orders?status=pending" -H "Authorization: Bearer $STAFF"
curl -X PATCH "$BASE/api/v1/admin/orders/<id>" -H "Authorization: Bearer $STAFF" \
  -H "Content-Type: application/json" -d '{ "status":"processing" }'

Best practices

Idempotency & bulk: for mass updates (prices, stock), process in batches and handle 409/422 responses per row.
Audit: every admin mutation is recorded in the store’s audit log.
Soft-delete: deleting a product/category sets deleted_at (it doesn’t destroy the order history); deactivating is a different thing (is_active).
Versioning: the API lives under /api/v1 — backward-compatible changes; breaking changes will go into a new version.

The full reference for the ~200 admin endpoints is in the API Reference (the admin sections), generated from the live OpenAPI schema.

Get started

Guides

AI & MCP

Manage your store via API

Authentication & permissions

Examples

Best practices

​Authentication & permissions

​Examples

​Best practices

Authentication & permissions

Examples

Best practices