Order Incident Management (Order & Order Line)

DJUST enables Customer Users to report and view incidents related to orders or individual order lines. These incidents may reflect delivery issues, missing items, damaged goods, or other anomalies requiring supplier attention.

🧠 Concept Overview

• Incidents are issues reported on a logistic order (linkedType = ORDER) or a logistic order line (linkedType = ORDER_LINES).
• Each incident can include:
  • One or more reason codes (e.g. DAMAGED, MISSING)
  • An associated thread of messages
  • Affected quantity per line
  • Optionally: custom fields, photos, and external references
• Incidents are grouped by functional ID, even if multiple lines are affected.
• Incidents statuses are OPEN, ON_GOING and CLOSED. When an incident targets order lines, each impacted line carries its own status with the same values, independent from the incident status.
• Statuses are set to OPEN at creation, and can then be updated from the Back-Office, by a Data Hub import (ERP feedback) or through the administration API — see Updating incident statuses and Back-Office incident management.

📝 Order Incident Creation

✏️ Standard workflow

sequenceDiagram
    participant User as 👤 Customer User
    participant Front as 🖥️ Frontend App
    participant API as 🔗 DJUST
    participant Hub as 🧬 Data Hub Connector

    %% Déclaration d’un incident (commande ou ligne)
    User->>Front: Click "Report an incident" or "Ask for a refund"...
    User->>Front: Select one or more reasons
    User->>Front: Optionally add some elements (files, photos...)
    User->>Front: Create new incident
    Front->>API: ORDER-101
    API-->>Front: Incident created (id, threadId)

    %% Synchronisation vers le data hub
    Note over API,Hub: Optional synchronization
    API-->>Hub: Export incident via API Connector
    Hub-->>API: Synchronize statuses

When Customer Users wish to report an incident to an order or order line, they use a form in which they specify:

• the reason(s) for the incident
• if necessary, add additional information such as photos, an invoice, etc.

Incidents are created using the ORDER-101 route. This replaces older routes:

• JSON

  POST /v1/shop/logistic-orders/{orderLogisticId}/incidents

• JSON

  POST /v1/shop/logistic-orders/{orderLogisticId}/lines/incidents

❗️

Important

• The historical route THREAD-100 cannot be used with the new Order Incident process.
• Mirakl support for order incident is not yet available throughout the new Order Incident APIs.

📏 Quantity control

The sum of incident quantities per line cannot exceed the order line’s original quantity (by default).

💡

Example

• Line ordered quantity = 10
  • Incident #1 = 5 → ✅ accepted
  • Incident #2 = 6 → ❌ rejected

This is the default behaviour.

For various reasons, you may want your platform to work without this check. In this case, contact your CSM to disable it for you using the VERIFY_ORDER_LINE_QUANTITIES_FOR_INCIDENT feature flag.

This will allow you to report incidents that go beyond the initial quantity of the line.

🧮 Default quantity behaviour

If quantity is omitted, it defaults to the remaining quantity on that line.

💡

Example

• Ordered = 10
• Previous incidents = 3 + 5
• Omitted quantity ⇒ 2 (10 – 3 – 5) for any new incident declared

🧰 Incident declaration supports

🔍 Order Incident Consultation

✏️ Standard workflow

This section covers two key steps in how Customer Users interact with order-related incidents in the frontend application:

1. Fetching the list of incidents linked to orders or order lines.
2. Retrieving the details of a specific incident using its ID.

sequenceDiagram
    participant User as 👤 Customer User
    participant Front as 🖥️ Frontend App
    participant API as 🔗 DJUST

    %% Consultation d’un ou plusieurs incidents
    User->>Front: Views incident list
    Front->>API: ORDER-559
    API-->>Front: Incident list

    %% Visualisation d’un thread
    User->>Front: Click on an incident
    Front->>API: ORDER-503
    API-->>Front: Incident details

🧾 Step 1 – Viewing the List of Incidents

The user accesses a view showing incidents associated with their past orders (at the order or order line level) via ORDER-559.

Incidents can be filtered with the following parameters:

💡 Suggested Frontend Use:

• Display a badge or highlight on affected orders/lines.
• Group by status or supplier if needed.
• Display incident status, count or last update date.
• Link to incident detail page

🔎 Step 2 – Viewing a Specific Incident’s Details

The customer user accesses a detailed view of a specific incident associated with their past orders (at the order or order line level) via ORDER-503. This endpoint retrieves full metadata for a single incident:

• What it is linked to (order or order line)
• Reason(s), quantity, custom fields
• Associated thread ID for messaging

💡 Suggested Frontend Use:

• Show incident details and metadata
• Provide access to the discussion thread (using threadId)
• Include an action button to reply or escalate

🛠️ Administration APIs

Incidents can also be listed, read and updated from the administration surface, for Back-Office screens, operator tooling or supplier tooling. The read endpoints mirror the storefront routes above and return the same response structure.

📘

Note: Operators read and process these incidents directly from the order sheet in the Back-Office — see Back-Office incident management. The endpoints below are what an integration or a custom tool uses to do the same thing.

⚠️

Warning: A caller whose dj-client is neither OPERATOR nor SUPPLIER receives a 403. Updating statuses requires the same right as updating a logistic order (ADM-ORDER-201): ORDER_UPDATE.

Scoping: operator vs supplier vs storefront

✅

Tip: A supplier user already sees the "Incident declared" flag on its orders and can read and answer the incident thread. With these endpoints, the supplier journey is complete: find the incidents of its orders, read them, discuss with the customer and move their status forward.

Listing incidents

linkedType is required and accepts ORDER or ORDER_LINES. The other filters are optional and can be combined:

Sorting: format property:direction (asc / desc), default createdAt:desc. Sortable properties are id, externalId, threadId, status, createdAt and supplierName. A sort on id is always appended so that pagination stays stable across pages.

Pagination: page is zero-based (default 0) and size defaults to 20, with a minimum of 1 and a maximum of 100. A size outside those bounds returns a 400.

# All open incidents declared at order level on a given store, most recent first
GET /v1/incidents?linkedType=ORDER&status=OPEN&sort=createdAt:desc&page=0&size=50
dj-client: OPERATOR
dj-api-key: <your-api-key>
dj-store: STORE-FR

# Same request from a supplier user: only the incidents of the supplier's own orders are returned
GET /v1/incidents?linkedType=ORDER&status=OPEN&sort=createdAt:desc&page=0&size=50
dj-client: SUPPLIER
dj-api-key: <your-api-key>

Reading a single incident

ADM-INCIDENT-500 resolves the path parameter as a DJUST identifier by default; pass idType=EXTERNAL_ID to look the incident up by its external identifier instead.

The response carries logisticOrder when the incident targets a whole order, and orderLines when it targets order lines.

GET /v1/incidents/INC-000142?idType=EXTERNAL_ID
dj-client: OPERATOR
dj-api-key: <your-api-key>

A 404 (ORI0006) is returned when no incident matches the identifier, and a 403 (OR0026) when a supplier user targets an incident of another supplier. For the full list of error codes, see Error / Warning codes.

Updating incident statuses

ADM-INCIDENT-200 (PATCH /v1/incidents/{incidentId}) updates the status of an incident and, when the incident targets order lines, the status of each impacted line. Before this endpoint, an incident stayed OPEN unless an ERP fed a new status back through a Data Hub import.

sequenceDiagram
    participant Op as 👤 Operator or Supplier user
    participant Tool as 🖥️ Back-Office / tooling
    participant API as 🔗 DJUST

    Op->>Tool: Find incidents to process
    Tool->>API: GET /v1/incidents (ADM-INCIDENT-550)
    API-->>Tool: Incident list (scoped to the supplier if dj-client SUPPLIER)
    Op->>Tool: Open an incident
    Tool->>API: GET /v1/incidents/{incidentId} (ADM-INCIDENT-500)
    API-->>Tool: Incident details, lines, threadId
    Op->>Tool: Take the incident in charge
    Tool->>API: PATCH /v1/incidents/{incidentId} (ADM-INCIDENT-200) status ON_GOING
    API-->>Tool: 204 No Content
    Op->>Tool: Resolve the incident
    Tool->>API: PATCH /v1/incidents/{incidentId} (ADM-INCIDENT-200) status CLOSED + lines CLOSED
    API-->>Tool: 204 No Content

Request

At least one of status or lines must be provided. The query parameter idType (DJUST_ID by default, or EXTERNAL_ID) applies to the path parameter and to every lineId.

PATCH /v1/incidents/0000011772
dj-client: OPERATOR
dj-api-key: <your-api-key>
Content-Type: application/json

{
  "status": "ON_GOING",
  "lines": [
    { "lineId": "0000011780", "status": "CLOSED" }
  ]
}

A successful update returns 204 No Content.

Rules

• Independent statuses — closing an incident does not close its lines, and closing every line does not close the incident. Update both explicitly when needed.
• Every transition is allowed, in both directions — there is no state machine: a CLOSED incident or line can be reopened.
• Declarative only — the status is informative. Updating it closes no discussion thread, sends no notification, releases no quantity and does not modify the logistic order.
• Supplier scope — a supplier user can only update the incidents of its own logistic orders (403 / OR0026 otherwise).
• Traceability — the author and date of each change are kept.
• Data Hub imports keep working — an import can still update both statuses, and can overwrite a value set through this endpoint.

Errors

✅

Tip: To list the logistic orders whose incidents are still OPEN or ON_GOING, use the incidentStatus criterion of the logistic order search — see Search, Filter & Sort Logistic Orders.

📘

Note: The existing storefront routes are unchanged. Management of incident discussion threads on the administration surface also remains unchanged.

Back-Office incident management

An incident declared from the storefront is read and processed from the order sheet in the Back-Office: reasons, impacted lines, statuses and the discussion with the customer are all on the order carrying them. What the screens do is exactly what the administration endpoints above expose, so a custom tool and the Back-Office behave alike.

Incidents tab on an order

An Incidents tab appears on the order sheet as soon as the order carries at least one incident, with the total count as a counter. An order without incident has no tab.

The counter and the two areas map to what ADM-INCIDENT-550 returns for linkedType=ORDER and linkedType=ORDER_LINES; a card maps to one ADM-INCIDENT-500 incident.

Statuses are independent and never propagate

The incident carries a status, each impacted line carries its own, and the three values are the same — OPEN, ON_GOING, CLOSED. The two levels stay independent, in the Back-Office exactly as through ADM-INCIDENT-200:

• Closing an incident does not close its lines.
• Closing every line does not close the incident.
• Nothing is updated automatically, so any change can be reverted.
• When the incident status and its line statuses diverge, a banner reports the discrepancy without correcting anything.

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

  A[📘 Order sheet]:::sys --> B{Order carries<br>an incident}
  B -->|No| C[🧾 No Incidents tab]:::sys
  B -->|Yes| D[📦 Incidents tab<br>with the total count]:::read
  D --> E[🧾 Incident card<br>number • status • reasons • date]:::read
  E --> F[➕ Update the incident status]:::update
  E --> G[➕ Update a line status]:::update
  E --> H[💬 Reply in the discussion]:::update
  F --> I[✅ Only the incident changes]:::place
  G --> J[✅ Only that line changes]:::place

  class B decision
  style A rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8
  style E rx:8,ry:8
  style F rx:8,ry:8
  style G rx:8,ry:8
  style H rx:8,ry:8
  style I rx:8,ry:8
  style J rx:8,ry:8

⚠️

Warning: The divergence banner is informative. It never aligns the statuses for you — an incident whose lines are all CLOSED stays OPEN until someone closes it, and it keeps being returned by incidentStatus: ["OPEN"] on the order lists.

One discussion per incident

The discussion belongs to the incident, not to its lines: an incident spanning several order lines carries a single thread. A reply written there reaches the customer user who declared the incident, and the messages are shown with their author and date.

Filtering the order list by incident status

The order list offers an Incident status filter with the three values OPEN, ON_GOING and CLOSED, in multiple selection, combinable with the other filters of the list. It is the screen counterpart of the incidentStatus criterion of the logistic order search:

• An order is returned as soon as one of its incidents carries one of the selected statuses — an order with one closed and one open incident appears under both.
• Only the incident status is evaluated, never its line statuses.
• Labels and colours are the same as in the Incidents tab, so a status looks identical from the list and from the order sheet.

{ "locale": "fr", "incidentStatus": ["OPEN", "ON_GOING"] }

Sent to ADM-ORDER-551 (POST /v1/logistic-orders), this body returns exactly what the filter displays. The criterion is detailed in Search, Filter & Sort Logistic Orders.

⚠️

Warning: Do not confuse this filter with the older incident boolean. The boolean relies on the order's incident flag, which is also raised by a plain customer discussion and is never cleared — it returns more orders than the three statuses combined.

Common mistakes