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).
| Parameter | Meaning |
|---|---|
q | Search text, matched against titles (≤ 80 characters). |
collection | A collection handle. Sort then defaults to the merchant's order. |
category | A category key from /categories. |
tag, vendor | Exact tag or vendor. |
min_price, max_price | Decimal strings in the store's currency. |
available | true: 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. |
sort | newest (default), oldest, price_asc, price_desc, title, relevance (needs q), collection (needs collection). |
limit | 1–100, default 24. |
cursor | next_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:pageorlanding_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 usuallynull; link to itspathinstead.GET /policies— published policies.GET /policies/{kind}— one policy, its body inbody_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 theircode(send it back asregion).GET /regions/{region}/cities— that region's cities.GET /delivery?region=16— that region's options:homeand/orpickup_point, each with itspriceand courier. Withoutregion, every region's cheapest prices. Withproduct, that product's own delivery settings apply.free_shipping_offerslists 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.
| Field | Meaning |
|---|---|
lines | 1–50 of { "variant_id", "quantity" }, quantity 1–99. variant_id takes a UUID or a var_… id. |
region, delivery_mode | Both together add delivery: a region code from /regions and home or pickup_point. |
offer_ids | Offers 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.
