A headless commerce API you host
The Merchant Engine is a REST API first. The storefront that ships with it is one client of that API, and the docs write down what any other client has to do: ten obligations, each shown as requests you can run. A Next.js, Nuxt or SvelteKit app, a native app or a script can be the storefront. The backend runs on your server, and you can read and change it.
How it works
One config call tells the storefront which store it is. GET /v1/store/config is public and
takes no parameters. It returns the store's identity, brand palette and font kit, locales and writing direction,
money format and domains. A storefront that renders from it fits any store the engine runs, instead of one store's
hard-coded currency and colours.
GET /v1/store/config
Accept-Language: en
{
"data": {
"identity": { "storeName": "Demo Store", "legalName": "Demo Store SAS", ... },
"brand": { "fontKit": "latin-rounded", "generatedPalette": { "tokens": { ... } }, ... },
"localization": {
"supportedLocales": ["en", "fr"],
"defaultLocale": "en",
"rtlLocales": [],
"timezone": "Europe/Paris"
},
"money": {
"currencyCode": "EUR",
"symbol": "€",
"symbolPosition": "after",
"decimalSeparator": ",",
"thousandsSeparator": " ",
"displayPrecision": 2,
"taxDisplay": "TTC",
"vatRate": 0.2
},
"domains": {
"storefront": "https://demo.example",
"admin": "https://admin.demo.example",
"api": "https://api.demo.example"
}
}
} The contract is ten obligations. Read the config first, send the locale header on every call, carry the
session and cart cookies, treat 304 as success, and six more. Each one names the files in the shipped
storefront that meet it, so you read working code instead of guessing. The conformance checklist turns the same
list into requests you run against your own client.
The spec comes from the code. npm run docs:generate exports two OpenAPI documents, one for the
storefront and one for the admin, and writes a REST Client .http file and a Postman collection with its
environment next to them. The storefront document lists 73 paths and the admin document 156. Every error, on either
side, has the same shape: { error: { code, message, details? } }.
What is not there. There is no GraphQL endpoint, and no SDK package to install: a client calls the REST routes directly. Card payment comes with Stripe only for now; more providers plug in behind one interface.
Paying by card from your own checkout. POST /v1/orders returns a paymentAction that
tells the client what to do next: none (cash on delivery, transfer, gift card), redirect,
form_post or embedded. A failed payment is retried with
POST /v1/orders/:id/payment, and the client confirms with
POST /v1/orders/:id/payment/confirm. Both calls need an X-Idempotency-Key. The provider
webhook stays the source of truth for the order's payment state.
Where to read the detail
- Build a storefront: the ten obligations, why each exists and the file that proves it.
- Conformance checklist: one request per obligation, and where the REST Client file and the Postman collection live.
- Framework notes: Next.js, Nuxt 3 and SvelteKit.
- Storefront API reference and admin API reference, generated from the OpenAPI documents.
- Error codes: every code the API can answer with, and its HTTP status.
Questions
Is the API REST or GraphQL?
REST over JSON. A success comes back as { data, meta? } and an error as { error: { code, message, details? } }. There is no GraphQL endpoint.
Do I have to use the storefront that ships with it?
No. The Analog.js storefront is one client of the API and the reference for the contract. You can replace it with your own, or run both against the same engine.
Which frameworks does it work with?
Any that can send an HTTP request. The flow pages use plain fetch, and the framework notes show what changes in Next.js (App Router), Nuxt 3 and SvelteKit: cookies at server render, the idempotency key on a retried action, fetch caches and the revalidation route.
How does a custom storefront sign customers in?
With cookies. Better Auth sets an HttpOnly session cookie and the cart sets its own, so the storefront never handles a token. In a browser it sends credentials: 'include'; on a server render it forwards the visitor's Cookie header and passes back every Set-Cookie.
Where is the API specification?
Two OpenAPI documents, one for the storefront and one for the admin, are exported from the code by npm run docs:generate. The same command writes a REST Client file and a Postman collection. The reference pages under /docs/reference/ are generated from those documents.
Last updated . Every claim on this page is read from a published source and cited beside it.