Orders are the heart of the platform. Every order:

That is the exact transition map the API enforces, per state:

Cancellation is legal only from pending, confirmed and processing — a shipped or delivered order can no longer be cancelled.

PATCHing an order to the status it already has is a 200 no-op.

cancelled and returned are terminal — you cannot transition out of them.

Create a new order for the calling store. Used by custom themes, mobile / native apps, resellers, and any headless storefront that submits orders from its own server instead of using the built-in storefront checkout.

Auth: platform key with orders:write. Requires Idempotency-Key.

The order is created in pending status. Stock is NOT committed at create time — the first move into a committed state (confirmed, processing, shipped or delivered) is what decrements stock, same as the dashboard flow. This is intentional: it lets your operations team filter out fake / duplicate / no-answer orders before any inventory is touched.

Customers are deduped by store + phone. If a customer with this phone already exists in your store, their record is updated (name, wilaya, commune, address, email) and reused. If not, a new customer record is created.

Important — server-authoritative pricing. You do not specify the line price. The product's current catalogue price is always used. If you send a price field, it is ignored.

Each variant's price_adjustment is server-authoritative too: for every (group_name, option_name) pair that matches a real option on the product, DZBuild substitutes the catalogue's own price_adjustment. Your value survives only for pairs that don't exist in the catalogue — a fail-open for stale integrations — so a negative "discount" you invent is silently discarded for any real option. Treat price_adjustment as informational on input: echo the value from GET /v1/products/{id} so your client-side total matches the server's.

Each variant object describes a chosen option for a variant group on the product:

Send one variant object per chosen group for that line item. So a "Red T-shirt size L" becomes 2 variant entries (one for Color/Red, one for Size/L). DZBuild renders these on the dashboard order page exactly the same way as if a customer picked them on the storefront.

For products using per-piece variants (e.g. a "buy 3 t-shirts, pick a color for each" offer), use quantity = 1 per line and create one line per piece — that's the cleanest mapping.

Total is computed server-side as subtotal + shipping_cost - discount + payment_fee (clamped to 0). subtotal itself is sum(items[].quantity × (price + Σ variants.price_adjustment)).

shipping_cost, discount and payment_fee are taken exactly as sent — the only check is that each is ≥ 0. They are not validated against your store's shipping rates or coupons, so POST /v1/orders must only ever be called from a trusted server, never from browser or app code a customer can tamper with.

Order creation returns HTTP 200, not 201 — do not branch on the status code; check data.id / data.order_number instead. The body is the same shape as GET /v1/orders/{id} — fully populated with computed totals, normalized customer block, and the line items you just created (with their variants).

order_number has the format ORD-{store_id}-{YYYYMMDD}-{8 uppercase hex}. Landing-page orders use LP-{8 uppercase hex}. Orders created before 2026-06-02 carry a legacy 4-hex suffix, so a parser must accept both lengths.

Monthly order limit. The Free plan is capped at 30 orders per calendar month; Pro, Unlimited and Enterprise are uncapped. An unrecognised plan name also falls back to the 30/month free cap. The counter is calendar-month and covers all order sources (storefront + landing page + dashboard + API).

Every POST must carry an Idempotency-Key header. If you retry the same request (same key, same store) within 24 h we return the same response — the order is created exactly once. See Idempotency.

Creating an order fires order.created to all /v1/webhooks subscriptions for that event. See Webhook events.

⚠️ Warning — /v1/webhooks only sees API activity

/v1/webhooks subscriptions fire only for changes made through the v1 API. Orders placed on the storefront or a landing page, and status changes made in the dashboard, do not fire order.created / order.confirmed / order.shipped.

For events covering all order activity, use the Webhooks addon (/dashboard/addons → "Webhooks — Connect n8n, Make & Zapier", requires the Unlimited plan), which picks up every order regardless of where it came from — or keep polling GET /v1/orders?since=….

An order created through the API is a lean insert. Compared with a storefront, landing-page or dashboard order, it does not:

Also note that a customer created by the API stores the whole customer.name string in first_name and leaves last_name empty; for an existing customer matched by phone, only first_name is overwritten and any existing last_name is left untouched.

List orders. Cursor-paginated.

Auth: any active platform key for the store (orders:read is granted by default and is not separately enforced at v1; only orders:write is checked, on the write endpoints).

An invalid status or an unparseable since is silently ignored — you get the unfiltered list, not a 400. There is no payment_status filter at v1; filter client-side.

The list view is intentionally compact (no items, no variants). Call GET /v1/orders/{id} for the full detail.

Full detail with line items, variants, and customer block.

Auth: any active platform key for the store (orders:read is not separately enforced at v1).

The variants array on each item is the source of truth for what the customer picked. Each entry has order_item_id, group_name, option_name, color_code (for color variants), and price_adjustment (the per-piece add-on price, returned as a JSON string, not a number). For multi-piece offers, you may see multiple variant entries on the same item with different effective groupings — see the per-piece notes below.

Product add-ons (the paid custom-field extras a merchant configures on a product) have no v1 surface: you cannot send them on POST /v1/orders, and GET /v1/orders/{id} returns no add-on entries. An order placed on the storefront with add-ons reads back through the API with the add-on money already baked into items[].price (and therefore amounts.subtotal) — but with no add-on line, title or file attribution.

Auth: platform key with orders:write. Requires Idempotency-Key.

Body must be {"status": "<one of the 7>"}. We validate the transition against the table in Lifecycle; otherwise we return 400 with the legal next states. PATCHing to the order's current status is a 200 no-op.

Returns 200 and the updated order detail. Concurrent transitions on the same order are serialised: if another request changed the status first, yours fails cleanly with bad_request ("order status changed concurrently; retry") instead of applying twice.

The committed-stock states are confirmed, processing, shipped and delivered.

Stock is not validated: the decrement clamps at zero, so overselling is never rejected, and a stock problem never fails or reverts the status change. Stock behaves exactly as it does for orders managed from the dashboard.

Convenience endpoint — exactly equivalent to PATCH /v1/orders/{id} with {"status":"cancelled"}. Same transition table, no extra permission. Cancellation is legal only from pending, confirmed and processing; from shipped or delivered you get 400 bad_request (those states can only go to delivered / returned).

Auth: platform key with orders:write. Requires Idempotency-Key.

Variants make a single product cover multiple options (color, size, material, capacity, …). On the storefront, customers click variant cards to choose what they want; on the API, you send the chosen options as part of the order.

A product has 0+ variant groups. A group has 0+ options. Each option can have:

Read GET /v1/products/{id} to see all groups and options for a product:

A product with 2 colors × 3 sizes has 6 combinations.

Convert the customer's selection into one variant entry per chosen group. For a "Red T-shirt, size L":

The names you send are stored exactly as-is on the order — they should match what GET /v1/products/{id} returned. price_adjustment is added to the line price (so final_price = product.price + Σ price_adjustment), but for any pair that exists in the catalogue the server substitutes its own value, so send the catalogue's number.

If the merchant has enabled variant_stock_enabled on a product, each variant option carries its own stock counter. Read it from options[].stock. The API itself does not block you from creating an order with quantity > stock — that's the merchant's call. Stock is decremented on the first move into a committed state (confirmed, processing, shipped, delivered) and is never validated: the decrement clamps at zero, so an oversell is recorded rather than rejected.

If combination_stock_enabled is on, stock is tracked per combination (Red+L = 5 units, Red+M = 8, etc.). Combinations are not exposed on the public products endpoint yet (they will be in v1.1 as a combinations[] array on GET /v1/products/{id}/combinations). For now, per-combination stock is applied when the order is confirmed and is visible in the dashboard.

The Cascading Variants add-on lets a merchant make Group B's options depend on Group A's selection (e.g. "Brand → Model" — picking "Apple" for Brand only shows "iPhone 15" / "iPhone 14" for Model). The add-on requires the Pro plan.

GET /v1/products/{id} exposes no cascade information — the parent/child mapping is only applied on the storefront and in the dashboard. Your client cannot discover cascade rules through the API at v1: hard-code them, or read them from the dashboard. Sending an invalid combination still creates the order (we don't block it) — but the merchant will reject it on confirm.

Some merchants use the image_text variant type (a thumbnail next to the option label). On the API, you still send group_name + option_name — the image is purely a storefront concern and is not part of the order payload.

If the merchant runs a "Buy 3, mix colors" offer, the customer picks a different variant for each piece. On the API:

Three separate line items, each quantity = 1. This way the dashboard order page renders each piece's color cleanly.

You're building a React/Vue/Next.js storefront that talks to the API instead of using DZBuild's built-in storefront themes. Flow:

See the Custom themes & storefronts guide for a full end-to-end walkthrough.

Use the since filter:

Polling is the right tool here. A /v1/webhooks subscription on order.created only covers orders your own integration created through the API — storefront and landing-page orders never fire it, so it cannot replace the since sweep. See Webhooks.