API reference & integration guide
EASYSTORE API v1EasyStore exposes a JSON REST API so any frontend (Next.js, Remix, Astro, mobile apps) can read the catalog, hold stock in a cart, start a Stripe checkout and, from your server, read orders and customers. Money is always an integer in the smallest currency unit (cents). The canonical reference is api/V1.md in the repository; this page mirrors it.
Quickstart
1. Create a store. Two default keys are created for it: publishable and secret. The secret is shown once, so copy it when you create it on the API Keys page.
2. Call the API from your frontend with the publishable key and your store's public ID (es_live_xxxxxxxxxxxxxxxx):
export API=https://api.example.com STORE=es_live_xxxxxxxxxxxxxxxx PK=pk_live_xxx curl -s "$API/v1/products?limit=10" \ -H "Authorization: Bearer $PK" -H "X-Store-Id: $STORE"
3. Or let your AI agent do it: the AI Integration page in your dashboard generates a prompt with your keys and these endpoints filled in. A typed fetch helper looks like this:
const API = process.env.NEXT_PUBLIC_EASYSTORE_API!;
const headers = {
Authorization: `Bearer ${process.env.NEXT_PUBLIC_EASYSTORE_PK}`,
"X-Store-Id": process.env.NEXT_PUBLIC_EASYSTORE_STORE!,
};
const res = await fetch(`${API}/v1/products?limit=12`, { headers });
const { data: products } = await res.json();4. Add to cart, then create a checkout session and redirect the buyer to checkout_url. See the cart and checkout sections below.
Authentication & keys
Every request needs the two headers below. Replace the placeholders with your key and store ID. The API is served by your PocketBase host (https://api.example.com in these examples) and browsers can call it directly.
Authorization: Bearer pk_live_xxxxxxxx X-Store-Id: es_live_xxxxxxxxxxxxxxxx Content-Type: application/json
Publishable keys (pk_live_...) are safe in browser code: catalog, cart, checkout and events. Secret keys (sk_live_...) are server-only: orders and customers. Only a hash of the secret is stored. Publishable scopes: products:read, promotions:read, cart:write, checkout:write, events:write, orders:lookup. Secret scopes: orders:read, orders:write, customers:read, products:write, inventory:read, inventory:write, promotions:read, promotions:write, metrics:read. Create and revoke keys on the API Keys page.
List endpoints accept limit (1 to 100, default 20) and cursor (the previous next_cursor) and return:
{ "object": "list", "data": [ ... ], "has_more": true, "next_cursor": "20" }Products & variants
| Param | Type | Description |
|---|---|---|
limit | integer | Items to return (default 20, max 100) |
cursor | string | Pass the previous next_cursor |
category | string | Filter by category slug or ID |
status | string | Only active products are public |
{
"object": "list",
"data": [
{
"id": "prod_xxx",
"object": "product",
"title": "Technical Oversized Tee",
"slug": "technical-oversized-tee",
"status": "active",
"price": 4800,
"category": { "id": "...", "name": "Apparel", "slug": "apparel" },
"images": ["https://api.example.com/api/files/..."],
"variants": [
{ "id": "var_xxx", "object": "variant", "title": "Black / M", "sku": "TEE-BLK-M",
"price": 4800, "option_values": { "Color": "Black", "Size": "M" }, "available": 42 }
]
}
],
"has_more": false,
"next_cursor": null
}A variant's available is its on-hand stock minus units reserved in carts and open checkouts.
Categories & collections
parent is the parent category ID or null./v1/products.{
"object": "list",
"data": [
{ "id": "...", "object": "category", "name": "Apparel", "slug": "apparel", "description": "", "parent": null }
],
"has_more": false,
"next_cursor": null
}Cart & stock holds
{cart_id?, variant_id, quantity, coupon_code?}. Creates the cart when cart_id is omitted (201), reserves stock and returns the priced cart.{
"id": "cart_xxx",
"object": "cart",
"status": "open",
"currency": "usd",
"expires_at": "2026-01-01 12:10:00.000Z",
"items": [
{ "variant_id": "var_xxx", "title": "Black / M", "quantity": 2, "unit_price": 4800, "total": 9600 }
],
"coupon_code": "SAVE10",
"subtotal": 9600,
"discount_total": 960,
"shipping_amount": 0,
"tax_amount": 0,
"total": 8640
}Carts hold stock for 10 minutes after the last change, and an expired cart returns 404. Prices (campaigns, automatic discounts, coupons, tax) are computed on the server on every cart call and again at checkout. An invalid coupon is reported in coupon_error. Not enough stock returns 409 out_of_stock.
To feed the dashboard funnel, send POST /v1/events with {type, session_id} where type is visit, pdp_view, add_to_cart or checkout_started.
Sales, discounts & coupons
promotions:read). Live flash sales: name, percent off, scope, end date. Products also carry sale_price and sale while a sale is live.{code, cart_id?, email?, subtotal?}. Always answers 200 with valid, a reason and the exact discount_amount when a cart is given.{code} attaches a coupon to a cart; an empty code removes it. Returns the priced cart or 422 invalid_coupon.Checkout sessions
{cart_id, email, success_url, cancel_url}. Creates a pending order and a Stripe Checkout Session.{
"object": "checkout.session",
"order_id": "ord_xxx",
"order_number": "ES-1001",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
"total": 8640,
"currency": "usd"
}Redirect the buyer to checkout_url. Stock stays reserved until Stripe reports payment (checkout.session.completed) or the session expires (checkout.session.expired). Stripe errors return 502 stripe_error; a store that selected Stripe but has not connected it returns 503 stripe_not_configured. Stores in manual mode skip Stripe: the response has payment_mode: "manual" and a null checkout_url, and the order stays unpaid until the owner marks it paid. Store owners connect their own Stripe keys in Settings > Payments.
// app/orders/page.tsx (server component, secret key stays on the server)
export default async function Orders() {
const res = await fetch(`${process.env.EASYSTORE_API}/v1/orders?limit=20`, {
headers: {
Authorization: `Bearer ${process.env.EASYSTORE_SECRET_KEY}`,
"X-Store-Id": process.env.EASYSTORE_STORE_ID!,
},
cache: "no-store",
});
const { data } = await res.json();
return <pre>{JSON.stringify(data, null, 2)}</pre>;
}Order lookup & history
orders:lookup). Body {number: "ES-1001", email}. Returns the order only when both match, so it is safe in the browser for confirmation pages and a guest "find my order" form.For logged-in shoppers, verify the shopper on your own server, then call GET /v1/orders?email=... or GET /v1/customers/:id (which includes the customer's orders) with a secret key. Never call these from the browser.
Orders
orders:read). Filters: status (payment status) and email.ES-1001).{
"object": "list",
"data": [
{
"id": "ord_xxx",
"object": "order",
"number": "ES-1001",
"email": "buyer@example.com",
"payment_status": "paid",
"fulfillment_status": "unfulfilled",
"currency": "usd",
"subtotal": 9600,
"discount_total": 960,
"total": 8640,
"tracking_number": ""
}
],
"has_more": false,
"next_cursor": null
}Orders are created when a checkout session is made and become paid when Stripe confirms payment. Fulfilment, tracking and refunds are managed from the dashboard and reflected in fulfillment_status and tracking_number.
Customers
customers:read). Optional email filter.{
"object": "list",
"data": [
{
"id": "...",
"object": "customer",
"email": "buyer@example.com",
"name": "Sarah Jenkins",
"orders_count": 3,
"total_spent": 21400,
"last_order_at": "2026-01-01 12:00:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}Customers are created automatically from paid orders, keyed by lower-cased email. total_spent is in cents.
Admin API (write)
Secret-key endpoints for scripts, back-office tools and AI agents: POST/PATCH/DELETE /v1/products, /v1/products/:id/variants, /v1/variants/:id (products:write); GET /v1/inventory and POST /v1/inventory/adjust (a relative delta or an absolute on_hand); POST /v1/orders/:id/fulfill|cancel|mark-paid (orders:write); CRUD on /v1/discounts, /v1/coupons and /v1/campaigns (promotions:write); and GET /v1/metrics?range=7d. Refunds, categories, collections, webhooks, keys and settings stay in the dashboard.
AI guide
Give your coding agent one URL: GET /v1/guide returns a complete Markdown guide (every endpoint, object shape, recipe and pitfall), and GET /v1 returns the same endpoint list as JSON. Neither needs authentication. The integration prompt in the dashboard already points the agent at it.
Webhooks
EasyStore POSTs a signed JSON event to every active endpoint subscribed to it. Manage endpoints on the Webhooks page; the whsec_... signing secret is shown once. Events: order.created, order.updated, payment.completed, inventory.updated, inventory.low, customer.created, refund.created.
POST <your url>
content-type: application/json
x-easystore-signature: t=1775702400,v1=<hex hmac>
x-easystore-event: order.created
{ "id": "evt_...", "event": "order.created", "created_at": 1775702400, "data": { "order": { ... } } }Verify v1 = hex(HMAC_SHA256(secret, "<t>." + raw body)) using the raw body, compare in constant time and reject old timestamps. The event id is stable across retries, so use it to deduplicate. Any 2xx response is a success (5 second timeout); otherwise delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours (six attempts in total). Full details and a Next.js verification example are in api/WEBHOOKS.md.
Rate limits & errors
Every request is counted against a monthly quota and a rolling hourly cap for your plan, and logged with its latency. Over the limit, the API returns 429 with Retry-After: 60.
| Plan | Requests / month | Requests / hour |
|---|---|---|
| Developer | 1,000 | 300 |
| Growth | 100,000 | 5,000 |
| Scale | 1,000,000 | 20,000 |
| Enterprise | Unlimited | Unlimited |
Errors share one shape:
{ "error": { "code": "out_of_stock", "message": "Not enough stock available" } }| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing or malformed parameter |
| 401 | invalid_key | Missing, unknown or revoked key, or wrong X-Store-Id |
| 403 | insufficient_scope | Key type or scope cannot use this endpoint |
| 404 | not_found | Unknown product, cart (including expired carts), order or customer |
| 409 | conflict | Duplicate record, for example an existing coupon code |
| 409 | out_of_stock | Not enough available stock to reserve |
| 422 | invalid_coupon | Coupon unknown, expired, used up or not eligible |
| 429 | rate_limited | Hourly or monthly plan quota reached (Retry-After: 60) |
| 502 | stripe_error | Stripe rejected the checkout session |
| 503 | stripe_not_configured | Stripe is not configured on the server |