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 = ORDERLINES).
• 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 by a Data Hub import (ERP feedback) or through the administration API — see Updating incident statuses.

📝 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.

🚧

API only for now. The corresponding Back-Office screens for supplier users and for status updates will arrive in a future version.

⚠️

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.