Skip to main content

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.

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

EndpointUse when
PATCH /v1/fleet/deliveries/{delivery_id}A single delivery changed state.
PATCH /v1/fleet/deliveriesYou 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.