API reference & integration guide

EASYSTORE API v1

EasyStore 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

GET/v1/products
Publishable key. Active products with variants, images and live availability.
GET/v1/products/:slug
Publishable key. Look up by slug or product ID.
ParamTypeDescription
limitintegerItems to return (default 20, max 100)
cursorstringPass the previous next_cursor
categorystringFilter by category slug or ID
statusstringOnly 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

GET/v1/categories
Publishable key. Active categories; parent is the parent category ID or null.
GET/v1/collections/:slug/products
Publishable key. Products in a manual or automated collection, in the same shape as /v1/products.
{
  "object": "list",
  "data": [
    { "id": "...", "object": "category", "name": "Apparel", "slug": "apparel", "description": "", "parent": null }
  ],
  "has_more": false,
  "next_cursor": null
}

Cart & stock holds

POST/v1/cart
Publishable key. Create an empty cart.
POST/v1/cart/items
Body {cart_id?, variant_id, quantity, coupon_code?}. Creates the cart when cart_id is omitted (201), reserves stock and returns the priced cart.
DELETE/v1/cart/items/:variant_id?cart_id=
Removes the item and releases its reserved stock.
GET/v1/cart/:id
Returns the cart with current prices.
{
  "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

GET/v1/campaigns
Publishable or secret key (promotions:read). Live flash sales: name, percent off, scope, end date. Products also carry sale_price and sale while a sale is live.
GET/v1/discounts
Live automatic discounts (percentage, fixed or free shipping) with their minimum spend, so a storefront can show "Free shipping over $50".
POST/v1/coupons/validate
Publishable key. Body {code, cart_id?, email?, subtotal?}. Always answers 200 with valid, a reason and the exact discount_amount when a cart is given.
POST/v1/cart/:id/coupon
Body {code} attaches a coupon to a cart; an empty code removes it. Returns the priced cart or 422 invalid_coupon.

Checkout sessions

POST/v1/checkout/session
Publishable key. Body {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

POST/v1/orders/lookup
Publishable key (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

GET/v1/orders
Secret key (orders:read). Filters: status (payment status) and email.
GET/v1/orders/:id
Secret key. Look up by order ID or number (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

GET/v1/customers
Secret key (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.

PlanRequests / monthRequests / hour
Developer1,000300
Growth100,0005,000
Scale1,000,00020,000
EnterpriseUnlimitedUnlimited

Errors share one shape:

{ "error": { "code": "out_of_stock", "message": "Not enough stock available" } }
StatuscodeMeaning
400invalid_requestMissing or malformed parameter
401invalid_keyMissing, unknown or revoked key, or wrong X-Store-Id
403insufficient_scopeKey type or scope cannot use this endpoint
404not_foundUnknown product, cart (including expired carts), order or customer
409conflictDuplicate record, for example an existing coupon code
409out_of_stockNot enough available stock to reserve
422invalid_couponCoupon unknown, expired, used up or not eligible
429rate_limitedHourly or monthly plan quota reached (Retry-After: 60)
502stripe_errorStripe rejected the checkout session
503stripe_not_configuredStripe is not configured on the server