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

Authentication

All API requests require authentication via Bearer token:

curl https://api.hanzo.ai/product \
  -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/product \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Widget",
    "price": 2999,
    "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

Code	Description
`200`	Success
`201`	Created
`204`	No Content (successful delete)
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`409`	Conflict - Resource already exists
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error

Pagination

List endpoints support pagination:

curl "https://api.hanzo.ai/product?limit=20&offset=40" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (max 100)
`offset`	integer	0	Number of results to skip

Filtering

Filter results using query parameters:

curl "https://api.hanzo.ai/order?status=confirmed&since=2024-01-01" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sorting

Sort results using the sort parameter:

curl "https://api.hanzo.ai/product?sort=price:asc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl "https://api.hanzo.ai/order?sort=createdAt:desc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate Limiting

API requests are rate limited:

Tier	Requests/minute
Free	60
Pro	600
Enterprise	6000

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/order \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Versioning

The API is versioned via the URL path. The current version is v1 (implicit):

https://api.hanzo.ai/product        # Current version (v1)
https://api.hanzo.ai/v2/product     # Future version

Expanding Resources

Include related resources in responses:

curl "https://api.hanzo.ai/order/order_abc123?expand=items.product,payments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Webhooks

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