Storefront API
Public, token-authenticated REST endpoints for your headless storefronts to read products and run cart & checkout.
Every request must include a per-site Storefront Token, generated by a workspace admin and scoped to a single site.
Authorization: Bearer sf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # or x-storefront-token: sf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Tokens authorize the storefront as the anon Postgres role; only products with is_public = true are returned. Carts and orders are written via a verified server route.
List products marked public for the storefront's site.
Response
{ "data": [{ "id":"...", "slug":"tee", "title":"Tee", "price":"29.00", "currency":"USD" }] }Fetch a single public product and its variants by slug.
Response
{ "data": { "id":"...", "title":"Tee", "variants":[...] } }Create an anonymous cart. Returns a cart token to use for subsequent calls.
Request body
{ "currency": "USD" }Response
{ "data": { "token":"abc123...", "currency":"USD", "subtotal":"0" } }Add a product (and optional variant) to the cart.
Request body
{ "product_id":"uuid", "variant_id":"uuid?", "quantity":1 }Response
{ "data": { "item": {...}, "subtotal":"29.00" } }Get the cart and its line items.
Response
{ "data": { "token":"...", "items":[...] } }Convert a cart into a pending order. Creates/links the customer.
Request body
{ "cart_token":"...", "customer": { "email":"a@b.co", "name":"Alex" } }Response
{ "data": { "order_number":"OC-XYZ", "total":"29.00", "status":"pending" } }products → product_variants (size/color, own price & stock)
carts → cart_items (token-addressed, anonymous)
orders → order_items (created on checkout, status pending)
storefront_tokens scope public access to a single site_id.