Troubleshooting & FAQs

What this covers

Common issues when integrating Order-based Checkout and how to fix them fast. Detailed steps live in Working with Draft Orders; contracts are in API Reference.

Quick orientation

• Shop routes expect dj-client=ACCOUNT.
• Start empty or from a source (Operation or Quote) via ORDER-108.
• Draft-only edits (shipping/billing/lines). Placement (ORDER-212) locks the order and sets child Logistic Orders to CREATED.
• Address IDs (shippingAddressId / billingAddressId) are external IDs of valid typed addresses.

---

🚨 Common issues

---

🧭 Triage flow

flowchart LR
  IN[Incoming issue] --> STEP1[Headers & scope<br>dj-client • api-key • store]
  STEP1 --> STEP2{Which step fails?}
  STEP2 -->|Create OPERATION| C_OP[ORDER-108<br>source=OPERATION]
  STEP2 -->|Create QUOTE| C_QT[ORDER-108<br>source=QUOTE]
  STEP2 -->|Read| READ[ORDER-500/561]
  STEP2 -->|Shipping/Billing| SHBI[ORDER-215/213]
  STEP2 -->|Lines| LNS[ORDER-150/350]
  STEP2 -->|Place| PLC[ORDER-212]

  C_OP --> OP_CHECKS[Check OPERATIONS flag • store attachment • visibility]
  OP_CHECKS --> OP_FIX[Fix flag/scope/Operation targeting]
  OP_FIX --> OK1[Resolved]

  C_QT --> QT_CHECKS[Status WAITING_FOR_CUSTOMER • ownership • stock]
  QT_CHECKS --> QT_FIX[Fix status/owner • restock • remove isFull=false]
  QT_FIX --> OK2[Resolved]

  READ --> RD_CHECKS[idType • scope]
  RD_CHECKS --> RD_FIX[Use REFERENCE • fix scope]
  RD_FIX --> OK3[Resolved]

  SHBI --> SB_CHECKS[Address external IDs • typing • shippingType]
  SB_CHECKS --> SB_FIX[Use valid IDs • complete payload]
  SB_FIX --> OK4[Resolved]

  LNS --> L_CHECKS[min/max • pack • stock • visibility]
  L_CHECKS --> L_FIX[Adjust qty • restock • expose via Catalog Views]
  L_FIX --> OK5[Resolved]

  PLC --> P_CHECKS[Shipping/Billing set • line validations]
  P_CHECKS --> P_FIX[Set via 215/213 • fix qty/stock/visibility]
  P_FIX --> OK6[Resolved]

  %% ---------- Styles ----------
  classDef sys fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  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 place fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef ok fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;

  class IN,STEP1,OP_CHECKS,QT_CHECKS,RD_CHECKS,SB_CHECKS,L_CHECKS,P_CHECKS sys
  class STEP2 decision
  class C_OP,C_QT create
  class READ read
  class SHBI update
  class LNS add
  class PLC place
  class OP_FIX,QT_FIX,RD_FIX,SB_FIX,L_FIX,P_FIX update
  class OK1,OK2,OK3,OK4,OK5,OK6 ok

  style IN rx:8,ry:8
  style STEP1 rx:8,ry:8
  style STEP2 rx:8,ry:8
  style C_OP rx:8,ry:8
  style C_QT rx:8,ry:8
  style READ rx:8,ry:8
  style SHBI rx:8,ry:8
  style LNS rx:8,ry:8
  style PLC rx:8,ry:8
  style OP_CHECKS rx:8,ry:8
  style OP_FIX rx:8,ry:8
  style QT_CHECKS rx:8,ry:8
  style QT_FIX rx:8,ry:8
  style RD_CHECKS rx:8,ry:8
  style RD_FIX rx:8,ry:8
  style SB_CHECKS rx:8,ry:8
  style SB_FIX rx:8,ry:8
  style L_CHECKS rx:8,ry:8
  style L_FIX rx:8,ry:8
  style P_CHECKS rx:8,ry:8
  style P_FIX rx:8,ry:8
  style OK1 rx:8,ry:8
  style OK2 rx:8,ry:8
  style OK3 rx:8,ry:8
  style OK4 rx:8,ry:8
  style OK5 rx:8,ry:8
  style OK6 rx:8,ry:8

---

❓ FAQs

Q: Can I edit shipping/billing after placement? A: No. After ORDER-212, the Commercial Order is immutable; use OMS flows on child Logistic Orders.

Q: Which id should I use to read an order? A: Prefer the business reference and pass ?idType=REFERENCE where supported.

Q: Why does Quote creation require isFull=true? A: Checkout initializes from all available quote lines; partial copy is not supported for QUOTE.

Q: Do I need idempotency keys? A: No — IDs are generated by the backend and are always unique (no special client idempotency setup required).

Q: Do Operation lines bypass Catalog Views? A: No. Operation lines still respect Catalog Views for the buyer’s Account.