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 and orders:read. Requires Idempotency-Key. The answer reads the order back, so a key holding orders:write alone gets the order saved and a 403 forbidden answer, and a retry with the same Idempotency-Key replays that 403.

The order is created in pending status. By default 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. A store whose Orders → Display settings → Stock deduction is set to As soon as the order arrives has its stock taken when the API creates the order instead.

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 (never below 0), where shipping_cost is the server's own quote. subtotal itself is sum(items[].quantity × (price + Σ variants.price_adjustment)).

Only discount is taken from your body. It must be ≥ 0, is capped at the subtotal plus shipping, and is not checked against your store's promo codes, 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 Idempotency-Key, same API key, same body bytes) within 24 h we return the same response with Idempotency-Replay: 1, so the order is created exactly once. Error answers are replayed too, except 429 and 5xx, and the same Idempotency-Key with a different body answers 422 idempotency_key_reuse: send a corrected order with a new key. 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:

The merchant does get the usual new-order notification, the same one a storefront order sends.

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: key with orders:read (part of the default scopes). A key without it gets 403 forbidden "Missing scope: orders:read".

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: key with orders:read. A key without it gets 403 forbidden.

store_seq is the order number the merchant sees in the dashboard (#644); an API create numbers the order before it answers, and in the rare case numbering fails it reads null until it is filled shortly after. shipment.sent_to_delivery turns true once a courier accepted the parcel; delivery_company is the courier slug and delivery_tracking its tracking number. shipment.last_send_failure is the most recent refused send for this order, { "at", "provider", "message" } with the courier's own message, or null when no send failed. It is always null once sent_to_delivery is true, so an earlier failure stops showing after a successful send. The same object is returned by create, update and cancel.

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 and orders:read. Requires Idempotency-Key. Without orders:read the status still changes, but the answer is 403 forbidden.

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 and orders:read. Requires Idempotency-Key. Without orders:read the order is still cancelled, but the answer is 403 forbidden.

Hands the order to the store's courier, the same send as the button in the dashboard. A parcel cannot be recalled once the courier has it, so every send takes two calls and the merchant approves the first one.

Auth: key with delivery:send. Requires Idempotency-Key. Keys created at Settings → API do not carry this scope and get 403 forbidden; an app gets it when the merchant approves it at install.

The send normally runs in the background and answers 202 with queued: true. Read GET /v1/orders/{id} until shipment.sent_to_delivery is true with a delivery_tracking, or until shipment.last_send_failure shows the courier's refusal. If the background runner is unavailable the send happens inside the request instead: 200 with sent, provider and tracking, or 422 courier_refused with the courier's message. Once the courier accepts the parcel, a pending or confirmed order moves to processing, which takes the stock if it was not taken yet. Orders with delivery type pickup are never handed to a courier. A background send stopped before the courier is called, such as one for a pickup order or for a courier that is not linked, still answers 202 and changes neither shipment field.

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), or at create on a store that deducts stock as soon as the order arrives, 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.). GET /v1/products/{id} returns them in combinations[] (each with id, sku, stock, is_active and its options), with combination_count; the list stops at 300 entries and combinations_truncated tells you when it was cut. See Products. Combination stock moves at the same moment as the rest of the order's stock.

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.