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

# Bulk Update Deliveries

`PATCH /v1/fleet/deliveries`

## Request

- Base URL: `https://api.sandbox.usenash.com`
- URL: `https://api.sandbox.usenash.com/v1/fleet/deliveries`
- Auth: none declared

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' | 'items_pick_complete' | '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. - ``items_pick_complete`` — every item of the order has been picked; the driver is still 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.
    - `pickedItems` PickedItem[], nullable: Every item picked for the delivery so far. Replaces the picked items the delivery holds, so each request sends the whole list, and sending it again changes nothing. Announced by the delivery's `items_pick_update` event when the list changed. At most 64 KB as JSON.
      - `sku` string, required: SKU of the item picked. For a substitution, the substitute's SKU.
      - `requestedSku` string, nullable: SKU the order line asked for.
      - `id` string, nullable: Id of the order line item picked. Leave out for a substitute, which is not an order line.
      - `requestedId` string, nullable: Id of the order line item this row answers.
      - `name` string, nullable: Display name of the item picked.
      - `status` 'picked' | 'partially_picked' | 'not_picked' | 'substituted', required: Outcome for the line.
      - `quantity` integer, required: Units picked. 0 when the item was not picked.
      - `requestedQuantity` integer, nullable: Units the order line asked for.
      - `weight` number, nullable: Weight picked, for an item sold by weight.
      - `weightUnit` string, nullable: Unit of `weight`. E.g. 'kg'.
      - `priceCents` integer, nullable: Price of the item picked, in cents.
      - `scannedBarcode` string, nullable: Barcode scanned at the pick. Leave out for an item with no barcode.
      - `substitutionType` 'no_substitution' | 'pre_selected' | 'override' | 'contact_customer'
      - `substitutionSource` string, nullable: Who listed the order line's substitutes. E.g. 'customer' or 'merchant'.
    - `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
      - `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.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)