Inbound API
REST endpoints your plugin calls into a merchant store — orders, products, customers, inventory.
Base URL & versioning
All requests target https://api.aeonzap.com/v1. The version is part of the path, never a header. Breaking changes ship as v2; v1 is supported for at least 24 months after that.
Authentication
Plugins receive a per-installation project token via ctx.token. The token is scoped to the merchant store that installed your plugin and inherits exactly the scopes your manifest declared. Send it in the Authorization header.
curl https://api.aeonzap.com/v1/orders?limit=20 \
-H "Authorization: Bearer $AEONZAP_TOKEN" \
-H "X-Aeonzap-Store: store_4f2a"Orders
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/orders | orders.read | List orders, paginated by cursor |
GET | /v1/orders/{id} | orders.read | Fetch one order with line items |
POST | /v1/orders | orders.write | Create a draft or live order |
PATCH | /v1/orders/{id} | orders.write | Update tags, notes, custom fields |
POST | /v1/orders/{id}/fulfillments | orders.write | Mark items shipped |
POST | /v1/orders/{id}/refunds | orders.write | Refund money or items |
Products
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/products | products.read | List products with variants |
POST | /v1/products | products.write | Create a product |
PATCH | /v1/products/{id} | products.write | Update fields |
POST | /v1/products/{id}/variants | products.write | Add a variant |
POST | /v1/inventory/adjust | products.write | Increment or set stock |
Customers
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /v1/customers | customers.read | List customers |
GET | /v1/customers/{id} | customers.read | Single customer + addresses |
POST | /v1/customers | customers.write | Create a customer |
PATCH | /v1/customers/{id} | customers.write | Update profile |
Pagination
List endpoints return a cursor-based page. Pass ?cursor= to continue. Cursors are opaque; do not parse them.
{
"data": [ /* items */ ],
"page": {
"next_cursor": "eyJpZCI6Im9yZF84ODIxIn0",
"has_more": true
}
}Rate limits
Default budget is 60 requests per second per store, 600 per minute, with bursts up to 120/s. The headers X-RateLimit-Remaining and X-RateLimit-Reset come on every response. A 429 includes Retry-After in seconds.
Error format
{
"error": {
"code": "validation_failed",
"message": "price must be a positive integer",
"field": "variants[0].price",
"request_id": "req_01HM6XB42Z"
}
}