Popular

↑↓ move ↵ open All results →

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.

Integration API 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 →
Storefront API 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

AbilityMethods
catalog:readGETList productsGETGet a product
catalog:writePUTCreate or replace a productPATCHUpdate part of a productPUTCreate or rename a categoryPUTCreate or rename a tag
orders:readGETList ordersGETGet an order
orders:write-statusPOSTChange an order status
customers:readGETList customersGETGet a customer
inventory:writePUTSet stock
content:readGETList pages and posts
content:writePUTCreate 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."
        ]
    }
}
401No key or cart token, or it was revoked.
403The key lacks the ability, or the store’s plan has no API access.
404Not found.
409Idempotency-Key already used for another request.
422Invalid request data.
429Too 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.

EventWhen
product.createdA product is created
product.updatedA product changes (name, description, prices, variants)
product.deletedA product is deleted
inventory.updatedA variant’s stock changes
order.createdAn order is placed
order.status_changedAn order’s status changes
customer.createdA 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.