***

## title: Status Lifecycle

Every delivery on the Rendr platform progresses through a defined state machine from creation to completion.

Understanding the status lifecycle allows you to:

* Build accurate UI states
* Respond correctly to webhook events
* Implement deterministic reconciliation logic
* Handle exception paths safely

<Note>
  Deliveries always end in a final, immutable state. Do not infer transitions — always rely on the latest status value from the delivery object or webhook event.
</Note>

***

## Lifecycle Overview

```mermaid
stateDiagram-v2
    direction LR

    [*] --> created

    created --> requested
    requested --> booked
    requested --> on_hold
    on_hold --> requested

    booked --> assigned
    booked --> collected

    assigned --> approaching
    approaching --> collected

    collected --> delivered
    collected --> pending_return
    collected --> reassigned

    reassigned --> assigned

    pending_return --> returned

    created --> cancelled
    requested --> cancelled
    booked --> cancelled
    assigned --> cancelled
```

***

## Status Reference

| Status           | Type      | Description                                                                                                                                                                    |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `created`        | Active    | Delivery has been created on Rendr, but an issue has occurred. Rendr's team is notified and will resolve the issue.                                                            |
| `requested`      | Active    | Delivery is ready to be booked.                                                                                                                                                |
| `on_hold`        | Active    | Delivery has been put on hold by staff.                                                                                                                                        |
| `booked`         | Active    | Delivery has been booked and the courier has been notified.                                                                                                                    |
| `assigned`       | Active    | Delivery has been assigned to a courier.                                                                                                                                       |
| `approaching`    | Active    | Courier is approaching the pickup location.                                                                                                                                    |
| `collected`      | Active    | Delivery has been collected.                                                                                                                                                   |
| `delivered`      | **Final** | Order is successfully delivered.                                                                                                                                               |
| `reassigned`     | Exception | Delivery has been reassigned to another courier since the SLA has not been met. Rendr's team has rebooked with another provider to ensure the customer's expectations are met. |
| `pending_return` | Exception | Delivery could not be completed. The order is being returned to the pickup location.                                                                                           |
| `returned`       | **Final** | The delivery has been successfully returned.                                                                                                                                   |
| `cancelled`      | **Final** | Delivery has been cancelled.                                                                                                                                                   |

***

## Core Statuses

<AccordionGroup>
  <Accordion title="created">
    The delivery record exists but has not yet been submitted for booking.

    **Typical scenarios:**

    * `book_delivery_now` is `false`
    * Delivery is being prepared or validated
    * Awaiting manual confirmation
  </Accordion>

  <Accordion title="requested">
    The delivery has been submitted to Rendr for orchestration.

    **During this stage:**

    * Carrier eligibility is evaluated
    * Pricing logic is applied
    * SLA and compliance rules are enforced

    The delivery is awaiting successful booking.
  </Accordion>

  <Accordion title="on_hold">
    The delivery has been paused and will not progress until resumed.

    **Reasons may include:**

    * Configuration issues
    * Operational intervention
    * Manual hold by staff
    * Temporary orchestration constraint
  </Accordion>

  <Accordion title="booked">
    A carrier or fulfillment method has accepted the job.

    **At this point:**

    * External booking reference exists
    * Dispatch timing is determined
    * Tracking has been initialized

    <Note>
      In some integrations, `booked` may transition directly to `collected` if the carrier does not expose assignment states.
    </Note>
  </Accordion>

  <Accordion title="assigned">
    A specific driver or service has been allocated. The job is confirmed and awaiting pickup.
  </Accordion>

  <Accordion title="approaching">
    The driver is en route to the pickup location. Typically triggered by carrier tracking events.
  </Accordion>

  <Accordion title="collected">
    The parcel has been collected from the store. The delivery is now in transit to the customer.
  </Accordion>

  <Accordion title="delivered">
    The order has been successfully delivered. This is a **final state**.

    **Proof of delivery may include:**

    * Signature capture
    * Photo confirmation
    * Authority-to-leave confirmation
  </Accordion>
</AccordionGroup>

***

## Exception & Operational States

<AccordionGroup>
  <Accordion title="reassigned">
    The delivery has been reassigned to another courier since the SLA has not been met. Rendr's team has rebooked with another provider to ensure the customer's expectations are met. The lifecycle continues from assignment onward.

    **Typical triggers:**

    | Trigger                  | Description                               |
    | ------------------------ | ----------------------------------------- |
    | Carrier cancellation     | Carrier has cancelled or rejected the job |
    | Failed pickup            | Driver was unable to collect from store   |
    | SLA risk                 | Projected breach requires intervention    |
    | Operational intervention | Manual action by Rendr or merchant team   |

    <Note>
      Reassignment does not create a new delivery ID.
    </Note>
  </Accordion>

  <Accordion title="pending_return">
    Delivery was unsuccessful and requires return to store.

    **Common reasons:**

    * Customer unavailable
    * Access restrictions
    * Compliance constraints
  </Accordion>

  <Accordion title="returned">
    The order has been returned to the store. This is a **final state**.
  </Accordion>

  <Accordion title="cancelled">
    The delivery has been cancelled. Cancellation may occur from most non-final active states. This is a **final state**.
  </Accordion>
</AccordionGroup>

***

## Typical & Exception Flows

### Successful Flow

The most common path for a successfully delivered order:

```
created → requested → booked → assigned → collected → delivered
```

<Note>
  Depending on carrier capabilities, `assigned` and `approaching` may be skipped.
</Note>

### Exception Paths

| Scenario     | Flow                                                         |
| ------------ | ------------------------------------------------------------ |
| Cancellation | `[any active state]` → `cancelled`                           |
| Reassignment | `collected` → `reassigned` → `assigned`                      |
| Return       | `collected` → `pending_return` → `returned`                  |
| Redelivery   | `returned` or `cancelled` → new delivery created with new ID |

***

## Manifest Status (Australia Post)

For Australia Post integrations, a separate `manifest_status` field tracks manifest submission. This operates **independently** from the delivery lifecycle status.

| Value        | Description                            |
| ------------ | -------------------------------------- |
| `pending`    | Booked but not yet added to a manifest |
| `ready`      | Eligible to be manifested              |
| `manifested` | Included in a submitted manifest       |

<Note>
  `manifest_status` does not affect the delivery state machine.
</Note>

***

## Integration Rules

<Warning>
  Final states — `delivered`, `returned`, and `cancelled` — are immutable. No further transitions will occur.
</Warning>

* Statuses only move forward unless explicitly reassigned
* Do not infer intermediate states
* Always rely on webhook payloads or direct retrieval as the source of truth
* For lifecycle behaviour within orchestration, see [Workflow Summary](/documentation/overview/workflow-summary)