# Tracking Lifecycle Model

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

{% content-ref url="/pages/-LcBrVLrJiv4Kd--KkGw" %}
[Delivery Status Model](/docs/developers/data-elements/lifecycle-model/status-model.md)
{% endcontent-ref %}

### Lifecycle Stage Codes and Business Labels

<figure><img src="/files/NFApkQPwtgfCYTuVwPL2" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="151">Stage Code</th><th width="147.5">Business Label</th><th width="116.5" data-type="checkbox">Is terminal</th><th width="316.5">Description</th></tr></thead><tbody><tr><td><code>Pending</code></td><td>Pending</td><td>false</td><td>Label exists, but no in-transit progression yet.</td></tr><tr><td><code>Transit</code></td><td>Transit</td><td>false</td><td>In carrier network.</td></tr><tr><td><code>Customs</code></td><td>Customs</td><td>false</td><td>Shipment is currently in customs processing.</td></tr><tr><td><code>LastMile</code></td><td>Last mile</td><td>false</td><td>Shipment reached out-for-delivery at least once.</td></tr><tr><td><code>ReadyToCollect</code></td><td>Ready to collect</td><td>false</td><td>Shipment is available for customer pickup.</td></tr><tr><td><code>Delivered</code></td><td>Delivered</td><td>true</td><td>Final handover to customer (or equivalent completion).</td></tr><tr><td><code>SentBack</code></td><td>Sent back</td><td>false</td><td>Return to sender started but not yet completed.</td></tr><tr><td><code>Returned</code></td><td>Returned</td><td>true</td><td>Return delivered back to sender/retailer.</td></tr><tr><td><code>Failed</code></td><td>Failed</td><td>true</td><td>Shipment cannot proceed (lost/destroyed/seized return path).</td></tr><tr><td><code>Cancelled</code></td><td>Cancelled</td><td>true</td><td>Cancelled by retailer.</td></tr></tbody></table>

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.

<table><thead><tr><th width="204">Flag</th><th width="411.5">Meaning</th></tr></thead><tbody><tr><td><code>flag_delayedDispatch</code></td><td>Delayed dispatch from warehouse to carrier.</td></tr><tr><td><code>flag_failedAttempt</code></td><td>At least one failed delivery attempt occurred.</td></tr><tr><td><code>flag_delayed</code></td><td>Shipment delay was detected.</td></tr></tbody></table>

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parcellab.com/docs/developers/data-elements/lifecycle-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.