Order Status Timeline

1. Concept

🎯 Objective

The Order Status Timeline allows customer service teams to quickly understand the global status of an order at a glance.
It provides a clear, synthetic, and immediate view of the key milestones in the order lifecycle, enabling agents to answer customers over the phone within seconds.

This component is not meant to replace the detailed Order History.
It shows macro-states, not every transition or log.

🧩 Core Principle

The Timeline :

Displays a series of macro-states based on the order type:
- Home Delivery: created → orchestrated → prepared → dispatched → (returned) → (removed)
- Store Delivery : created → orchestrated → prepared → collectable → collected → (returned) → (removed)
- ROPIS: created → orchestrated → collectable → collected → (returned) → (removed)
- Immediate Pick Up (OIS): created → collected → (returned) → (removed) → (expired)
- States in italic are displayed only if they are reached
Displays macro states depending on standards and custom order states.
Displays fully or partially reached states using a consistent color-coded status logic.
Shows parcel evolution, each parcel progressing individually.

The Timeline is displayed only on order detail pages, never on parent orders.

Retroactivity :

Timeline display depends on available logs.

2. Configuration

🔧 Activation / Deactivation

The feature is controlled through a feature flag:

Configuration > Backoffice > Orders > Order Detail > Toggle: Enable Order Status Timeline

When enabled, a code editor becomes available, allowing the user to configure the mapping between client workflow states and timeline macro-states.

🧱 Macro status Mapping

Standard Mapping

A default mapping is provided in common. (usable from v21)

{
  homeDelivery: {
    orchestrated: {
      orderStates: ['processing'],
      parcelsStates: ['new'],
    },
    prepared: {
      parcelsStates: ['packed'],
    },
    dispatched: {
      orderStates: ['fulfilled'],
      parcelsStates: ['dispatched'],
    },
    returned: {
      returnParcelsStates: ['returned'],
    },
    cancelled: {
      orderStates: ['removed'],
    },
  }

{
  storeDelivery: {
    orchestrated: {
      orderStates: ['processing'],
      parcelsStates: ['new'],
    },
    prepared: {
      parcelsStates: ['packed', 'dispatched'],
    },
    collectable: {
      orderStates: ['collectable'],
      parcelsStates: ['bagged', 'received'],
    },
    collected: {
      orderStates: ['fulfilled'],
      parcelsStates: ['collected'],
    },
    returned: {
      returnParcelsStates: ['returned'],
    },
    cancelled: {
      orderStates: ['removed'],
    },
  }

{
  "immediatePickup": {
    "expired": {
      "orderStates": [
        "expired"
      ]
    },
    "returned": {
      "returnParcelsStates": [
        "returned"
      ]
    },
    "cancelled": {
      "orderStates": [
        "removed"
      ]
    },
    "collected": {
      "orderStates": [
        "fulfilled"
      ]
    }
  }
}

{
 storeReservation: {
    orchestrated: {
      orderStates: ['processing'],
      parcelsStates: ['new'],
    },
    collectable: {
      orderStates: ['collectable'],
      parcelsStates: ['bagged', 'ropis_bagged', 'received'],
    },
    collected: {
      orderStates: ['fulfilled'],
      parcelsStates: ['collected'],
    },
    returned: {
      returnParcelsStates: ['returned'],
    },
    cancelled: {
      orderStates: ['removed'],
    },
  }

The timeline provided depends on the order type. Availables order types are managable in :

Configuration > Back Office > Orders > Order list > Order types.

Custom Mapping (semi-DIY)

The timeline structure itself is not configurable.
Only the mapping between custom workflow states and timeline macro-states can be edited.
Transitions cannot be customized.
The editor allows the user to add or modify the mapping only.

Example:

{"cancelled": {
      "orderStates": ["removed", "removed_refunded"]}
}

Order types

To display orders in the correct timeline, make sure the order types are correctly ordered in Configuration > Backoffice > Order List > Order types.

We recommend using the following order:

ckc
ropis
home_delivery
ois

🛑 MVP Limitations

Parcel icons and parcel information are not configurable.
Future stock statuses are simplified and included under "processing".

3. Technical

🧠 Determining the Timeline Type

The system:

Retrieves the order type based on the configured mapping.
Selects one of the 3 predefined timelines.
Applies the client-defined mapping between workflow states and macro-states.

🎨 State Display Logic

Important rules:

CREATED is always fully achieved.
The current step is the last validated macro-state.
If the workflow moves backwards, the timeline reflects the current state but does not visually display the rollback.

📦 Parcel Handling

Parcels appear on the timeline as soon as they are created.
Each parcel progresses independently.
Displayed information includes:
- Parcel icon (box or bag depending on order type)
- Current state date (last update from logs)
- Store / carrier details via hover (id, name, email, address, phone)

Display rules:

Up to 3 parcels visible per step → beyond that: “Show more (X parcels)”.
A return_parcel is shown as a new parcel, the original is not removed.

📅 Additional Information

Order creation date is shown under the CREATED step.
If the order contains an ETA (available with Delivery Promise only) -
sent_delivery_option.eta_end:
- Home Delivery → displayed under processed / fulfilled
- Store Delivery → displayed under collectable

📱 Responsive Behavior

On mobile, the timeline becomes horizontally scrollable.

How does it work for old orders ?

The timeline is built and displayed based on the order logs. If an order has logs, the timeline will be displayed correctly.

We rely on the create and change_state logs of the order, parcel, and return_parcel entities.

4. User Guide

🧭 Understanding the States

Element	Meaning

Element	Meaning
	State or transition is not reached.
	State or transition is currently in progress.
	State or transition is half achieved.
	State or transition is achieved.
	State or transition is in error.

📦 Understanding Parcels

Element	Meaning

Element	Meaning
	Parcels appear under the step matching their macro-state. The date corresponds to the last update of the parcel.
	Hover reveals the preparation store/warehouse, contact information of the store/warehouse and carrier information.
	If many parcels exist, click Show more to expand the list.
	Return parcels appear under the RETURNED step. The date corresponds to the last update of the parcel.

Understanding Dates

Element	Meaning

Element

Meaning

The date under the CREATED step is date of creation of the order

Date in parcel or return parcel bagde corresponds to the last update of the parcel.

The date under the DISPATCHED step is the ETA of the order.

It exists only the delivery promise is used.

This date can appear under the DELIVERED step if this state is manage in the workflow.

💡 Special Cases

If a status goes backward, the UI updates accordingly but does not show the “rollback” explicitly.
Steps after a red status remain greyed out.

5. Use Cases Examples

🏠 Use Case 1: Standard Home Delivery

Scenario: A customer calls to check order progress.

Timeline shows:

→ “Your order is being orchestrated and will be prepared soon.”

Use Case 2: Store Delivery with Multiple Parcels

Scenario: A customer calls to check order progress. 2 items / 2 parcels.

Timeline shows:

→ “One parcel is already collectable; the other one is still processing.”

Use Case 3: Store Delivery with Partial Return

Scenario: A customer calls to check order progress. 10 items / 2 parcels of 5 items each / 1 return parcel with 1 item only.

→ “Every parcel and items have been collected. One parcel has been returned”. For more information about items in the return parcel the customer service must check the return parcel section in the order detailed page.

⚡ Use Case 4: Immediate Pick-Up (OIS)

Scenario: A customer service wants to check if a straight fulfilled order has an issue.

The order goes directly from created → collected. The order shows no issue.

Use Case 4: The order have been cancelled

Scenario: A customer calls to check why the order has been cancelled.

→ “Your order has been cancelled during the preparation process”. Here the customer service need to understand why by using the history logs.