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

# Overview

> How a fleet reports delivery state back to Nash.

The Fleet API is the inbound surface a fleet uses to report state on deliveries Nash has dispatched to it — courier location, status transitions, proof of delivery, courier identity, ETAs, and notes.

Use it whether you're a merchant operating your own couriers or a third-party fleet receiving Nash demand. The contract is the same in both cases: Nash dispatches an order to your organization, you fulfill it, and you `PATCH` updates back as the delivery progresses.

## When updates start

Each dispatch event Nash sends carries a `deliveryId`. That's the identifier you use on every update for that delivery's lifetime. Updates only land on deliveries owned by your organization — anything else returns not-found.

## Two endpoints

| Endpoint                                   | Use when                                                                                                          |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `PATCH /v1/fleet/deliveries/{delivery_id}` | A single delivery changed state.                                                                                  |
| `PATCH /v1/fleet/deliveries`               | You want to flush updates for up to 100 deliveries at once. Per-item failures don't affect the rest of the batch. |

Both accept partial bodies — only the fields you want to change need to be present.

## Lifecycle

A typical happy path moves through:

```
pickup_enroute → pickup_arrived → pickup_complete →
dropoff_enroute → dropoff_arrived → dropoff_complete
```

Terminal failures use `failed` or `canceled_by_provider`, paired with a structured `failure.code` (e.g. `customer_unavailable`, `address_not_found`, `no_capacity`). Returns flow through `return_in_progress → return_arrived → returned_to_store`.

Sending the same status twice is a no-op, so it's safe to retry.

## What you can include in a single call

A single update can carry any combination of:

* **`status`** — lifecycle transition.
* **`coordinates`** — `{ latitude, longitude }`. Append-only; safe to send on every tick.
* **`courier`** — name, phone, vehicle, profile image. Send on first assignment, or any subset on a mid-flight swap.
* **`proofOfDelivery`** — image artifacts (photo / signature at pickup or dropoff) or barcode scans.
* **`failure`** — structured `{ code, reason }` for `failed` / `canceled_by_provider`.
* **`pickupEta` / `dropoffEta`** — provider-supplied ETAs.
* **`pickupNote` / `dropoffNote`** — free text the courier captured.
* **`externalDeliveryId`** — your own identifier for this delivery, for cross-system reconciliation.

## Validation

* At least one mutating field is required per update — empty bodies return `422`.
* `coordinates.latitude` must be in `[-90, 90]`, `longitude` in `[-180, 180]`.
* Wire format is camelCase; snake\_case is also accepted.

## Response shape

Both endpoints return the same delivery object you'd see nested under a job's task in `GET /v1/jobs/{id}`. The bulk response wraps each item with a per-item `success` flag and either the updated delivery or a structured error.