Skip to main content
When Nash dispatches a job (delivery) to your organization, the Fleet API is how you report state back as the courier works through it — status transitions, courier location, proof of delivery, courier identity, ETAs, and notes. This guide walks through reporting state for a single delivery, flushing many updates at once, testing transitions in sandbox, and the lifecycle and validation rules that apply. Every dispatch event Nash sends carries a deliveryId. That identifier is what you use on every update for that delivery’s lifetime. Updates only land on deliveries owned by your organization — anything else returns not-found.

​
Reporting state for a single delivery

Use Update Delivery (PATCH /v1/fleet/deliveries/{delivery_id}) to report a change on one delivery. The body is partial — include only the fields that changed.
1

Receive the dispatch and capture the deliveryId

When Nash dispatches the job (delivery) to you, store the deliveryId it carries. You’ll send it on every subsequent update.
2

Report the first assignment

On assignment, send the courier object (name, phone, vehicle, and profile image as available) and a status such as assigned_driver. You can include coordinates and an ETA in the same call.
3

Send progress updates as the delivery moves

As the courier advances, PATCH each transition — pickup_enroute, pickup_arrived, pickup_complete, and so on. coordinates are append-only and safe to send on every location tick, alongside pickupEta / dropoffEta and any pickupNote / dropoffNote.
4

Attach proof of delivery

At pickup or dropoff, include proofOfDelivery — image artifacts (photo or signature) or barcode scans — discriminated by type.
5

Close out the delivery

Send dropoff_complete on success. For a terminal failure, send failed or canceled_by_provider together with a structured failure object. Returns flow through return_in_progress → return_arrived → returned_to_store.
A single update can carry any combination of the following fields:
FieldWhat it carries
statusA lifecycle transition (see Lifecycle & validation).
coordinates{ latitude, longitude } for the courier’s current position. Append-only; safe to resend.
courierCourier identity and vehicle — name, phone, vehicle, profile image.
proofOfDeliveryImage (photo or signature) or barcode artifacts captured at a stop.
failureStructured { code, reason } when the delivery enters failed or canceled_by_provider.
pickupEta / dropoffEtaProvider-supplied ETAs, ISO 8601.
pickupNote / dropoffNoteFree-text notes the courier captured at a stop.
parkingLocation / returnParkingLocationWhere the courier parked at the stop or when returning the package.
externalDeliveryIdYour own identifier for the delivery, for cross-system reconciliation.
The endpoint returns the updated delivery object — the same shape you’d see nested under a job’s task in Get Job.

​
Bulk updates

When you have updates for many deliveries to flush at once, use Bulk Update Deliveries (PATCH /v1/fleet/deliveries). Send a deliveries array of up to 100 items, where each item is the same partial update you’d send to the single endpoint, keyed by its deliveryId. The response returns a results array with one entry per request item, in order. Each result carries:
  • deliveryId — the Nash delivery id.
  • success — whether that item’s update was applied.
  • delivery — the updated delivery, on success.
  • errorCode / errorMessage — failure detail, when success is false.
Per-item failures don’t affect the rest of the batch, so a single bad item won’t roll back the others. Inspect each result’s success flag rather than relying on the overall HTTP status.

​
Testing with Fleet simulators

In sandbox you can exercise your integration without a real courier. Two complementary tools:
  • Fleet simulators — mock fleets that emulate real-world scenarios. FleetSimulator cycles a job through statuses from driver-not-assigned up to dropoff-complete, FleetSimulatorFast does the same on a shorter interval, and FailingFleetSimulator sends a failed status. Simulators start the job based on its scheduled pickup time. See Environments for the full list.
  • Simulate Delivery Status Transition — this endpoint (POST /v1/deliveries/{delivery_id}/simulate) advances a delivery to a specific status on demand, so you can drive your handlers through each state deliberately.
The simulate endpoint is available in dev and sandbox only, and only for deliveries dispatched to the Nash sandbox test provider. The behavior of fleets and fleet simulators is not an indication of how real fleets behave in production.

​
Lifecycle & validation

A typical happy path moves through: 
pickup_enroute → pickup_arrived → pickup_complete →
dropoff_enroute → dropoff_arrived → dropoff_complete
The full set of status values you can send is: not_assigned_driver, assigned_driver, pickup_enroute, pickup_arrived, pickup_complete, dropoff_enroute, dropoff_arrived, dropoff_complete, failed, canceled_by_provider, return_in_progress, return_arrived, returned_to_store. Terminal failures use failed or canceled_by_provider, paired with a structured failure.code. Valid codes are customer_unavailable, address_not_found, out_of_service_area, damage_in_transit, item_unavailable, age_verification_failed, no_capacity, and other, with an optional free-text reason. Validation rules to keep in mind:
  • At least one mutating field is required per update — empty bodies return 422.
  • coordinates.latitude must be in [-90, 90] and coordinates.longitude in [-180, 180].
  • Wire format is camelCase; snake_case is also accepted.
  • Sending the same status twice is a no-op, so updates are safe to retry.

​
Next steps

Fleet overview

How the inbound Fleet API surface fits together.

Update Delivery

PATCH a single delivery’s state.

Bulk Update Deliveries

Flush updates for up to 100 deliveries at once.

Simulate Delivery Status Transition

Drive a sandbox delivery to a given status.