> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sparqle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order lifecycle

> Every status a Sparqle order moves through, and what each one means.

Each order carries a `status`. Over the API and in [webhooks](/webhooks), the
status is the lowercase value in the **API value** column below (for example
`in_transit`). Statuses progress as the parcel is printed, scanned, and
delivered — with separate branches for returns and exceptions.

## Happy path

<Steps>
  <Step title="draft">
    The order was created and accepted. No label scanned yet.
  </Step>

  <Step title="expected">
    A label has been printed. Sparqle is expecting the parcel to enter the
    network.
  </Step>

  <Step title="in_transit">
    The parcel has had its first carrier scan and is moving through the network.
  </Step>

  <Step title="out_for_delivery">
    In the bike, en route from the local depot to the recipient.
  </Step>

  <Step title="completed">
    Delivered. This is the terminal success state.
  </Step>
</Steps>

## All statuses

| API value               | Meaning                                                     |
| ----------------------- | ----------------------------------------------------------- |
| `draft`                 | Order created and accepted.                                 |
| `expected`              | Label printed; parcel expected in the network.              |
| `in_transit`            | First scan received; moving through the middle mile.        |
| `out_for_delivery`      | En route from the local depot to the recipient.             |
| `awaiting_next_attempt` | A delivery attempt was made; another is scheduled.          |
| `at_pickup_point`       | Available for collection at a pickup point.                 |
| `completed`             | Delivered. Terminal success state.                          |
| `failed`                | Delivery failed, including after second attempts.           |
| `in_return_transit`     | Being returned to sender.                                   |
| `returned`              | Returned and received back at the origin address.           |
| `cancelled`             | Cancelled before dispatch.                                  |
| `rejected`              | Rejected (for example, not serviceable).                    |
| `address_not_found`     | The delivery address could not be resolved.                 |
| `inactive`              | Label printed but never scanned within a reasonable window. |
| `missing`               | Previously scanned but cannot currently be located.         |
| `lost`                  | A missing parcel confirmed lost. Terminal.                  |
| `error`                 | An internal processing error occurred.                      |

## Cancelling an order

You can cancel an order using `PATCH /orders/cancel/{orderId}`. Succesfull cancellation depends on the order status. Up until `in_transit` every order can be cancelled. Once a parcel is `out_for_delivery` or beyond,
it may depend on the specific order if it can be cancelled. This can not be inferred from the API.

<Note>
  Terminal states (`completed`, `returned`, `lost`, `cancelled`) won't change
  again.
</Note>