Guides
Start typing to search…

Start from a Source (Operation or Quote)

What this covers

How to initialize a Commercial Order from a source: an Operation or a Quote. What headers to send, how isFull behaves, and which validations apply.

At a glance

  • One endpoint: Create order - (ORDER-108).
  • Sources supported today: OPERATION and QUOTE.
  • isFull=true adds all eligible lines from the source; isFull=false is only for OPERATION (create empty draft linked to the Operation).

🔗 Endpoint

  • Create order - (ORDER-108)

POST /v2/shop/commercial-orders

Feature flag: required only when sourceType=OPERATION (OPERATIONS). Not required for QUOTE.

🧾 Request body

{
  "sourceType": "OPERATION | QUOTE",
  "sourceId": "string",
  "isFull": true
}

Defaults If a source is provided, isFull defaults to true.

🟣 From an Operation

Behavior

  • isFull=true → add all eligible & visible Operation lines to the order (filtered by store/account/catalog views).
  • isFull=false → create an empty order linked to the Operation; add lines later via Add lines - (ORDER-150).
  • The Operation must be ACTIVE, within its date window, scoped to the buyer’s Store/Account, and lines must remain visible via Catalog Views.
  • All lines are re-validated again at placement (ORDER-212).

Flow

flowchart LR
  IN[POST ORDER-108<br>sourceType=OPERATION] --> AUTH[Auth & headers<br>dj-client=ACCOUNT - api-key]
  AUTH --> FF[Feature flag OPERATIONS?]
  FF -->|No| ERR403FF[403 Feature disabled]
  FF -->|Yes| STORE[Resolve effective store<br>dj-store or default]
  STORE --> ATT[Check store attachment<br>caller attached?]
  ATT -->|No| ERR403S[403 Access denied]
  ATT -->|Yes| LINES[Resolve eligible Operation lines<br>visibility • dates • catalog views]
  LINES --> FULL{isFull?}
  FULL -->|true| ADD[Add all eligible lines]
  FULL -->|false| EMPTY[Create empty order<br>linked to Operation]
  ADD --> OUT[201 Created]
  EMPTY --> OUT

  %% ---------- Styles ----------
  classDef sys fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef ok fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef stop fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  class IN,AUTH,FF,STORE,ATT,LINES,FULL sys
  class ADD,EMPTY,OUT ok
  class ERR403FF,ERR403S stop

  style IN rx:8,ry:8
  style AUTH rx:8,ry:8
  style FF rx:8,ry:8
  style STORE rx:8,ry:8
  style ATT rx:8,ry:8
  style LINES rx:8,ry:8
  style FULL rx:8,ry:8
  style ADD rx:8,ry:8
  style EMPTY rx:8,ry:8
  style OUT rx:8,ry:8
  style ERR403FF rx:8,ry:8
  style ERR403S rx:8,ry:8

🟡 From a Quote

Behavior

  • Only isFull=true is supported (forced).
  • Attempt all quote lines; stock availability is the only product check at init time.
  • Out-of-stock lines are ignored.
  • Quote must be WAITING_FOR_CUSTOMER, not expired/cancelled, owned by the caller’s account, and in the effective store.

Flow

flowchart LR
  IN[POST ORDER-108<br>sourceType=QUOTE] --> AUTH[Auth & headers<br>dj-client=ACCOUNT - api-key]
  AUTH --> STORE[Resolve effective store<br>dj-store or default]
  STORE --> ATT[Check store attachment<br>caller attached to store?]
  ATT -->|No| ERR403S[403 Access denied]
  ATT -->|Yes| OWN[Check quote ownership<br>same account?]
  OWN -->|No| ERR403O[403 Access denied]
  OWN -->|Yes| STATUS[Quote status OK?<br>WAITING_FOR_CUSTOMER & not expired]
  STATUS -->|No| ERR422S[422 Invalid status]
  STATUS --> LINES[Collect quote lines<br>stock check only]
  LINES --> NONE[No eligible line?]
  NONE -->|Yes| ERR422E[422 Empty after check]
  NONE -->|No| CREATE[Create order<br>add eligible lines]
  CREATE --> OUT[201 Created]

  %% ---------- Styles ----------
  classDef sys fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef ok fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef stop fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  class IN,AUTH,STORE,ATT,OWN,STATUS,LINES,NONE sys
  class CREATE,OUT ok
  class ERR403S,ERR403O,ERR422S,ERR422E stop

  style IN rx:8,ry:8
  style AUTH rx:8,ry:8
  style STORE rx:8,ry:8
  style ATT rx:8,ry:8
  style OWN rx:8,ry:8
  style STATUS rx:8,ry:8
  style LINES rx:8,ry:8
  style NONE rx:8,ry:8
  style CREATE rx:8,ry:8
  style OUT rx:8,ry:8
  style ERR403S rx:8,ry:8
  style ERR403O rx:8,ry:8
  style ERR422S rx:8,ry:8
  style ERR422E rx:8,ry:8

🧩 Interactions with other endpoints

  • Add lines - (ORDER-150): use after creating an empty order from an Operation (isFull=false).
  • Read the draft - (ORDER-500) and Read lines - (ORDER-561): verify the initialized content.
  • Place / validate - (ORDER-212): transition the order to placed; child Logistic Orders move to CREATED.

🔗 Related

  • Buyer experience ▸ Start from an Operation — how buyers trigger the flow from the Operation detail or list in the storefront.

    → Start from operation

  • Working with Draft Orders — after init, manage the order: read, add/remove lines, place (ORDER-212).

    → Working with draft orders


Updated about 1 month ago