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.

📝 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