Migration guide (Cart v2 → Order-based Checkout)

Purpose

Help teams move from Cart v2 (cart-centric) to Order-based Checkout (order-first, no technical cart). This page highlights key deltas, a before/after workflow, a capability and endpoint mapping, and a focused test checklist.

✨ What changes

• No technical cart → everything is a Commercial Order (draft → placed).
• Draft-only edits → after Place - ORDER-212, the Commercial Order is immutable; child Logistic Orders = CREATED and drive progression.
• Dedicated address updates → shipping (ORDER-215) and billing (ORDER-213) are separate endpoints applied to the order and linked Logistic Orders.
• Lines as services → edit via ORDER-150 (updateAction=ADD|REMOVE|REPLACE), delete via ORDER-350, read (ORDER-561). Header read is ORDER-500.
• Start from a source → optional init from Operation or Quote via ORDER-108.
• Legacy field: processing is not used in Order-based Checkout; ignore if you still see it.

🧭 Concept mapping

🗺️ Before/After workflow

flowchart LR
    subgraph V3 [Order-based checkout]
    direction LR
    O0[🆕 Create draft<br>ORDER-108]:::create --> O1[📘 Read draft<br>ORDER-500]:::read
    O1 --> O2{✏️ Edit lines?}:::decision
    O2 -->|Add| O3[➕ Add lines<br>ORDER-150]:::add
    O2 -->|Remove| O4[➖ Remove lines<br>ORDER-350]:::remove
    O3 --> O5[📄 Read lines<br>ORDER-561]:::read
    O2 -->|No| O5
    O4 --> O5
    O5 --> O7[📦 Update shipping<br>ORDER-215]:::update
    O5 --> O8[🧾 Update billing<br>ORDER-213]:::update 
    O7 --> O9[✅ Place order<br>ORDER-212<br>child LOs → CREATED]:::place
    O8 --> O9
	end

  subgraph V2 [Cart v2]
    direction LR
    C0[🛒 Create cart<br>CART-100]:::create --> C1[📘 Read cart<br>CART-500]:::read
    C1 --> C2{✏️ Edit lines?}:::decision
	C2 -->|Add| C3[➕ Add items from offers id<br>CART-150]:::add
    C2 -->|Add| C3b[➕ Add items from variants id<br>CART-151]:::add
    C2 -->|Remove| C4[➖ Remove lines<br>CART-350]:::remove
    C3 --> C5[🧾 Read cart<br>header+lines<br>CART-551]:::read
    C5 --> C6[🧾 Initialize order<br>CART-101]:::create
    C6 --> C10[🧾 Get commercial order<br>ORDER-500]:::read
    C3b --> C5
    C4 --> C5
    C2 -->|No| C5
    C10 --> C7[📦 Update shipping<br>ORDER-215]:::update
    C10 --> C8[🧾 Update billing<br>ORDER-213]:::update
    C7 --> C9[✅ Place order<br>ORDER-212<br>child LOs → CREATED]:::place
    C8 --> C9
  end



  %% Styles
  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;

  style V2 rx:10,ry:10
  style V3 rx:10,ry:10

📚 Cart v2 → Order-based Checkout (endpoint mapping by capability)

Use this table to migrate code. Exact Order-based Checkout contracts and opIds live in API Reference.

Test checklist (must pass)

🔗 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
• List Commercial Orders - ORDER-560
• Place - ORDER-212

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