Guides
Start typing to search…

Order-based Checkout

What this is Order-based Checkout is the current integration path to build a working purchase flow in Djust. It is order-first: there is no technical cart. Buyers create a Draft Order, add/adjust lines, then place the order.

Who is this for

  • Customer integrators building buyer flows
  • Operators who need a high-level mental model
  • Anyone migrating from legacy “cart-centric” flows

🔑 Key ideas

  • Order-first: a Draft Order is the single source of truth during the checkout.
  • No technical cart: all actions (add/remove/quantity/addresses) happen on the draft order.
  • Editable only in DRAFT: lines, addresses, and metadata are mutable in DRAFT, then locked after placement.
  • Visibility applies: product visibility still follows Catalog Views for the Account.
  • Pricing & rules: pricing resolution and quantity constraints apply exactly as in the rest of the platform.
  • From a Quote/Operation: you can start a Draft from an eligible Quote/Opertion; lines are re-validated.

👥 Roles & headers

  • Buyer scope (storefront): uses the Account context.
  • Operator scope: can list/inspect; write actions depend on your policies.

Standard headers (no new ones)

HeaderRequiredNotes
dj-client✅ACCOUNT for buyer scope (storefront).
dj-api-key✅API key for authZ.
dj-store⭕️Optional store scoping.
dj-store-view⭕️Optional store-view scoping.

IDs are plain alphanumeric by default (not UUID) unless explicitly specified elsewhere.

For shop routes in general, use dj-client=ACCOUNT.

If store scoping is used, the caller must be attached to that store.

🧭 High-level flow

flowchart LR
  A[🏁 Start checkout]:::start --> B[🆕 Create Draft Order]:::create
  B --> C[✏️ Edit lines & metadata]:::update
  C --> V[🧪 Front validations<br>visibility & quantities]:::decision
  V -->|OK| S[✅ Place order]:::place
  V -->|Issues| FX[⚠️ Fix issues and retry]:::warn
  B -. optional .-> Q[🔗 Start from Quote or Operation<br>eligibility + mapping]:::source

  %% Styles
  classDef start fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef create fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef update fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef warn fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef source fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;

  class A start
  class B create
  class C update
  class V decision
  class S place
  class FX warn
  class Q source

  style A rx:8,ry:8
  style B rx:8,ry:8
  style C rx:8,ry:8
  style V rx:8,ry:8
  style S rx:8,ry:8
  style FX rx:8,ry:8
  style Q rx:8,ry:8

🔌 Start sources (Quote & Operation)

  • From a Quote

    Eligibility: quote valid (not expired), same Account, compatible Store/Store-view.

    Behavior: copy/mapping to a new Draft Order, then re-validate visibility, quantities, and pricing per policy.

    Rule: initialization is full only; out-of-stock lines are ignored.

  • From an Operation

    Eligibility: Operation is ACTIVE, within its date window, scoped to the buyer’s Store/Account; lines still visible via Catalog Views. Tenant flag OPERATIONS must be enabled.

    Behavior: initialize a Draft Order with Operation lines; lines are re-validated (visibility, quantity constraints, optional stock) and priced per standard rules.

For both paths, re-validation ensures today’s visibility and rules apply, not the historical state.

🔁 Lifecycle (short version)

  • DRAFT → fully editable (lines, quantities, addresses, references).
  • Placed → immutable lines; child Logistic Orders drive progression (see next page).
  • Delete → allowed only in DRAFT and only if no blocking links (payments/shipments/etc.).
  • Full details and state model diagrams are on the next page: Lifecycle & Status.

🔄 Differences vs cart-centric flows (old versions)

  • Single object to manage: everything happens on the order; no cart resource.
  • Server truth early: pricing/eligibility checks happen on the draft order as you edit it.
  • Fewer edge cases: no cart/order drift, simpler delete guards (DRAFT-only).
  • Quote-to-Order or Operation-to-Order path: supported (with re-validation).

⚙️ Data & constraints (what still applies)

  • Catalog Views filter visible products for the buyer’s Account.
  • Quantity constraints (min/max/pack) and optional stock checks still apply.
  • Sorting rule (global): when listing orders, any invalid/malformed sort entries are ignored silently; the request still succeeds.

🧱 What you’ll build next

  • Working with Draft Orders (create, update, add/read/remove lines, delete)
  • Search, Filter & Sort Orders (list for the buyer, filters, sort semantics)
  • Start an Order from a Quote/Operation (eligibility, mapping, re-validation)

🔗 API quicklinks

Add deep links to your API Reference once contracts are published (we won’t invent fields here):

Updated about 1 month ago