Storefront API
Build a headless store
A complete store front end on your own stack, with Ordexs keeping the catalogue, prices, delivery and orders.
A headless store is your own website or app — any framework, any host — that shows an Ordexs store's catalogue and sends its orders to Ordexs. The merchant keeps managing everything in the Ordexs dashboard; your front end reads it live.
You need two credentials, kept in different places:
| Credential | Where it lives | What it does |
|---|---|---|
A Storefront API token (ordx_sf_…) | Your front end, in the browser | Reads the catalogue, prices a cart |
An API key (ordx_live_…) | Your server only | Places the order |
Ask the store for both (Settings → Developers). For the token, the store lists your website's address (for example https://shop.example.com) so only your site can use it from a browser.
1. The catalogue
Read the store once for its currency and language, then list products. Every answer is edge-cached and refreshed within seconds of the merchant changing something, so you can fetch on each page view, or cache on your side as well.
const BASE = 'https://api.ordexs.com/storefront/v1/atelier-nour'
const HEADERS = { 'X-Ordexs-Storefront-Token': 'ordx_sf_…' }
const sf = (path, init) => fetch(`${BASE}${path}`, { ...init, headers: { ...HEADERS, ...init?.headers } }).then(async (res) => {
const body = await res.json()
if (!res.ok) throw new Error(body.error?.message ?? `HTTP ${res.status}`)
return body
})
const store = await sf('/store') // currency, direction, logo…
const nav = await sf('/navigation') // menus
const home = await sf('/products?limit=12') // newest productsFormat money with the store's own decimals: amount is already a decimal string in store.currency.code, so Intl.NumberFormat(locale, { style: 'currency', currency: amount.currency }).format(Number(amount.amount)) is enough for display.
2. Collection pages with filters
One request gives a collection and its first page; a second gives the filter menu with counts.
const filters = { 'option.Size': 'M', available: 'true', sort: 'price_asc' }
const [collection, facets] = await Promise.all([
sf(`/collections/dresses?${new URLSearchParams(filters)}`),
sf('/facets?collection=dresses'),
])
// Next page: sf(`/collections/dresses?${new URLSearchParams({ ...filters, cursor: collection.products.next_cursor })}`)3. Search
Show suggestions while the shopper types, and full results on submit:
let timer
input.addEventListener('input', () => {
clearTimeout(timer)
timer = setTimeout(async () => {
if (input.value.length < 2) return
const { products, collections } = await sf(`/search/suggest?q=${encodeURIComponent(input.value)}`)
render(products, collections)
}, 200)
})
// On submit: sf(`/products?q=${encodeURIComponent(query)}&sort=relevance`)4. The product page
const product = await sf('/products/linen-dress')
const reviews = await sf('/reviews?product=linen-dress&limit=5')
const offers = await sf('/offers?product=linen-dress')Pick the variant from product.variants by its options. Show available: false variants as sold out; exact stock is never in the answer.
5. The cart and the real price
Keep the cart on your side (variant ids and quantities). Whenever it changes — and always before the shopper confirms — ask Ordexs for the price. It runs the same calculation an order will, offers included, so the number you show is the number the order will have.
const regions = await sf('/regions')
const quote = await sf('/cart/price', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
lines: cart.map((l) => ({ variant_id: l.variantId, quantity: l.quantity })),
region: shopper.region, // a code from /regions
delivery_mode: 'home', // or 'pickup_point'
}),
})
showTotal(quote.total) // what the order will cost, delivery includedNever compute totals yourself from list prices: offers, delivery and rounding are applied by the quote.
6. Place the order (your server)
The Storefront API never writes. Your server places the order with the store's API key through the Ordexs API — POST /v1/orders with the shopper's name, phone, region, city and the same lines. The API prices the order again on its side, so a tampered browser can't change what is charged.
curl -X POST https://api.ordexs.com/v1/orders \
-H "Authorization: Bearer $ORDEXS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "customer": { "name": "Sara B.", "phone": "+213550000000" },
"shipping_address": { "region": "16", "city": "Bab Ezzouar" },
"delivery": { "mode": "home" },
"line_items": [{ "variant_id": "var_52f9c14cbdae4b7caf1fc04955623056", "quantity": 2 }] }'The orders guide has the full body and the webhooks tell your server when the order's status changes.
Checklist
- The token is in the
X-Ordexs-Storefront-Tokenheader, never in the address. - The API key is only on your server.
- The total the shopper confirms comes from
POST /cart/price. - Product links use the
pathfrom the answers, under your own domain. - When you get
429, back off for the seconds inRetry-After.
