API Reference

The Hanzo Commerce API is a RESTful API that provides programmatic access to all commerce functionality.

Base URL

Production: https://api.hanzo.ai
Sandbox:    https://sandbox.api.hanzo.ai

What api.hanzo.ai serves today

Commerce is one module served in two places, and they do not expose the same surface. api.hanzo.ai serves these families:

The module also implements a wider admin surface — products, variants, orders, customers, coupons, promotions, inventory, tax, regions, fulfillment, gift cards, draft orders, exchanges, claims, B2B and more. Those are routed by the standalone commerce deployment, not by api.hanzo.ai. Pages in this section that document them describe the module's capability, not a live route on this host — check the OpenAPI reference for what is actually served before you build against a path.

Authentication

All API requests require authentication via Bearer token:

curl https://api.hanzo.ai/v1/cart/6QiZNqrY9hW \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

See the Authentication Guide for details on obtaining tokens.

Request Format

• Content-Type: application/json
• Accept: application/json
• Character Encoding: UTF-8

Example Request

curl -X POST https://api.hanzo.ai/v1/cart \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "currency": "USD"
  }'

Response Format

All responses return JSON with the following structure:

Success Response

{
  "id": "prod_abc123",
  "name": "Premium Widget",
  "price": 2999,
  "currency": "USD",
  "createdAt": "2024-01-15T10:30:00Z"
}

List Response

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The 'price' field is required",
    "field": "price"
  }
}

HTTP Status Codes

Pagination

List endpoints support pagination:

curl "https://api.hanzo.ai/v1/store/?page=3&display=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Either one that is not a positive integer is refused, not silently ignored.

Filtering

Filter results using query parameters:

curl "https://api.hanzo.ai/v1/billing/subscriptions?status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sorting

Sort results using the sort parameter:

curl "https://api.hanzo.ai/v1/store/?sort=slug" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate Limiting

API requests are rate limited:

Rate limit headers are included in responses:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1705315200

Idempotency

For POST requests, include an idempotency key to prevent duplicate operations:

curl -X POST https://api.hanzo.ai/v1/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Versioning

Every endpoint lives under /v1, and the prefix is explicit — there is no implicit-version form:

https://api.hanzo.ai/v1/cart
https://api.hanzo.ai/v1/store/{storeid}/product/{key}

/v1/admin/products is not a commerce path, despite the name. It is the platform's fleet workload registry — the operator App CRs running in the cluster — and has nothing to do with a product you sell.

There is no /v2, and there will not be one. New capability arrives as new paths under /v1; breaking changes are avoided rather than versioned around. A path without the /v1 prefix is not an API route — it falls through to the console, which answers 200 text/html for any unmatched path, so a missing prefix looks like success until you read the body.

Expanding Resources

Include related resources in responses:

curl "https://api.hanzo.ai/v1/cart/6QiZNqrY9hW" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Webhooks

Register webhooks to receive real-time event notifications:

curl -X POST https://api.hanzo.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks",
    "events": ["order.created", "payment.completed"]
  }'

See Webhooks for the complete event list.

SDKs

Official SDKs are available for:

• JavaScript/TypeScript
• Go
• Python

API Endpoints