API reference

A small REST API over HTTPS. Every response uses one envelope; money is always a string of minor units.

Base URL:

https://<store-domain>/api/v1

Authentication

Send your key in the x-api-key header on every request. Keys are shown once, stored hashed, and revocable.

-H "x-api-key: $KEY"

Scopes

A key carries scopes; a call without the scope it needs returns FORBIDDEN.

catalog:read

purchase

orders:read

Endpoints

GET

/b2b/catalog

Scope: catalog:read

List products with your-tier prices and availability.

Example request

curl https://your-store.com/api/v1/b2b/catalog?perPage=100 \
  -H "x-api-key: $KEY"

Example response

{
  "ok": true,
  "data": [{
    "id": "019f56a9-…", "slug": "steam-5-us",
    "name": { "en": "Steam $5 — United States" },
    "type": "code", "listPrice": "545", "yourPrice": "501",
    "currency": "USD", "available": true, "maxPerOrder": 20
  }],
  "meta": { "page": 1, "perPage": 100, "total": 38 }
}

POST

/b2b/orders

Scope: purchase

Place an order (idempotent, wallet-paid).

Example request

curl -X POST https://your-store.com/api/v1/b2b/orders \
  -H "x-api-key: $KEY" \
  -H "x-idempotency-key: po-2026-07-12-0001" \
  -H "content-type: application/json" \
  -d '{
    "externalRef": "po-2026-07-12-0001",
    "items": [{ "productId": "019f56a9-…", "quantity": 2 }]
  }'

Example response

{ "ok": true, "data": {
  "orderId": "019f5728-…", "number": "KC-MRI0BS8W-026F",
  "status": "paid", "total": "1002"
} }

GET

/b2b/orders

Scope: orders:read

List your orders.

Example request

curl https://your-store.com/api/v1/b2b/orders \
  -H "x-api-key: $KEY"

GET

/b2b/orders/{orderId}

Scope: orders:read

Read one order with its delivered codes.

Example request

curl https://your-store.com/api/v1/b2b/orders/019f5728-… \
  -H "x-api-key: $KEY"

Example response

{ "ok": true, "data": {
  "orderId": "019f5728-…", "status": "delivered",
  "externalRef": "po-2026-07-12-0001", "total": "1002",
  "lines": [{
    "product": { "slug": "steam-5-us" }, "quantity": 2,
    "units": [{ "unitIndex": 0, "status": "delivered", "code": "XXXX-YYYY-ZZZZ" }]
  }]
} }

GET

/b2b/orders/by-ref/{externalRef}

Scope: orders:read

Read an order by your own externalRef.

Example request

curl https://your-store.com/api/v1/b2b/orders/by-ref/po-2026-07-12-0001 \
  -H "x-api-key: $KEY"

GET

/b2b/wallet

Scope: catalog:read

Read your wallet balance.

Example request

curl https://your-store.com/api/v1/b2b/wallet \
  -H "x-api-key: $KEY"

Example response

{ "ok": true, "data": { "cash": "48998", "currency": "USD" } }

Idempotency

Send an Idempotency-Key header on POST /b2b/orders. A retry with the same key replays the first result — the order is never placed twice. Also pass your own externalRef to look an order up later by your reference.

Errors

Failures return the same envelope with ok:false and a stable code. Worth handling:

UNAUTHORIZED

Missing or revoked token

FORBIDDEN

Token lacks the scope for this call

IDEMPOTENCY_KEY_REQUIRED

Money-moving POST without x-idempotency-key

IDEMPOTENCY_KEY_REUSED

Same key, different body

INSUFFICIENT_FUNDS

Wallet balance below the order total

OUT_OF_STOCK

Not enough units available right now

LIMIT_EXCEEDED

A product's per-user daily cap refused a line

RATE_LIMITED

Back off and retry (reuse the same idempotency key)