Order lifecycle and statuses

This page describes how orders are structured and managed in Djust OMS, with a focus on lifecycle progression, key statuses, and operational transitions.

📦 Order Structure Overview

Each order in Djust OMS follows a structured lifecycle composed of several phases. It can contain:

• One or multiple order lines (products)
• Optional delivery splits (for multi-shipment flows)
• Related documents (quotes, invoices, delivery notes)
• Linked approval and shipment statuses

Orders progress through the lifecycle based on configured business rules, user actions, and external system events (e.g. approval, shipment, or cancellation).

🧭 Main Order Lifecycle Phases

The following statuses define the typical flow of a B2B order in Djust OMS:

1. Draft (DRAFT_ORDER)

• The order is being created and not yet submitted.
• Still editable by the buyer.
• Next states: DRAFT_ORDER_ON_HOLD, ORDER_CREATED, CANCELED.

2. On Hold (DRAFT_ORDER_ON_HOLD)

• This is an optional intermediate status that can be triggered during checkout.
• It allows a third party (e.g., a procurement manager or finance controller) to review and verify the order before submission.
• Useful in workflows where manual validation, rechecking, or internal coordination is required before the order proceeds.
• Next states: ORDER_CREATED, CANCELED.

3. Blocked By Policy (BLOCKED_BY_POLICY)

• Order cannot progress due to Buying Policies checks (e.g., credit control, quotas).
• When it happens: at placement/validation time or later validations, if the policy engine flags the order as non-compliant.
• How to resolve: adjust account limits/quotas, use an operator override per your governance (see Buying Policies docs), or decline the order (operator only).
• Next states: back to DRAFT_ORDER (after fix) then CREATED on successful re-validation, or DECLINED_BY_SUPPLIER if declined by an operator.

4. Blocked By Payment (BLOCKED_BY_PAYMENT)

• Payment authorization failed for this Logistic Order.
• When it happens: during/after the authorization step for the order (PCard L3 payment method only); if the provider returns a refused/declined result for this split.
• How to resolve: retry authorization, change payment method, or handle per your escalation rules.
• Next states: CREATED after a successful retry; remains BLOCKED_BY_PAYMENT otherwise.

5. Created (ORDER_CREATED)

• The order has been submitted by the buyer.
• It awaits the next approval steps.
• Next states: WAITING_CUSTOMER_APPROVAL, WAITING_SUPPLIER_APPROVAL, BLOCKED_BY_POLICY, BLOCKED_BY_PAYMENT, CANCELED.

⚠️

Warning: When a payment authorization is in progress (AUTHORIZATION_PENDING), the order is locked — all modification endpoints are rejected until the authorization is confirmed or refused. This prevents mismatches between the authorized amount and the order content. See Working with Draft Orders for details.

6. Waiting Customer Approval (WAITING_CUSTOMER_APPROVAL)

• An internal approval step is required from the customer (e.g., purchase manager validation).
• Configurable per client and order type.
• Next states: WAITING_SUPPLIER_APPROVAL, DECLINED_BY_CUSTOMER, CANCELED.

7. Waiting Supplier Approval (WAITING_SUPPLIER_APPROVAL)

• The order is awaiting review and confirmation by the supplier.
• The supplier can accept or decline based on stock or commercial conditions.
• Next states: ACCEPTED_BY_SUPPLIER, DECLINED_BY_SUPPLIER, CANCELED.

Accepting or declining an order

Both operator (dj-client: OPERATOR) and supplier (dj-client: SUPPLIER) users can accept or decline a logistic order, provided they have the ORDER_UPDATE permission.

Both endpoints accept an optional message field in the request body (free text, max 1000 characters) that is stored on the order and visible in the order detail responses.

ℹ️

A supplier user can only accept or decline orders assigned to their own supplier. The idType query parameter supports DJUST_ID (default) and EXTERNAL_ID.

⚠️

Declining from BLOCKED_BY_POLICY is restricted to operator users only (dj-client: OPERATOR). Supplier users cannot decline policy-blocked orders.

8. Declined By Customer (DECLINED_BY_CUSTOMER)

• The customer has refused or withdrawn the order after submission.
• The process stops unless re-submitted.

9. Declined By Supplier (DECLINED_BY_SUPPLIER)

• The supplier has refused the order (e.g. stock unavailability, pricing issue).
• The order cannot proceed further.

10. Accepted By Supplier (ACCEPTED_BY_SUPPLIER)

• The supplier has confirmed the order and is ready to fulfill it.
• It transitions to the fulfillment phase.
• Next states: WAITING_SHIPMENT.

11. Waiting Shipment (WAITING_SHIPMENT)

• The order is ready to be shipped, either partially or in full.
• Warehouse or supplier actions are expected.
• Next states: PARTIALLY_SHIPPED, SHIPPED, CANCELED.

12. Partially Shipped (PARTIALLY_SHIPPED) (Mirakl Only)

• Some order lines have been shipped, others are still pending.
• The order remains open until all items are fulfilled or canceled.
• Next states: SHIPPED, CANCELED.

13. Shipped (SHIPPED)

• All items have been shipped.
• Delivery may be confirmed by carrier integration or manually.
• The order can be completed (moved to COMPLETED) from the Back Office or via the admin API endpoint PUT /v1/logistic-orders/{orderLogisticId}/complete.
• Next states: COMPLETED, CANCELED.

14. Partially Canceled (PARTIALLY_CANCELED) (Mirakl Only)

• Some order lines have been canceled, other are still active.
• The order remains open until all items are canceled.
• Next states: SHIPPED, CANCELED.

15. Canceled (CANCELED)

• The order was canceled before full shipment.
• Can be triggered by the customer, supplier, or system rules.
• Only DRAFT_ORDER_ON_HOLD and WAITING_SHIPMENT are eligible to cancelation.

16. Completed (COMPLETED)

• The order has been fully processed: all shipments completed, and the flow is finalized.
• The order is archived operationally.

⚠️

Payment confirmation does not affect the logistic status. An order can be COMPLETED from a logistics perspective while the payment status remains independent (e.g., PAYMENT_NOT_INITIATED for clients without a PSP).

📄 Order Line Statuses

Each order line tracks its own state independently from the parent order. A line can carry both a lifecycle status and, if applicable, a refund status.

Line lifecycle status

By default, a line has no explicit status (active and progressing with the order). The following statuses flag deviations from the nominal flow:

Line refund status

When a refund is initiated at line level, the line carries a refund status:

ℹ️

Line statuses can differ across lines of the same order — e.g., a PARTIALLY_SHIPPED order may have one CANCELED line and the others active.

🧾 Status Types

Djust OMS tracks multiple layers of order status:

⚙️ Status Transition Logic

Status changes can be triggered by:

• Customer or supplier actions
• Admin operations via backoffice
• Data Hub jobs and or Webhooks from logistics or external systems
• Automated rules (e.g., timeout or rejection fallback)

All transitions are logged as events and auditable through the OMS.

🔁 Example Lifecycle Flow

flowchart LR
  %% Nodes
  DRAFT[📝 DRAFT_ORDER]:::draft --> HOLD[⏸️ DRAFT_ORDER_ON_HOLD]:::pause
  DRAFT --> PLACE[✅ ORDER_CREATED]:::created
  HOLD --> PLACE

  PLACE --> CAPP[🧾 WAITING_CUSTOMER_APPROVAL]:::approval
  PLACE --> SAPP[🧑‍🏭 WAITING_SUPPLIER_APPROVAL]:::approval

  CAPP --> ACC[👍 ACCEPTED_BY_SUPPLIER]:::progress
  CAPP --> DCUS[✋ DECLINED_BY_CUSTOMER]:::terminal
  SAPP --> ACC
  SAPP --> DSUP[❌ DECLINED_BY_SUPPLIER]:::terminal

  %% Buying Policies & Payment gates
  PLACE --> BPOL[🛑 BLOCKED_BY_POLICY]:::blocked
  PLACE --> BPAY[💳 BLOCKED_BY_PAYMENT]:::blocked

  %% Unblocks
  BPOL -->|Fix & re-validate| PLACE
  BPOL -->|Operator decline| DSUP
  BPAY -->|Retry auth OK| PLACE

  %% Fulfillment
  ACC --> WAITSHIP[📦 WAITING_SHIPMENT]:::progress
  WAITSHIP --> PARTSHIP[📦➗ PARTIALLY_SHIPPED <i>Mirakl only</i>]:::progress
  WAITSHIP --> PCAN[❎ PARTIALLY_CANCELED <i>Mirakl only</i>]:::progress
  PARTSHIP --> SHIP[🚚 SHIPPED]:::progress
  PARTSHIP --> PCAN
  PCAN --> SHIP
  SHIP --> DELIV[📬 COMPLETED]:::success

  %% Global cancel path
  HOLD --> CANCEL[🗑️ CANCELED]:::terminal
  WAITSHIP --> CANCEL

  %% ---------- Styles ----------
  classDef draft fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef pause fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef created fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef approval fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef progress fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef blocked fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef success fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef terminal fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  style DRAFT rx:8,ry:8
  style HOLD rx:8,ry:8
  style PLACE rx:8,ry:8
  style CAPP rx:8,ry:8
  style SAPP rx:8,ry:8
  style ACC rx:8,ry:8
  style WAITSHIP rx:8,ry:8
  style PARTSHIP rx:8,ry:8
  style PCAN rx:8,ry:8
  style SHIP rx:8,ry:8
  style DELIV rx:8,ry:8
  style BPOL rx:8,ry:8
  style BPAY rx:8,ry:8
  style DCUS rx:8,ry:8
  style DSUP rx:8,ry:8
  style CANCEL rx:8,ry:8