Ordexs API v1 Get an API key

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:

CredentialWhere it livesWhat it does
A Storefront API token (ordx_sf_…)Your front end, in the browserReads the catalogue, prices a cart
An API key (ordx_live_…)Your server onlyPlaces 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 products

Format 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 })}`)

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 included

Never 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-Token header, 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 path from the answers, under your own domain.
  • When you get 429, back off for the seconds in Retry-After.