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

# Update Delivery

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

## Request

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

Apply a partial update — such as status, courier location, proof of delivery, picked items, 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' | '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.

## 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. `location` is the carrier's scan location, null when none was reported. `injected` marks skipped-status injection only; ETA/GPS-inferred arrivals may be null.
  - `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. When file links are enabled, Nash-hosted photo items include secure_url alongside url. Authenticate with Nash to open secure_url; it redirects to a temporary download URL. Store secure_url, not the redirect target, and do not forward your API key to that target.
  - `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
  - `bonusPayCents` integer, nullable: Bonus pay 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.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)