Headless Commerce API

You own the storefront. Sellrn owns the transaction. Your site or app can live on Vercel, Netlify, your own servers, or the App Store — and every cart, price, checkout and order still runs on Sellrn, reached over HTTP with a store API key.

In practice that means there is no database to provision, no schema to keep in sync, no payment credentials to hold, and no PCI surface of your own.

What it covers

All endpoints live under /api/storefront/v1/:

• Catalog — /products, /products/:handle, /collections, /search
• Cart — /carts and its item routes
• Checkout — /checkout/quote, /checkout/reservation, /checkout/payment-intent
• Orders — /orders to place one, /orders/lookup to retrieve one
• Content — /snapshot, your published pages and theme

Available on Growth and above. Generate a key in Settings → Advanced.

Two credentials, and the difference matters

Authorization: Bearer <key> says which store is calling. X-Customer-Token says which shopper is browsing, and it is optional.

Send the shopper's token whenever you have one. Without it, an approved wholesale buyer is quoted retail prices — silently, with no error to notice. Their contract pricing and their access to trade-only products both depend on that header.

Keep the key server-side on the web

A standard API key can create carts and place orders. In browser code, anyone viewing your site can read it and order in your name. Call the API from server components, route handlers, or server actions — never from the client. The generated code export enforces this with a server-only import, so getting it wrong fails the build instead of leaking the key.

Mobile apps are different, because they have no server: anything shipped in a bundle can be extracted. For those, generate a public key. It is limited to what any visitor could already do — browse the public catalog, build a cart, check out — and cannot read orders or customers. It also cannot see wholesale or member-only products, because those depend on the shopper's own token rather than the store's key.

Never compute prices yourself

Prices and stock resolve live, per request, and differ per shopper. They are deliberately absent from the content snapshot and from the mobile manifest — not stale, not refreshed often, absent — so there is nothing that can drift out of date.

A total you calculate on your side is not the total that will be charged. Always price a cart through /checkout/quote and place the order against that quote.

Publishing controls content, not prices

Editing pages, copy, images or collections changes nothing publicly until you publish. Each publish mints a new snapshot version, and can fire a deploy hook so a statically built storefront rebuilds itself.

Prices and stock ignore publishing entirely. Change a price and it is live immediately, everywhere, without republishing.

Retrying safely

Send the same reservation_key when you retry placing an order. Sellrn replays the original order rather than creating a second one, so a lost response cannot double-charge a shopper. This matters most on mobile, where connections drop routinely.

A 409 means something changed — a price, stock, a discount — and the request is recoverable: re-quote and try again. It is not a failure.

Limits and billing

Your plan includes a number of orders per billing period. Passing it never blocks a sale. You are notified at 80% and again when you pass it, there is a seven-day grace window, and upgrading waives whatever has accrued — so upgrading is always cheaper than paying overage.

Rate limits are separate, and exist only to stop runaway loops and scrapers. They are never a billing gate. Checkout is never refused for billing reasons.

What is still beta

This API is graded beta, and honestly so. It has been proven by real orders placed from a foreign origin — including an approved wholesale buyer receiving contract pricing — but no exported storefront has yet been deployed to a live host and transacted end to end. If you are building on it now, expect to be an early adopter.

Protected commerce routes — cart, checkout, shop, account — ship as portability metadata rather than as prebuilt UI. You build those screens yourself against the generated client. Their behaviour lives behind the API, which is what lets it stay correct while you change everything around it.