API v1 · platform
Public API v1 contract
The eleven current operations, authentication, pagination, errors, fixed-window rate limits, and limitations.
Public API v1 contract
The current base path is /api/v1. Send an installation-bound access token from your server as Authorization: Bearer <ACCESS_TOKEN>. The Marketplace feature must be enabled; otherwise the surface is unavailable.
Current operations
| Method and path | Required scope | Current resource coverage |
|---|---|---|
GET /api/v1/catalog/products | catalog:read | Product list fields. |
GET /api/v1/orders | orders:read | Order summary fields. |
GET /api/v1/webhooks | webhooks:manage | Installation subscriptions. |
POST /api/v1/webhooks | webhooks:manage | Create or rotate a subscription secret. |
DELETE /api/v1/webhooks/{id} | webhooks:manage | Disable one installation subscription. |
GET /api/v1/customers | customers:read | Name, phone, email and creation time; no addresses or notes. |
GET /api/v1/discounts | discounts:read | Currently active rules; no customer redemptions. |
GET /api/v1/inventory/locations | inventory:read | Location names, type and active/default state. |
GET /api/v1/inventory/levels | inventory:read | Product, variant and location IDs; available, reserved and total quantities. |
GET /api/v1/inventory/movements | inventory:read | Product/location IDs, quantity delta, reason and creation time; no notes or staff identity. |
GET /api/v1/store | store:read | Store names, ID, subdomain and creation time; no private settings or bank details. |
Product, discount and order mutations, payment, shipping and messaging have no public API contract yet.
Pagination
The product and order list operations accept limit from 1 through 100, default 25, and an ISO timestamp before. Responses contain meta.limit and meta.next_before. A non-date cursor returns 400 with invalid_before_cursor.
The six new read endpoints return data and meta.next_cursor. Pass both before and before_id exactly as returned, preserving timestamp microseconds. Rows sort by (created_at, id) descending, so equal timestamps do not skip rows. A null cursor means the page is final. limit defaults to 25 and must be an integer from 1 to 100. Partial cursors, repeated or unknown query parameters (including tenant_id) return 400 invalid_pagination. The database rechecks the original token, current grant and release gate in the same transaction as the data read; previously resolved access cannot outlive a committed revocation.
Error behavior
API v1 errors use this envelope:
{"error":{"code":"invalid_token"}}Known status classes include 400 invalid input, 401 invalid token, 403 denied webhook creation, 404 unavailable surface or missing subscription, 413 oversized create body, 429 rate limit, 500 query/mutation failure, and 503 rate-limit service unavailable. Use the code, not prose matching. Retry only idempotent operations and only with bounded backoff.
Rate limits
The actual policy is 60 requests per 60-second fixed window, per installation, per route key. Successful authorization returns RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429 also returns Retry-After. The limit is not per token, per app globally, or per tenant globally.
Versioning and limitations
The path version is v1. Formal deprecation governance and migration guides are PLANNED; consult the changelog before upgrades. Product reads do not include category resources. Order reads do not include a public line-item contract. Response fields are defined by the OpenAPI reference and may be narrower than internal commerce models.