> ## Documentation Index
> Fetch the complete documentation index at: https://afrizon-admin.tunzaa.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Track and manage order deliveries in Meneja dashboard

> Assign delivery partners, track shipment stages, add pickup points, and monitor the real-time progress of every order delivery in Meneja.

Once an order is confirmed, you can assign a delivery partner and track its progress through each stage of the fulfillment journey. Meneja records every stage transition with a timestamp and partner identifier, giving you a full audit trail from pickup to final delivery.

## Delivery record structure

A delivery record is created when you assign a delivery partner to an order. It contains the following fields:

| Field                     | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `id`                      | Unique delivery identifier                                        |
| `order_id`                | The order this delivery belongs to                                |
| `pickup_points`           | Array of `PickupPoint` objects (partner and timestamp)            |
| `stages`                  | Array of `DeliveryStage` objects recording each status transition |
| `current_stage`           | The active `DeliveryStageType` value                              |
| `estimated_delivery_time` | Expected delivery timestamp, or `null`                            |
| `actual_delivery_time`    | Confirmed delivery timestamp, or `null`                           |
| `created_at`              | When the delivery record was created                              |
| `updated_at`              | When the delivery record was last modified                        |

## Delivery stages

Each entry in the `stages` array represents a transition in the delivery lifecycle and contains:

| Field        | Description                                               |
| ------------ | --------------------------------------------------------- |
| `partner_id` | The delivery partner responsible at this stage            |
| `stage`      | The `DeliveryStageType` value for this transition         |
| `proof`      | Optional proof-of-delivery reference, or `null`           |
| `timestamp`  | ISO timestamp of when this stage was recorded             |
| `location`   | Optional `{ latitude, longitude }` coordinates, or `null` |

### Stage values

| Stage        | Meaning                                           |
| ------------ | ------------------------------------------------- |
| `assigned`   | A delivery partner has been assigned to the order |
| `at_pickup`  | The partner has arrived at the pickup location    |
| `in_transit` | The parcel is on its way to the customer          |
| `delivered`  | The parcel has been delivered successfully        |
| `failed`     | A delivery attempt failed                         |
| `cancelled`  | The delivery was cancelled                        |

The `current_stage` field always reflects the most recent stage in the `stages` array.

<Note>
  The delivery detail view shows the full stage history in chronological order, so you can see exactly when each transition occurred and which partner was responsible.
</Note>

## Pickup points

Pickup points record the intermediate handoff locations where a partner collects the parcel. Each `PickupPoint` contains:

| Field        | Description                                        |
| ------------ | -------------------------------------------------- |
| `partner_id` | The partner who collected the parcel at this point |
| `timestamp`  | When the pickup occurred                           |

## Assigning a delivery partner

To assign a delivery partner to an order, you create a new delivery record. The following fields are required:

| Field                     | Required | Description                                                            |
| ------------------------- | -------- | ---------------------------------------------------------------------- |
| `order_id`                | Yes      | The order to assign the delivery to                                    |
| `stages`                  | Yes      | Initial array of `DeliveryStage` entries                               |
| `current_stage`           | Yes      | The starting stage: `assigned`, `in_transit`, `delivered`, or `failed` |
| `pickup_points`           | No       | Optional array of `PickupPoint` entries                                |
| `estimated_delivery_time` | No       | Expected delivery timestamp                                            |

<Steps>
  <Step title="Open the order detail view">
    Navigate to **Orders** and click the order you want to assign a delivery partner to. The order must be in a status that allows fulfillment (for example, `confirmed`).
  </Step>

  <Step title="Open the delivery section">
    Scroll to the **Delivery** section of the order detail view. If no delivery has been assigned yet, you will see an option to assign a partner.
  </Step>

  <Step title="Select a delivery partner">
    Choose the delivery partner from the available list. The system creates a delivery record with the initial stage set to `assigned`.
  </Step>

  <Step title="Confirm the assignment">
    Submit the form. The delivery record is created and `current_stage` is set to `assigned`.
  </Step>
</Steps>

## Adding a delivery stage

As the delivery progresses, you can record each stage transition. The following fields are required:

| Field        | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| `partner_id` | The partner responsible for this stage                            |
| `stage`      | The new stage: `assigned`, `in_transit`, `delivered`, or `failed` |

<Steps>
  <Step title="Open the delivery detail">
    From the order detail view, open the delivery record. You can also access deliveries directly from the **Deliveries** section of the dashboard.
  </Step>

  <Step title="Add a new stage">
    Use the **Add Stage** action and select the appropriate `stage` value. The new stage is appended to the `stages` array and `current_stage` is updated automatically.
  </Step>
</Steps>

<Warning>
  Stage transitions are permanent. Once a stage is added to the delivery record, it cannot be removed.
</Warning>

## Filtering deliveries

You can filter the deliveries list by the following criteria:

| Filter      | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `search`    | Search by order number or delivery ID                            |
| `status`    | Filter by delivery status: `active`, `completed`, or `cancelled` |
| `stage`     | Filter by a specific `DeliveryStageType`                         |
| `partnerId` | Show deliveries for a specific partner                           |
| `orderId`   | Look up the delivery for a specific order                        |