---
title: "Bulk Update Deliveries"
method: PATCH
path: "/v1/fleet/deliveries"
tags: ["Fleet"]
---

# Bulk Update Deliveries

`PATCH /v1/fleet/deliveries`

Apply updates to up to 100 deliveries in a single request. Each item is keyed by exactly one of `deliveryId` or `packageExternalIdentifier` (your own id set on the package at creation), plus the same field set as the single-delivery endpoint. The per-item result echoes back the key you sent under `deliveryId`. Per-item failures come back as a structured error in the response and do not affect the rest of the batch.

## Request body

- BulkDeliveryUpdateRequest — Top-level body for ``PATCH /v1/deliveries`` (bulk update).
  - `deliveries` BulkDeliveryUpdateItem[], required — Delivery updates to apply (max 100).
    - `status` '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' — Lifecycle states a fleet can report for a delivery. Ordered roughly chronologically: - ``not_assigned_driver`` — provider received the dispatch but hasn't found a driver. - ``assigned_driver`` — a driver has accepted the dispatch but hasn't departed. - ``pickup_enroute`` — driver is on the way to the pickup location. - ``pickup_arrived`` — driver is at the pickup location. - ``pickup_complete`` — package has been picked up. - ``dropoff_enroute`` — driver is on the way to the customer. - ``dropoff_arrived`` — driver is at the customer. - ``dropoff_complete`` — package delivered (terminal success). - ``failed`` — delivery aborted; pair with ``failure`` block (terminal). - ``canceled_by_provider`` — provider canceled the dispatch (terminal). - ``return_in_progress`` — package is being returned to the pickup location. - ``return_arrived`` — driver is at the pickup location to return. - ``returned_to_store`` — package returned (terminal).
    - `coordinates` Coordinates — Latitude / longitude pair for the courier's current location.
      - `latitude` number, required — Latitude in decimal degrees.
      - `longitude` number, required — Longitude in decimal degrees.
    - `proofOfDelivery` union[], nullable — Proof artifacts captured at the stop. Image or barcode, discriminated by `podType`.
      - union
        - ImageProof — Image-based proof captured at pickup or dropoff (photo or signature).
          - `podType` 'photo_proof_of_delivery' | 'signature_proof_of_delivery' | 'photo_proof_of_pickup' | 'signature_proof_of_pickup' | 'photo_pre_delivery_verification', required — Type of image artifact.
          - `imageUrl` string, required — URL of the captured image.
        - BarcodeProof — Barcode scan recorded at pickup, dropoff, or during a return.
          - `podType` 'barcode_scan_on_pickup' | 'barcode_scan_on_dropoff' | 'barcode_scan_on_return', required — Type of barcode scan.
          - `value` string, required — The scanned barcode string.
          - `status` 'success' | 'invalid' | 'failure' | 'skipped' | 'manually_entered' | 'damaged', required — Outcome of the scan.
    - `courier` Courier — Identity and vehicle for the courier currently handling the delivery. Send the full block when a courier is first assigned, or any subset when one of the fields changes (e.g., a driver swap mid-flight).
      - `name` string, nullable — Courier's display name.
      - `phoneNumber` string, nullable — Courier's phone number, E.164.
      - `pickupPhoneNumber` string, nullable — Proxy phone for the pickup contact, if issued.
      - `dropoffPhoneNumber` string, nullable — Proxy phone for the customer, if issued.
      - `profileImageUrl` string, nullable — URL of the courier's profile image.
      - `vehicle` CourierVehicle — Vehicle the courier is using to fulfill the delivery.
        - `make` string, nullable — Vehicle make. E.g. 'Toyota'.
        - `model` string, nullable — Vehicle model. E.g. 'Prius'.
        - `color` string, nullable — Vehicle color. E.g. 'white'.
        - `licensePlate` string, nullable — License plate.
      - `externalId` string, nullable — Provider's own courier identifier.
    - `failure` DeliveryFailure — Structured cause when a delivery enters ``failed`` or ``canceled_by_provider``.
      - `code` 'customer_unavailable' | 'address_not_found' | 'out_of_service_area' | 'damage_in_transit' | 'item_unavailable' | 'age_verification_failed' | 'no_capacity' | 'other', required — Structured failure / cancellation code paired with optional free-text reason. Stable across providers so analytics, reassignment policy, and merchant notifications can branch on the cause rather than parsing strings. Used for both ``failed`` and ``canceled_by_provider`` status transitions.
      - `reason` string, nullable — Free-text detail.
    - `pickupNote` string, nullable — Note from the courier at pickup. E.g. 'used the side door'.
    - `dropoffNote` string, nullable — Note from the courier at dropoff. E.g. 'left with concierge'.
    - `parkingLocation` string, nullable — Where the courier parked at the stop. E.g. 'loading bay 4'.
    - `returnParkingLocation` string, nullable — Where the courier parked when returning the package to the pickup location.
    - `pickupEta` string, date-time, nullable — Estimated pickup arrival time. ISO 8601.
    - `dropoffEta` string, date-time, nullable — Estimated dropoff arrival time. ISO 8601.
    - `externalDeliveryId` string, nullable — Provider's own identifier for this delivery.
    - `deliveryId` string, nullable — Nash delivery id. Provide this OR packageExternalIdentifier, not both.
    - `packageExternalIdentifier` string, nullable — Your own identifier set on the package at creation. Provide this OR deliveryId, not both. Resolves the delivery server-side.

## Response `200`

OK

- BulkDeliveryUpdateResponse — Top-level response for ``PATCH /v1/deliveries``.
  - `results` BulkDeliveryUpdateResultItem[], required — One result per request item, in order.
    - `deliveryId` string, required — Echoes the key the caller sent: a Nash delivery id or a packageExternalIdentifier.
    - `success` boolean, required — Whether the update was applied.
    - `errorCode` string, nullable — Error code if `success` is false.
    - `errorMessage` string, nullable — Error detail if `success` is false.
    - `delivery` object, nullable — Updated delivery on success.

## Other responses

- `422` — Unprocessable Content

---

[API](https://skmtc.net/usenash/apis/nash-api.md) · [All operations](https://skmtc.net/usenash/apis/nash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usenash/nash-api/revisions/09a23a95889b/schema)