API · v1
Storeforma API
Two APIs on every store’s domain: the Integration API for accounting, ERPs and CRMs, and the Storefront API for your own storefronts and mobile apps. Every method with JSON examples, and on the right a console that sends requests straight to your store.
https://{store}/api/v1/integrations
Catalog, orders and content for an external system (ERP, PIM, CRM, accounting). Authenticated with an integration key whose abilities are chosen in the store admin. Available on the Pro plan and above.
First method →https://{store}/api/v1
Cart, shipping and checkout for your own storefront or a mobile app. A cart token identifies the buyer’s cart; the store’s own checkout runs on the same core, with the same rules and errors. Status: preview.
First method →Authentication
Integration API. Create a key in the store admin under API keys and choose its abilities. Send it with every request as Authorization: Bearer {key}. The Integration API is available on the Pro plan and above.
Storefront API. No key. POST /carts returns meta.cart_token; send it as X-Cart-Token with every cart, shipping and checkout call.
The store is the domain of the request: your-store.storeforma.shop or the store’s own domain.
Key abilities
| Ability | Methods |
|---|---|
catalog:read | GETList productsGETGet a product |
catalog:write | PUTCreate or replace a productPATCHUpdate part of a productPUTCreate or rename a categoryPUTCreate or rename a tag |
orders:read | GETList ordersGETGet an order |
orders:write-status | POSTChange an order status |
customers:read | GETList customersGETGet a customer |
inventory:write | PUTSet stock |
content:read | GETList pages and posts |
content:write | PUTCreate or update a draftPOSTPublish a pagePOSTUnpublish a page |
Data format
Requests and responses are JSON (Content-Type: application/json, Accept: application/json). Money is integer minor units: 49000 means 490.00. Integration API times are YYYY-MM-DD HH:MM:SS in the store’s time zone.
Pagination
Products page with page and limit (up to 50); the response has total and next_page_url. Orders and content use a cursor: pass the previous next_cursor as cursor until it is null.
Idempotency
Calls that change an order status or a publication, and checkout, need an Idempotency-Key header: a unique key per attempt (a UUID, say). Repeating the key returns the first response instead of acting twice; the same key for a different request is 409 (Integration) or 422 idempotency_key (checkout). Catalog and content upserts are idempotent by your external_id.
Errors
The Integration API answers in one shape: a code, a message and the field concerned.
{
"code": "validation_error",
"message": "name is required.",
"field": "name"
}
The Storefront API returns validation errors the Laravel way: a message and errors by field.
{
"message": "The quantity field must not be greater than 100.",
"errors": {
"quantity": [
"The quantity field must not be greater than 100."
]
}
}
| 401 | No key or cart token, or it was revoked. |
| 403 | The key lacks the ability, or the store’s plan has no API access. |
| 404 | Not found. |
| 409 | Idempotency-Key already used for another request. |
| 422 | Invalid request data. |
| 429 | Too many requests; wait Retry-After seconds. |
Rate limits
Integration API: 60 requests a minute per key; every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Storefront API: cart creation 20/min per IP, cart calls 120/min, checkout 10/min.
Webhooks
Instead of polling, subscribe to events in the store admin (Webhooks). The store sends a POST to your https address.
| Event | When |
|---|---|
product.created | A product is created |
product.updated | A product changes (name, description, prices, variants) |
product.deleted | A product is deleted |
inventory.updated | A variant’s stock changes |
order.created | An order is placed |
order.status_changed | An order’s status changes |
customer.created | A customer signs up |
Headers: X-Storeforma-Event, X-Storeforma-Delivery (delivery id) and X-Storeforma-Signature: sha256=…, the HMAC-SHA256 of the body with the subscription secret. Bursts of product and stock changes are collected for 30 seconds into one delivery with the latest state.
{
"id": "9b2f0c1e-…",
"event": "order.status_changed",
"created_at": "2026-10-12T16:20:45+03:00",
"data": {
"id": 1044,
"reference": "2026-001044",
"status": "dispatched",
"total": 214000,
"currency_code": "UAH"
}
}
// Verify the signature (Node.js)
import crypto from 'node:crypto';
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-storeforma-signature']));OpenAPI
The full contract for Postman, Insomnia or client generators:
openapi-integration.json openapi-storefront.json
Every store also serves its own copy with its address: https://{store}/api/docs/openapi.json, and a text one for AI agents at /api/docs.md.
Versioning
v1 may gain new fields and optional parameters, so write clients that ignore unknown fields. Renames, removals or a new required parameter only come in /api/v2, with a changelog entry.