Synchronize a Draft Order

Introduction

A commercial order in DRAFT status is editable and evolves until placement. Between the moment it is created and the moment it is placed, catalog data can change: prices may be updated, stock levels may decrease, products may become inactive, or quantity rules may evolve.

The sync endpoint reconciles a draft order with the current state of the DJUST catalog and returns a detailed list of warnings - either blocking (the order cannot be updated) or informational (the order was updated, but differences were detected).

When to sync

Synchronization is not limited to a pre-placement check. It should be called whenever the order needs to reflect the latest catalog reality:

• On order display - When a buyer reopens a draft order, call sync to refresh prices, stock, and availability before rendering the page. This ensures the buyer always sees accurate, up-to-date information.
• After a period of inactivity - If a draft order has been idle for hours or days, catalog data may have drifted significantly.
• Before placement - As a final validation step before calling the placement endpoint (ORDER-212), to catch any last-minute changes.
• After editing lines - When lines have been added or quantities changed, sync ensures the full order remains coherent.

✅

Tip: Synchronization works with DJUST as the single source of truth (standard mode). No external pricing or stock system is required.

Key Concepts

Standard Mode

In standard mode, synchronization relies exclusively on data persisted in DJUST:

• Catalog: product and variant activation status, catalog view eligibility for the buyer's context
• Offer prices: price values, eligibility per account or account group
• Stock / availability: offer inventory levels
• Quantity rules: minimum, maximum, item per pack
• Custom fields: offer-level and order-level custom field validity

No external real-time pricing (RTP) source is involved.

Catalog View Eligibility

Each order line is verified against the catalog views assigned to the customer user. If a product has been removed from a catalog view, or if the buyer's catalog view scope has changed, the product is flagged with a blocking warning (F-W-015).

This same eligibility check is also enforced when adding a product to an order (add-to-cart). A product that is not visible in the buyer's current catalog view context cannot be added to a commercial order.

⚠️

Warning: A product that was previously valid may become ineligible after a catalog view configuration change. Always call sync before placement to catch these cases.

Blocking vs. Informational Warnings

Each warning returned by the sync endpoint carries a blocked flag:

⚠️

Warning: If at least one blocking warning exists, no modification is applied to the order - even if other lines are valid.

Warning Structure

Each warning in the response array contains:

{
  "id": "OFFP-EXT-00042",
  "code": "F-W-018",
  "blocked": true,
  "detail": "Requested quantity is lower than the minimum order quantity.",
  "changes": [
    {
      "field": "quantity",
      "previousValue": "2",
      "newValue": "5"
    }
  ]
}

How to read changes depending on the warning type:

• Informational (blocked: false): previousValue is the old value on the order line, newValue is the new value that was applied by the sync.
• Blocking (blocked: true): previousValue is the current value on the order line, newValue is the constraint or limit that the line violates (e.g. the minimum order quantity). No change is applied.

Preconditions

Before calling the sync endpoint, ensure:

• The commercial order has not been validated (validatedAt must be empty)
• The order is in a modifiable state (DRAFT)
• The order was created in an Order-based Checkout context
• The caller is either the order owner or has the required permissions to edit order lines

If any precondition is not met, the sync is rejected with an error response (see Error handling).

API Reference

Endpoint

PUT /v1/shop/commercial-orders/{commercialOrderId}/sync

operationId: ORDER-223

Path Parameters

Headers

⚠️

Warning: Only dj-client: ACCOUNT is accepted on this endpoint.

Request Body

No request body. The sync applies to all existing lines on the order.

Response

200 OK - Returns an array of warnings (may be empty if everything is up to date):

[
  {
    "id": "OFFP-EXT-00042",
    "code": "F-W-014",
    "blocked": true,
    "detail": "The product variant with id PV-00042 is inactive."
  },
  {
    "id": "OFFP-EXT-00099",
    "code": "F-W-018",
    "blocked": true,
    "detail": "Requested quantity is lower than the minimum order quantity.",
    "changes": [
      {
        "field": "quantity",
        "previousValue": "2",
        "newValue": "5"
      }
    ]
  },
  {
    "id": "OFFP-EXT-00110",
    "code": "F-W-026",
    "blocked": false,
    "detail": "Unit price has been updated.",
    "changes": [
      {
        "field": "unitPrice",
        "previousValue": "12.50",
        "newValue": "13.20"
      }
    ]
  }
]

When the response contains only non-blocking warnings (or no warnings at all), the order has been updated successfully. The lastSyncAt timestamp is set on the order.

What Gets Checked

Blocking Warnings (blocked: true)

The following conditions prevent the order from being updated. When at least one blocking warning is detected, no change is applied to any line.

Product / Variant

Offer / Pricing

Quantity Rules

Stock

Custom Fields

Informational Warnings (blocked: false)

The following changes are applied automatically and reported for traceability. The changes field provides the before/after values for each applied change.

ℹ️

Important: Informational warnings reflect a diff between the order line and the current catalog state. Once the sync applies the changes, calling sync again immediately will not return these warnings because the order is now in sync with the catalog. This is expected behavior - it means the order is up to date.

For the full warning code reference, see Error / Warning codes.

Typical Workflow

flowchart LR
    %% Styles (Readme)
    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 decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
    classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
    classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

    A[📘 Buyer opens<br>draft order] --> B[🔄 Call sync<br>ORDER-223]
    B --> C{Blocking<br>warnings}
    C -->|None| D[✅ Order updated<br>lastSyncAt set]
    D --> E{Buyer<br>action}
    E -->|Continue editing| A
    E -->|Place order| F[➡️ ORDER-212]
    C -->|At least one| G[⛔ Order unchanged<br>fix issues]
    G --> H[🔧 Remove or fix<br>affected lines]
    H --> B

    A:::create
    B:::update
    C:::decision
    D:::place
    E:::decision
    F:::place
    G:::stop
    H:::update

Recommended integration patterns

Pattern 1 - Sync on order display (recommended)

Call sync every time the buyer opens or returns to the draft order view. This keeps prices and availability up to date and allows the UI to display warnings immediately.

1. Buyer navigates to the draft order view
2. Call sync (ORDER-223)
3. Render the order with fresh data and display any warnings to the buyer
4. Buyer edits lines if needed → re-sync after edits
5. When ready → place order (ORDER-212)

Pattern 2 - Sync before placement only

Call sync as a final validation step just before placing the order. Simpler to implement, but the buyer may discover stale data only at checkout time.

1. Build your draft order (create, add lines, set addresses)
2. Call sync (ORDER-223) before placement
3. If blocking warnings → display issues, fix lines, retry sync
4. If no blocking warnings → proceed to placement (ORDER-212)

✅

Tip: Sync does not add or remove lines - it only validates and updates existing ones. To remove problematic lines, use the line deletion endpoint (ORDER-350) before retrying sync.

Error Handling

For the full error reference, see Error / Warning codes.

Best Practices

• Sync on every order display - Call sync whenever the buyer opens the draft order view, not just before placement. This ensures prices and stock are always accurate.
• Handle blocking warnings gracefully - Display the detail message to the user and let them decide whether to fix or remove affected lines.
• Use lastSyncAt for freshness - After a successful sync, lastSyncAt is updated on the order. You can use this to decide whether a re-sync is needed (e.g. skip sync if lastSyncAt is less than a few minutes old).
• Re-sync after line edits - After adding, removing, or changing quantities on lines, call sync again to revalidate the full order.
• Understand idempotent behavior - Informational warnings only appear when there is a difference to report. A second consecutive sync call returns no informational warnings because the first call already applied the changes. This is expected - it means the order is up to date.
• Do not use sync as a create mechanism - In standard mode, sync never creates new lines. It only validates and updates existing ones.

Common Mistakes