Getting started

What this covers

A concise overview of the Commercial Order flow: from draft creation to placement. Detailed step-by-step actions live in Working with Draft Orders; request/response contracts are in API Reference.

At a glance

No technical cart; everything is a Commercial Order.

Edit while DRAFT only; placing the order locks it and sets child Logistic Orders to CREATED.

Start empty or from a source (Operation or Quote).

🧰 Prerequisites

Area	You need
Headers	Shop routes expect `dj-client=ACCOUNT` and `dj-api-key`.
Store scope	Optional `dj-store` / `dj-store-view`. Caller must be attached to the effective store.
Feature flags	Only when starting from an Operation: tenant flag `OPERATIONS`.
Address IDs	`shippingAddressId` / `billingAddressId` are external IDs of valid addresses.
Id kinds	For orders, prefer REFERENCE when available.

🗺️ End-to-end workflow

flowchart LR
  START[🏁 Start] --> SRC{🆕 Create mode}
  SRC -->|Empty| C0[🆕 Create draft<br>ORDER-108]
  SRC -->|From Operation| C1[🆕 Create from Operation<br>ORDER-108]
  SRC -->|From Quote| C2[🆕 Create from Quote<br>ORDER-108]
  C0 --> R[📘 Read draft<br>ORDER-500]
  C1 --> R
  C2 --> R
  R --> S[📦 Update shipping<br>ORDER-215]
  S --> B[🧾 Update billing<br>ORDER-213]
  B --> DEC{✏️ Edit lines?}
  DEC -->|Add| A1[➕ Add lines<br>ORDER-150]
  DEC -->|Remove| A2[➖ Remove lines<br>ORDER-350]
  DEC -->|No| L[📄 Read lines<br>ORDER-561]
  A1 --> L
  A2 --> L
  L --> PLACE[✅ Place order<br>ORDER-212<br>child LOs → CREATED]
  PLACE --> DONE[🎉 Done]

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

  class START start
  class SRC decision
  class C0,C1,C2 create
  class R,L read
  class S,B update
  class DEC decision
  class A1 add
  class A2 remove
  class PLACE place
  class DONE success

  style START rx:8,ry:8
  style C0 rx:8,ry:8
  style C1 rx:8,ry:8
  style C2 rx:8,ry:8
  style R rx:8,ry:8
  style S rx:8,ry:8
  style B rx:8,ry:8
  style A1 rx:8,ry:8
  style A2 rx:8,ry:8
  style L rx:8,ry:8
  style PLACE rx:8,ry:8
  style DONE rx:8,ry:8

🔗 API quicklinks

Create draft - ORDER-108
Read draft - ORDER-500
Update shipping info - ORDER-215
Update billing info - ORDER-213
Add lines - ORDER-150
Remove lines - ORDER-350
Read lines - ORDER-561
Place - ORDER-212

See Working with Draft Orders for how to use each action. Contracts are in API Reference.