Ordexs API v1 Get an API key

Storefront API

Storefront API reference

Every Storefront API endpoint, its parameters and an example answer.

Every path below is relative to https://api.ordexs.com/storefront/v1/<store> (with the X-Ordexs-Storefront-Token header), or to https://<store>.myordexs.com/api/storefront/v1 on the store's own address (no token). The examples use the store atelier-nour and $TOKEN for your token. The machine-readable contract is the OpenAPI file.

Store

Get the store

GET /store — name, logo, language and direction, currency with its decimals, country, contacts, social links and payment methods.

curl https://api.ordexs.com/storefront/v1/atelier-nour/store -H "X-Ordexs-Storefront-Token: $TOKEN"
{
  "object": "store",
  "name": "Atelier Nour",
  "handle": "atelier-nour",
  "url": "https://atelier-nour.myordexs.com",
  "logo": "https://cdn.myordexs.com/…/logo-640.webp",
  "language": "ar",
  "direction": "rtl",
  "currency": { "code": "DZD", "decimals": 2 },
  "country": "DZ",
  "accepting_orders": true,
  "contact": { "email": "hello@atelier-nour.example", "phone": "0550 00 00 00", "city": "Oran" },
  "social": [{ "network": "instagram", "label": "Instagram", "url": "https://www.instagram.com/ateliernour/" }],
  "payment_methods": ["cash_on_delivery"]
}

Get the navigation

GET /navigation — the store's menus as its themes build them: main (the catalogue and collections) and footer (footer pages and policies). Each item has a kind (catalog, collection, page, landing_page, policy), a handle and a path.

Products

List and search products

GET /products — published products, newest first. Unlisted products never appear in lists (they still open by handle).

ParameterMeaning
qSearch text, matched against titles (≤ 80 characters).
collectionA collection handle. Sort then defaults to the merchant's order.
categoryA category key from /categories.
tag, vendorExact tag or vendor.
min_price, max_priceDecimal strings in the store's currency.
availabletrue: only products a shopper can order now.
option.<Name>Option values, comma-separated: option.Size=M,L&option.Colour=Sand. Up to 8 options, 20 values each.
sortnewest (default), oldest, price_asc, price_desc, title, relevance (needs q), collection (needs collection).
limit1–100, default 24.
cursornext_cursor from the previous page.
curl "https://api.ordexs.com/storefront/v1/atelier-nour/products?collection=dresses&option.Size=M&available=true&sort=price_asc&limit=24" \
  -H "X-Ordexs-Storefront-Token: $TOKEN"
const params = new URLSearchParams({ collection: 'dresses', 'option.Size': 'M', available: 'true', sort: 'price_asc' })
const page = await fetch(`https://api.ordexs.com/storefront/v1/atelier-nour/products?${params}`, {
  headers: { 'X-Ordexs-Storefront-Token': TOKEN },
}).then((r) => r.json())
{
  "object": "list",
  "data": [{
    "object": "product",
    "id": "3f2b1c0e-8d4a-4b7f-9c1e-2a5d6e7f8a90",
    "handle": "linen-dress",
    "title": "Linen dress",
    "path": "/products/linen-dress",
    "price": { "min": { "amount": "4500.00", "currency": "DZD" }, "max": { "amount": "4900.00", "currency": "DZD" } },
    "compare_at_price": { "amount": "5900.00", "currency": "DZD" },
    "available": true,
    "image": { "url": "https://cdn.myordexs.com/…/linen-dress-1024.webp", "alt": "Linen dress" },
    "images_count": 5,
    "category": { "key": "dresses", "name": "Dresses" },
    "vendor": "Atelier Nour",
    "tags": ["summer"],
    "options": [{ "name": "Size", "kind": "size", "values": ["S", "M", "L"] }],
    "reviews": { "count": 12, "average": 4.6 }
  }],
  "has_more": true,
  "next_cursor": "eyJzIjoicHJpY2VfYXNjIn0"
}

Get a product

GET /products/{product} — by handle, id or prod_… id. Adds description_html (sanitised), description_text, product_type, seo, every image in order, the variants (each with id, title, options, price, compare_at_price, available, preorder, image) and the product's collections. Exact stock is never shown: only whether a variant can be ordered now.

curl https://api.ordexs.com/storefront/v1/atelier-nour/products/linen-dress -H "X-Ordexs-Storefront-Token: $TOKEN"

Filter facets

GET /facets — what a filter menu can offer, with counts, for the products in scope (q, collection, category): categories, vendors, tags (top 50), the price range, and every option's values. Bounded to the newest 5,000 products in scope.

{
  "object": "facets",
  "products": 42,
  "categories": [{ "key": "dresses", "name": "Dresses", "count": 18 }],
  "vendors": [{ "value": "Atelier Nour", "count": 9 }],
  "tags": [{ "value": "summer", "count": 12 }],
  "price": { "min": { "amount": "1900.00", "currency": "DZD" }, "max": { "amount": "8900.00", "currency": "DZD" } },
  "options": [{ "name": "Size", "values": [{ "value": "M", "count": 30 }, { "value": "L", "count": 27 }] }]
}

Suggest as the shopper types

GET /search/suggest?q=lin — up to 6 products and 4 collections whose title matches (q needs 2 characters). Debounce your search box (about 200 ms) and show these; send the full search to /products?q=…&sort=relevance.

Collections

List collections

GET /collections — in the merchant's order, with products_count. Paged with limit and cursor.

Get a collection and its products

GET /collections/{collection} — the collection (description_html, image, seo) and a page of its products, in the merchant's order unless sort says otherwise. Takes every /products filter, so a collection page with filters is one request.

List categories

GET /categories — the categories present in the catalogue with products_count. Filter products with category=<key>.

Pages and policies

  • GET /pages — published content pages and landing pages (kind: page or landing_page).
  • GET /pages/{page} — one page, content or landing: kind, path, body_html (sanitised), body_text, seo. A landing page is built from blocks, so its body is usually null; link to its path instead.
  • GET /policies — published policies.
  • GET /policies/{kind} — one policy, its body in body_markdown.

Reviews and offers

List reviews

GET /reviews?product=linen-dress — published reviews, newest first, the author's first name only. With product you also get that product's summary (count, average). limit up to 50.

List live offers

GET /offers?product=linen-dress — bundles, quantity tiers (upsell), cross-sells and free-delivery offers that are live now, with the products they include (role) and their tiers. Discount codes are never listed: they are the store's secrets, checked only at checkout.

Delivery

  • GET /regions — the regions of the store's country, with their code (send it back as region).
  • GET /regions/{region}/cities — that region's cities.
  • GET /delivery?region=16 — that region's options: home and/or pickup_point, each with its price and courier. Without region, every region's cheapest prices. With product, that product's own delivery settings apply. free_shipping_offers lists the offers that make delivery free.
{
  "object": "delivery_rates",
  "country": "DZ",
  "region": "16",
  "delivery_enabled": true,
  "modes": { "home": true, "pickup_point": true },
  "options": [
    { "mode": "home", "label": "Home delivery", "price": { "amount": "600.00", "currency": "DZD" }, "courier": "Yalidine" },
    { "mode": "pickup_point", "label": "Stop desk", "price": { "amount": "400.00", "currency": "DZD" }, "courier": "Yalidine" }
  ],
  "free_shipping_offers": [{ "offer_id": "b152e795-d2c9-4a52-883d-a36214da2d74", "name": "Free delivery from 3", "type": "upsell", "from_quantity": 3 }]
}

Price a cart

POST /cart/price — the server's price for a cart. It runs the same calculation an order goes through (bundle and tier offers included), so the total is exactly what the order will cost. Nothing is stored. Never cached.

FieldMeaning
lines1–50 of { "variant_id", "quantity" }, quantity 1–99. variant_id takes a UUID or a var_… id.
region, delivery_modeBoth together add delivery: a region code from /regions and home or pickup_point.
offer_idsOffers the shopper picked, such as a bundle (up to 20). Discount codes are not accepted here.
curl -X POST https://api.ordexs.com/storefront/v1/atelier-nour/cart/price \
  -H "X-Ordexs-Storefront-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [{ "variant_id": "52f9c14c-bdae-4b7c-af1f-c04955623056", "quantity": 2 }], "region": "16", "delivery_mode": "home" }'
{
  "object": "cart_price",
  "currency": "DZD",
  "lines": [{
    "variant_id": "52f9c14c-bdae-4b7c-af1f-c04955623056",
    "product_id": "3f2b1c0e-8d4a-4b7f-9c1e-2a5d6e7f8a90",
    "handle": "linen-dress",
    "title": "Linen dress",
    "variant_title": "M",
    "image": null,
    "quantity": 2,
    "unit_price": { "amount": "4500.00", "currency": "DZD" },
    "line_total": { "amount": "9000.00", "currency": "DZD" }
  }],
  "offers": [],
  "subtotal": { "amount": "9000.00", "currency": "DZD" },
  "discount": { "amount": "0.00", "currency": "DZD" },
  "shipping": { "amount": "600.00", "currency": "DZD" },
  "total": { "amount": "9600.00", "currency": "DZD" },
  "delivery": { "region": "16", "mode": "home", "label": "Home delivery" },
  "note": null
}

Without region and delivery_mode, shipping and delivery are null and note says delivery isn't included. If a line can't be priced you get 422 with variant_unknown, insufficient_stock (never a stock number), region_unknown, delivery_unavailable or store_closed.

Pagination

Lists are keyset-paged: ask for limit items, then pass next_cursor as cursor until has_more is false. A cursor is opaque and tied to the filters and sort it came from — change them and start again without one. Pages never repeat or skip an item when the store adds products while you page.