---
title: "Update Delivery"
method: PATCH
path: "/v1/fleet/deliveries/{delivery_id}"
tags: ["Fleet"]
---

# Update Delivery

`PATCH /v1/fleet/deliveries/{delivery_id}`

Apply a partial update — such as status, courier location, proof of delivery, courier identity, or ETAs — to a delivery your organization owns. Only available for deliveries fulfilled by your own fleet (not by a third-party courier integration). Returns the updated delivery.

## Path parameters

- `delivery_id` string, required — The Nash delivery id to update.

## Request body

- DeliveryUpdate — Partial update for a delivery dispatched to a Nash-connected provider.
  - `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.

## Response `200`

OK

- DeliverySerializer — Generic serializer for deliveries used in many endpoints. Some endpoints won't return all fields, so they are optional. This means that they will return field names with null values.
  - `id` string, required — Delivery ID
  - `type` string, nullable
  - `status` string, required — Delivery status
  - `statusHistory` object[], nullable — Delivery status history
  - `isActive` boolean, required — Is the delivery active
  - `pickupEta` string, nullable — Pickup ETA
  - `dropoffEta` string, nullable — Dropoff ETA
  - `dropoffDeadline` string, nullable — Dropoff deadline
  - `priceCents` integer, required — Price in cents
  - `currency` string, required — Currency
  - `documents` DocumentSerializer[], nullable — Documents
    - `createdAt` string, required
    - `id` string, required
    - `type` string, required
    - `url` string, nullable
    - `data` string, binary, nullable
    - `contentType` string, required
    - `documentMetadata` object, nullable
  - `nashFeeCents` integer, nullable — Nash fee in cents
  - `courierName` string, nullable — Courier name
  - `courierPhoneNumber` string, nullable — Courier phone number
  - `courierPickupPhoneNumber` string, nullable — Courier pickup phone number
  - `courierDropoffPhoneNumber` string, nullable — Courier dropoff phone number
  - `courierLocation` object, nullable — Courier location
  - `courierVehicle` object, nullable — Courier vehicle
  - `courierProfileImage` string, nullable — Courier profile image
  - `proofOfDelivery` object[], nullable — Proof of delivery
  - `providerDeliveryId` string, nullable — Provider delivery id
  - `providerBatchId` string, nullable — Provider batch id
  - `price` number, nullable — Price
  - `taxAmountCents` integer, nullable — Tax amount in cents
  - `tollFeeCents` integer, nullable — Toll fee in cents
  - `waitFeeCents` integer, nullable — Wait fee in cents
  - `waitTimeMinutes` integer, nullable — Wait time in minutes
  - `cancellationFeeCents` integer, nullable — Cancellation fee in cents
  - `returnFeeCents` integer, nullable — Return fee in cents
  - `otherProviderFees` object, nullable — Other provider fees
  - `insuranceFeeCents` integer, nullable — Insurance fee in cents
  - `totalPriceBreakdown` object, nullable — Total price breakdown
  - `totalPriceCents` integer, nullable — Total price in cents
  - `pickedItems` PickedItemsSerializer[], nullable — Picked items
    - `sku` string, nullable
    - `requestedSku` string, nullable
    - `id` string, nullable
    - `requestedId` string, nullable
    - `quantity` integer, nullable
    - `requestedQuantity` integer, nullable
    - `scannedBarcode` string, nullable
    - `weight` number, nullable
    - `priceCents` integer, nullable
    - `status` string, nullable — Per-item fulfillment outcome at pick time. One of: `picked`, `partially_picked`, `not_picked`, `substituted`.
    - `name` string, nullable
    - `scans` ItemScanSerializer[], nullable
      - `substitutionType` string, nullable
      - `barcodes` BarcodeInfoSerializer[], nullable
        - `weight` number, nullable
        - `priceCents` integer, nullable
        - `weightUnit` string, nullable
        - `productCode` string, nullable
        - `isVariableWeight` boolean, nullable
        - `barcode` string, nullable
        - `variableValue` number, nullable
        - `format` string, nullable
        - `indicatorDigit` string, nullable
        - `checkDigit` string, nullable
        - `manufacturerCode` string, nullable
        - `itemReference` string, nullable
        - `pluCheckDigit` string, nullable
        - `barcodeSansCheckDigit` string, nullable
        - `expirationDate` string, nullable

## 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)