Skip to main content
PATCH
/
v1
/
jobs
/
{id}
/
{jobConfigurationId}
Update Job by JobID/ExternalIdentifier and Job Configuration ID
curl --request PATCH \
  --url https://api.sandbox.usenash.com/v1/jobs/{id}/{jobConfigurationId} \
  --header 'Content-Type: application/json' \
  --data '{
  "pickupAddress": "<string>",
  "pickupAddressComponents": {
    "number": "1600",
    "secondaryNumber": null,
    "street": "Pennsylvania Avenue NW",
    "county": "Washington",
    "city": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "country": "US",
    "latitude": 38.8948949,
    "longitude": -77.0371581
  },
  "pickupPhoneNumber": "<string>",
  "pickupBusinessName": "<string>",
  "pickupFirstName": "<string>",
  "pickupLastName": "<string>",
  "pickupEmail": "<string>",
  "pickupInstructions": "<string>",
  "pickupStoreLocationId": "<string>",
  "pickupBarcodes": [
    "<string>"
  ],
  "dropoffAddress": "<string>",
  "dropoffAddressComponents": {
    "number": "1600",
    "secondaryNumber": null,
    "street": "Pennsylvania Avenue NW",
    "county": "Washington",
    "city": "Washington",
    "state": "DC",
    "postalCode": "20500",
    "country": "US",
    "latitude": 38.8948949,
    "longitude": -77.0371581
  },
  "dropoffPhoneNumber": "<string>",
  "dropoffBusinessName": "<string>",
  "dropoffFirstName": "<string>",
  "dropoffLastName": "<string>",
  "dropoffEmail": "<string>",
  "dropoffStoreLocationId": "<string>",
  "dropoffInstructions": "<string>",
  "dropoffBarcodes": [
    "<string>"
  ],
  "packageDeliveryMode": "<string>",
  "packagePickupStartTime": "<string>",
  "packagePickupEndTime": "<string>",
  "packageDropoffStartTime": "<string>",
  "packageDropoffEndTime": "<string>",
  "packageDescription": "<string>",
  "packageRequirements": [
    "photo_proof_of_delivery",
    "age_verification_on_delivery"
  ],
  "packageMinimumVehicleSize": "car",
  "packageValue": 123,
  "packageTax": 123,
  "tipAmount": 123,
  "currency": "<string>",
  "packageItems": [
    {}
  ],
  "referenceId": "<string>",
  "itemsCount": 123,
  "weight": 123,
  "externalIdentifier": "<string>",
  "jobMetadata": {},
  "packageMetadata": {}
}'
{
  "id": "job_01234567890",
  "createdAt": "2023-08-29T19:17:46.264523",
  "portalUrl": "https://usenash.com/portal/job_abc123",
  "externalIdentifier": "mini-mart-order-99",
  "jobMetadata": {
    "key": "value"
  },
  "isActive": true,
  "isBatch": false,
  "batch": {
    "id": "<string>",
    "type": "<string>",
    "objectSequence": [
      "<string>"
    ],
    "stopTypes": [
      "PICKUP"
    ],
    "providerId": "<string>",
    "providerIsInternal": true,
    "winnerQuote": {},
    "quotes": [
      {
        "id": "qot_01234567890",
        "type": "<string>",
        "providerId": "uber_standard_mini_mart",
        "providerName": "Nash",
        "providerLogo": "https://nash.com/logo.png",
        "providerIsInternal": true,
        "createdTime": "2021-01-01T00:00:00Z",
        "expireTime": "2021-01-01T00:00:00Z",
        "priceCents": 1000,
        "taxAmountCents": 100,
        "tollFeeCents": 100,
        "nashFeeCents": 100,
        "insuranceFeeCents": 100,
        "currency": "USD",
        "pickupWindow": "2021-01-01T00:00:00Z",
        "dropoffEta": "2021-01-01T00:00:00Z",
        "tags": [
          "tag1",
          "tag2",
          "autodispatch_preferred_quote"
        ],
        "costSplitCustomerCents": 100,
        "costSplitBusinessCents": 100,
        "totalPriceBreakdown": {
          "subtotal": 1000,
          "tax": 100,
          "total": 1100
        },
        "totalPriceCents": 1000,
        "price": 1000,
        "isSuccessful": true,
        "errorMessage": "Error message"
      }
    ],
    "failedQuotes": [
      {}
    ]
  },
  "route": {
    "id": "rte_JphRWDiEosGpXuxwgaYfY3",
    "externalId": "rte_JphRWDiEosGpXuxwgaYfY3",
    "type": "SINGLE_PICKUP_MULTIPLE_DROPOFFS",
    "stops": [
      {
        "stopType": "PICKUP",
        "objectIds": [
          "ord_Qr5bVt8WiByGh66z2g7xEu",
          "ord_WJFuooSiRvFCaceGZjpbqs"
        ],
        "arrivalTime": "2025-04-25T03:27:00",
        "departTime": "2025-04-25T03:30:00",
        "serviceTime": 360,
        "distanceFromPrevious": 3376,
        "durationFromPrevious": 420,
        "location": {
          "lat": 45.558214,
          "lng": -122.587074
        }
      }
    ],
    "jobId": "job_1234567890abcdef12345678",
    "routeMetadata": {
      "priority": "high",
      "source": "optimization_engine"
    }
  },
  "jobConfigurations": [
    {
      "id": "cfg_01234567890",
      "package": {
        "id": "pkg_01234567890",
        "description": "Package description",
        "requirements": [
          "photo_proof_of_delivery",
          "age_verification_on_delivery"
        ],
        "tags": [
          "Alcohol"
        ],
        "packageDeliveryMode": "now",
        "pickupStartTime": "2021-01-01T00:00:00Z",
        "pickupEndTime": "2021-01-01T00:00:00Z",
        "pickupBarcodes": [
          "<string>"
        ],
        "dropoffStartTime": "2021-01-01T00:00:00Z",
        "dropoffEndTime": "2021-01-01T00:00:00Z",
        "dropoffBarcodes": [
          "<string>"
        ],
        "valueCents": 123,
        "taxCents": 100,
        "serviceFeeCents": 100,
        "itemsCount": 100,
        "externalIdentifier": "mini-mart-order-99",
        "minimumVehicleSize": "car",
        "pickupLocation": {
          "id": "loc_01234567890",
          "address": "1600 Amphitheatre Parkway",
          "formattedAddress": "1600 Amphitheatre Parkway",
          "addressNumber": "1600",
          "addressFormattedStreet": "Amphitheatre Parkway",
          "addressCity": "Mountain View",
          "addressCounty": "Santa Clara",
          "addressState": "CA",
          "addressZip": "94043",
          "addressCountry": "US",
          "timezoneId": "America/Los_Angeles",
          "timezoneName": "Pacific Time",
          "instructions": "Turn left on Main St",
          "businessName": "Nash",
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+15555555555",
          "email": "[email protected]",
          "lat": 37.774929,
          "lng": -122.419416
        },
        "pickupStoreLocationId": "store_01234567890",
        "pickupStoreLocationExternalId": "0123",
        "dropoffLocation": {
          "id": "loc_01234567890",
          "address": "1600 Amphitheatre Parkway",
          "formattedAddress": "1600 Amphitheatre Parkway",
          "addressNumber": "1600",
          "addressFormattedStreet": "Amphitheatre Parkway",
          "addressCity": "Mountain View",
          "addressCounty": "Santa Clara",
          "addressState": "CA",
          "addressZip": "94043",
          "addressCountry": "US",
          "timezoneId": "America/Los_Angeles",
          "timezoneName": "Pacific Time",
          "instructions": "Turn left on Main St",
          "businessName": "Nash",
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+15555555555",
          "email": "[email protected]",
          "lat": 37.774929,
          "lng": -122.419416
        },
        "dropoffStoreLocationId": "store_01234567890",
        "drivingMetrics": {
          "distance": 100,
          "duration": 100
        },
        "value": 100,
        "tax": 100,
        "serviceFee": 100,
        "tipAmountCents": 123,
        "weight": 100,
        "dimensions": {
          "height": 100,
          "length": 100,
          "width": 100
        },
        "items": [
          {
            "count": 1,
            "description": "Item 1",
            "valueCents": 100
          }
        ],
        "referenceId": "mini-mart-order-99",
        "packageMetadata": {
          "key": "value"
        }
      },
      "tasks": [
        {
          "id": "tsk_01234567890",
          "createdAt": "2023-08-29T19:17:46.264523",
          "status": "running",
          "pickupStartTime": "2023-08-29T19:17:46.264523",
          "pickupEndTime": "2023-08-29T19:17:46.264523",
          "dropoffStartTime": "2023-08-29T19:17:46.264523",
          "dropoffEndTime": "2023-08-29T19:17:46.264523",
          "providerId": "prv_01234567890",
          "providerIsInternal": true,
          "tipAmountCents": 100,
          "winnerQuote": {
            "id": "qot_01234567890",
            "price_cents": 100
          },
          "quotes": [
            {
              "id": "qot_01234567890",
              "price_cents": 100
            }
          ],
          "failedQuotes": [
            {
              "id": "qot_01234567890",
              "price_cents": 100
            }
          ],
          "delivery": {
            "id": "dlv_01234567890",
            "type": "<string>",
            "status": "dropoff_complete",
            "statusHistory": [
              {
                "created_at": "2023-08-29T19:17:46.264523",
                "status": "created"
              },
              {
                "created_at": "2023-08-29T19:17:47.509265",
                "status": "not_assigned_driver"
              }
            ],
            "isActive": true,
            "pickupEta": "<string>",
            "dropoffEta": "<string>",
            "dropoffDeadline": "<string>",
            "priceCents": 123,
            "currency": "<string>",
            "documents": [
              {
                "createdAt": "<any>",
                "id": "<any>",
                "type": "<any>",
                "url": "<any>",
                "data": "<any>",
                "contentType": "<any>",
                "documentMetadata": "<any>"
              }
            ],
            "nashFeeCents": 123,
            "courierName": "<string>",
            "courierPhoneNumber": "<string>",
            "courierPickupPhoneNumber": "<string>",
            "courierDropoffPhoneNumber": "<string>",
            "courierLocation": {},
            "courierVehicle": {},
            "courierProfileImage": "<string>",
            "proofOfDelivery": [
              {}
            ],
            "providerDeliveryId": "<string>",
            "providerBatchId": "<string>",
            "price": 123,
            "taxAmountCents": 123,
            "tollFeeCents": 123,
            "waitFeeCents": 123,
            "waitTimeMinutes": 123,
            "cancellationFeeCents": 123,
            "returnFeeCents": 123,
            "otherProviderFees": {},
            "insuranceFeeCents": 123,
            "totalPriceBreakdown": {},
            "totalPriceCents": 123,
            "pickedItems": [
              {
                "sku": "<any>",
                "requestedSku": "<any>",
                "id": "<any>",
                "requestedId": "<any>",
                "quantity": "<any>",
                "scannedBarcode": "<any>",
                "weight": "<any>",
                "priceCents": "<any>",
                "status": "<any>",
                "name": "<any>",
                "scans": "<any>"
              }
            ]
          },
          "tipAmountUsd": 100,
          "failureReason": "Task failed",
          "taskNotes": [
            {
              "created_at": "2023-08-29T19:17:46.264523",
              "id": "not_01234567890",
              "note": "Task note",
              "user": {
                "email": "[email protected]"
              }
            }
          ]
        }
      ],
      "advancedTask": {
        "id": "tsk_01234567890",
        "createdAt": "2023-08-29T19:17:46.264523",
        "status": "running",
        "pickupStartTime": "2023-08-29T19:17:46.264523",
        "pickupEndTime": "2023-08-29T19:17:46.264523",
        "dropoffStartTime": "2023-08-29T19:17:46.264523",
        "dropoffEndTime": "2023-08-29T19:17:46.264523",
        "providerId": "prv_01234567890",
        "providerIsInternal": true,
        "tipAmountCents": 100,
        "winnerQuote": {
          "id": "qot_01234567890",
          "price_cents": 100
        },
        "quotes": [
          {
            "id": "qot_01234567890",
            "price_cents": 100
          }
        ],
        "failedQuotes": [
          {
            "id": "qot_01234567890",
            "price_cents": 100
          }
        ],
        "delivery": {
          "id": "dlv_01234567890",
          "type": "<string>",
          "status": "dropoff_complete",
          "statusHistory": [
            {
              "created_at": "2023-08-29T19:17:46.264523",
              "status": "created"
            },
            {
              "created_at": "2023-08-29T19:17:47.509265",
              "status": "not_assigned_driver"
            }
          ],
          "isActive": true,
          "pickupEta": "<string>",
          "dropoffEta": "<string>",
          "dropoffDeadline": "<string>",
          "priceCents": 123,
          "currency": "<string>",
          "documents": [
            {
              "createdAt": "<any>",
              "id": "<any>",
              "type": "<any>",
              "url": "<any>",
              "data": "<any>",
              "contentType": "<any>",
              "documentMetadata": "<any>"
            }
          ],
          "nashFeeCents": 123,
          "courierName": "<string>",
          "courierPhoneNumber": "<string>",
          "courierPickupPhoneNumber": "<string>",
          "courierDropoffPhoneNumber": "<string>",
          "courierLocation": {},
          "courierVehicle": {},
          "courierProfileImage": "<string>",
          "proofOfDelivery": [
            {}
          ],
          "providerDeliveryId": "<string>",
          "providerBatchId": "<string>",
          "price": 123,
          "taxAmountCents": 123,
          "tollFeeCents": 123,
          "waitFeeCents": 123,
          "waitTimeMinutes": 123,
          "cancellationFeeCents": 123,
          "returnFeeCents": 123,
          "otherProviderFees": {},
          "insuranceFeeCents": 123,
          "totalPriceBreakdown": {},
          "totalPriceCents": 123,
          "pickedItems": [
            {
              "sku": "<any>",
              "requestedSku": "<any>",
              "id": "<any>",
              "requestedId": "<any>",
              "quantity": "<any>",
              "scannedBarcode": "<any>",
              "weight": "<any>",
              "priceCents": "<any>",
              "status": "<any>",
              "name": "<any>",
              "scans": "<any>"
            }
          ]
        },
        "tipAmountUsd": 100,
        "failureReason": "Task failed",
        "taskNotes": [
          {
            "created_at": "2023-08-29T19:17:46.264523",
            "id": "not_01234567890",
            "note": "Task note",
            "user": {
              "email": "[email protected]"
            }
          }
        ]
      },
      "delivery": {
        "id": "dlv_01234567890",
        "type": "<string>",
        "status": "dropoff_complete",
        "statusHistory": [
          {
            "created_at": "2023-08-29T19:17:46.264523",
            "status": "created"
          },
          {
            "created_at": "2023-08-29T19:17:47.509265",
            "status": "not_assigned_driver"
          }
        ],
        "isActive": true,
        "pickupEta": "<string>",
        "dropoffEta": "<string>",
        "dropoffDeadline": "<string>",
        "priceCents": 123,
        "currency": "<string>",
        "documents": [
          {
            "createdAt": "<any>",
            "id": "<any>",
            "type": "<any>",
            "url": "<any>",
            "data": "<any>",
            "contentType": "<any>",
            "documentMetadata": "<any>"
          }
        ],
        "nashFeeCents": 123,
        "courierName": "<string>",
        "courierPhoneNumber": "<string>",
        "courierPickupPhoneNumber": "<string>",
        "courierDropoffPhoneNumber": "<string>",
        "courierLocation": {},
        "courierVehicle": {},
        "courierProfileImage": "<string>",
        "proofOfDelivery": [
          {}
        ],
        "providerDeliveryId": "<string>",
        "providerBatchId": "<string>",
        "price": 123,
        "taxAmountCents": 123,
        "tollFeeCents": 123,
        "waitFeeCents": 123,
        "waitTimeMinutes": 123,
        "cancellationFeeCents": 123,
        "returnFeeCents": 123,
        "otherProviderFees": {},
        "insuranceFeeCents": 123,
        "totalPriceBreakdown": {},
        "totalPriceCents": 123,
        "pickedItems": [
          {
            "sku": "<any>",
            "requestedSku": "<any>",
            "id": "<any>",
            "requestedId": "<any>",
            "quantity": "<any>",
            "scannedBarcode": "<any>",
            "weight": "<any>",
            "priceCents": "<any>",
            "status": "<any>",
            "name": "<any>",
            "scans": "<any>"
          }
        ]
      },
      "publicTrackingUrl": "https://usenash.com/tracking/job_abc123"
    }
  ],
  "optionsGroup": {
    "id": "opn_WyMhHj",
    "label": "New York City Strategy",
    "allowedProviders": [
      "prv_01234567890",
      "prv_01234567891"
    ],
    "enableAutoDispatch": true,
    "providerSelectionStrategy": "cheapest",
    "reassignOnFailure": true,
    "enableMaxDeliveryFee": true,
    "maxDeliveryFeeCents": 10000,
    "costSplitMaxFixedPriceCents": 10000,
    "costSplitMaxPercentage": 0.1,
    "costSplitStrategy": "price",
    "smartReassignment": true
  },
  "shortReferenceCode": "<string>"
}

​
Pre Dispatch Updates

Updating a job should always work before a quote is selected. Some updates may result in pricing changes Please note that you are only able to update the package delivery times and the pickup or dropoff addresses before an order has been dispatched to a fleet. If any task in a job is dispatched and a delivery time or address are attempted to be updated, then an error will be thrown by the endpoint. If you update any of the following fields, then the quotes returned by the job will be refreshed and the endpoint will return a new set of quotes. Moreover, any existing quotes (and quote IDs) will be invalid for dispatch. The fields that will force a refresh in the Quotes:
  1. pickupAddress
  2. dropoffAddress
  3. packagePickupStartTime
  4. packagePickupEndTime
  5. packageDropoffStartTime
  6. packageDropoffEndTime
  7. packageDeliveryMode
  8. packageRequirements
  9. packageMinimumVehicleSize
  10. packageValue: for this field, it can also be updated in the post-dispatch stage

​
Note on Updating Times

If you wish to update the times of a Job, you must provide at least one time constraint out of packagePickupStartTime, packagePickupEndTime, packageDropoffStartTime, and packageDropoffEndTime. Times that are not specified will be calculated by Nash, and the previous times not included in the Update Request will be overwritten. Therefore, if you want to update only one time field and keep the rest the same, you must provide them in the parameters of the Update Request.
If you change packageDeliveryMode from SCHEDULED job to NOW, you do not need to specify any other time fields.

​
Post Dispatch Updates

If a quote has been selected or the job is dispatched via auto-dispatch, Nash will return an error if any of the assigned fleets in the job reject the update of the order. In the post-dispatch stage, updating the package value of the job may result in a price change, based on how the providers calculate their pricing. Below is a list of fields that are allowed to be updated, with more details on pre-dispatch or post-dispatch restrictions.

Path Parameters

​
id
string | null
required
​
jobConfigurationId
string | null
required

Body

application/json
​
pickupAddress
string | null
​
pickupAddressComponents
object | null
​
pickupPhoneNumber
string | null
​
pickupBusinessName
string | null
​
pickupFirstName
string | null
​
pickupLastName
string | null
​
pickupEmail
string | null
​
pickupInstructions
string | null
​
pickupStoreLocationId
string | null
​
pickupBarcodes
string[] | null
​
dropoffAddress
string | null
​
dropoffAddressComponents
object | null
​
dropoffPhoneNumber
string | null
​
dropoffBusinessName
string | null
​
dropoffFirstName
string | null
​
dropoffLastName
string | null
​
dropoffEmail
string | null
​
dropoffStoreLocationId
string | null
​
dropoffInstructions
string | null
​
dropoffBarcodes
string[] | null
​
packageDeliveryMode
string | null
​
packagePickupStartTime
string | null
​
packagePickupEndTime
string | null
​
packageDropoffStartTime
string | null
​
packageDropoffEndTime
string | null
​
packageDescription
string | null
​
packageRequirements
Packagerequirements · array
Example:
​
packageMinimumVehicleSize
enum<string> | null
Available options:
any,
bike,
motorbike,
cargobike,
sedan,
car,
suv,
pickup_truck,
pickup,
van,
large_van,
extra_large_van,
truck
Example:
​
packageValue
number | null
​
packageTax
number | null
​
tipAmount
number | null
​
currency
string | null
​
packageItems
Packageitems · object[] | null
​
referenceId
string | null
​
itemsCount
integer | null
​
weight
​
externalIdentifier
string | null
​
jobMetadata
object | null
​
packageMetadata
object | null

Response

​
id
string
required
Example:
​
createdAt
string
required
Example:
​
portalUrl
string
required
Example:
​
isActive
boolean
required
Example:
​
isBatch
boolean
required
Example:
​
batch
object
required
​
route
object | null
required
​
jobConfigurations
JobConfigurationsSerializer · object[]
required
​
externalIdentifier
string | null
Example:
​
jobMetadata
object | null
Example:
​
optionsGroup
object | null
​
shortReferenceCode
string | null