Tracking Lifecycle Model

Lifecycle is an aggregated state. It is not just "the latest checkpoint". The system evaluates multiple fields and applies precedence rules.

Why Lifecycle Exists

Carrier checkpoints are a history of events. The latest event alone can be misleading (for example, after failed attempts or return flows). Lifecycle gives one current business state for retailer operations, reporting, and trigger logic.

For information about the mapping of individual checkpoints of a delivery, refer to the following page.

Delivery Status Model

Lifecycle Stage Codes and Business Labels

Stage Code	Business Label	Is terminal	Description
Pending	Pending		Label exists, but no in-transit progression yet.
Transit	Transit		In carrier network.
Customs	Customs		Shipment is currently in customs processing.
LastMile	Last mile		Shipment reached out-for-delivery at least once.
ReadyToCollect	Ready to collect		Shipment is available for customer pickup.
Delivered	Delivered		Final handover to customer (or equivalent completion).
SentBack	Sent back		Return to sender started but not yet completed.
Returned	Returned		Return delivered back to sender/retailer.
Failed	Failed		Shipment cannot proceed (lost/destroyed/seized return path).
Cancelled	Cancelled		Cancelled by retailer.

Notes:

• Cancelled has highest precedence and overrides all other states.

• LastMile is sticky in practice once OutForDelivery has happened, unless overridden by terminal/return/cancel states.

• Failed is currently derived in return context when exceptions indicate unrecoverable loss/destruction/seizure.

Lifecycle Flags (Additional Context)

These flags complement stage and are exposed in formatted tracking output.

Flag	Meaning
flag_delayedDispatch	Delayed dispatch from warehouse to carrier.
flag_failedAttempt	At least one failed delivery attempt occurred.
flag_delayed	Shipment delay was detected.

Notes:

• Flags are orthogonal to lifecycle stage.

• A shipment can be Transit + flag_delayed = true, or Delivered + flag_failedAttempt = true.

Technical Details on Stage Resolution

The lifecycle engine evaluates in this order. Earlier matches win and return immediately.

1. Cancelled

2. Return-to-Sender flow:

   • Failed if any checkpoint exception contains Lost, Destroyed, or Seized

   • Returned if return shipment has been delivered

   • Otherwise SentBack

3. Delivered flow:

   • Non-branch delivery: Delivered

   • Branch delivery: ReadyToCollect until an internal retailer event confirms customer collection, then Delivered (see details below)

4. Pickup-ready flow:

   • ReadyToCollect, if any DeliveryStatus like PickupReady*

   • Additional condition for non-branch delivery: Delivery had a network scan before

5. In-transit flow:

   • Default Transit as soon as any network scan is registered

   • LastMile if any checkpoint has DeliveryStatus containing OutForDelivery

   • Customs in/out logic (see below) can switch between Customs and Transit

6. Fallback default: Pending

Branch Delivery Special Handling

For delivery_info.branchDelivery = true:

• Carrier-level delivery_date alone does not always mean customer-delivered

• Stage is ReadyToCollect until an internal event confirms customer collection

• Internal collection confirmation currently requires:

  • status_details beginning with ShopEvent or parcelLab (case-insensitive), and

  • matching.DeliveryStatus = Delivered

This is why a branch shipment can have delivery_date and still be ReadyToCollect.

Customs Behavior

Customs is stateful while processing checkpoints in order:

• Enters customs on:

  • DeliveryStatus = CustomsIn, or

  • DeliveryStatus = Exception with exception containing Customs

• Exits customs on:

  • CustomsReleased, DestinationDeliveryCenter, or DestinationDeliveryDepot

• After customs exit, stage returns to Transit unless a higher-precedence rule already applied.