API usage guidelines

Pagination (required at scale)

Do not attempt unbounded list pulls.

GET /v1/products?limit=250&cursor=<opaque> HTTP/1.1

Response shape:

{
  "data": [ { "id": "prod_...", "title": "…" } ],
  "pagination": {
    "limit": 250,
    "next_cursor": "<opaque>",
    "has_more": true
  }
}

Rules:

• Default limit = 25; max = 250 (Enterprise may raise via contract)
• Use cursor pagination only — raw offset query parameters are rejected (400)
• Treat cursor / next_cursor as opaque strings (do not parse or invent them)
• Stable sort when using cursors; do not change sort mid-walk

Filtering

GET /v1/orders?status=paid&updated_since=2026-07-01T00:00:00Z&limit=100

Common query params:

Param	Example	Notes
updated_since	ISO-8601	Inclusive lower bound
created_since / created_until	ISO-8601
status	paid	Resource-specific enums
sku / q	search	Indexed search — not LIKE % scans
limit	1..250
cursor	opaque	From previous page
sort	updated_at:asc	Whitelisted fields only

Sorting

Only documented fields. Unknown sort → 400 INVALID_PARAMETER.

Batch operations

POST /v1/products/batch
Idempotency-Key: batch_prod_2026-08-01_01
Content-Type: application/json

{
  "operations": [
    { "op": "upsert", "sku": "SKU-1", "title": "…" },
    { "op": "upsert", "sku": "SKU-2", "title": "…" }
  ]
}

• Max ops per batch: 100 (Starter/Business); higher on Enterprise
• Partial success returns 207 with per-item errors when supported
• Prefer async job for > 1k mutations: POST /v1/jobs/catalog-import

Caching

Resource	Guidance
Products (public catalog)	Cache with short TTL; invalidate on product.* webhooks
Orders	Do not CDN-cache; pull or webhook
Inventory	Treat as volatile; webhook inventory.changed

Honor Cache-Control / ETag when present. Send If-None-Match for conditional GETs.

Incremental sync

See Data synchronization. Pattern:

1. Initial full sync via cursors
2. Store high-water mark (updated_at or event_id)
3. Poll updated_since or consume webhooks
4. Reconcile nightly with a bounded window

Anti-patterns

Anti-pattern	Do instead
GET /products for 1M SKUs	Cursor pages + webhooks
Poll every 1s	Webhooks + 5–15 min reconcile
One giant transaction from ERP	Batches + idempotency
Store API keys in frontend	Server-side only