Create or update order by external identifier
This endpoint allows you to create and/or update an order by specifying an ID. Using this endpoint is relevant for checkout workflows, where you can create an order based on the customers cart / order ID and then update it once the customer completes the checkout.
Create or Update Order by External Identifier behavior: If two requests with the same external_id are received, Nash will block the second request until the first request has been committed to the db and the response has been sent to the client. After that, the second request will be processed as an update since the order has already been created by the first request.
This ensures that only one order is created per external_id, even when multiple requests are made simultaneously.
Updating an archived order will also unarchive it.
Path Parameters
The external id of the order to update
"1234567890"
Body
Order input for creating an order.
Order unique identifier from an external system.
The full address in one line for the pickup location. Format: [Number] [Street], [second line], [city], [state], [zip code].
Google place id for the pickup location.
The phone number to contact at the pickup location in the form: '+15555555555'
Pickup business name at the origin. Limited to 80 characters.
First name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
Last name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
Any special instructions for pickup. Limited to 280 characters.
A unique identifier for store location created in Nash.
The external identifier used for your store.
A list of store location IDs (internal or external) to consider for the Order. The optimal store will be selected and returned in the response in pickupStoreLocationId and/or pickupStoreLocationExternalId.
A list of zone IDs to consider for the Order. The pickup store location will be selected later via selected delivery window.
Array containing barcode values that are required to be scanned at the pickup waypoint.
The email of the contact at the pickup location.
The full address in one line for the dropoff location. Format: [Number] [Street], [second line], [city], [state], [zip code].
Google place id for the dropoff location.
The phone number to contact at the dropoff location in the form: '+15555555555'
Name of the business at the destination. Should be left empty if there is no business. Limited to 80 characters.
First name of the contact at the destination. Limited to 80 characters.
Last name of the contact at the destination. Limited to 80 characters.
Any special instructions for dropoff. Limited to 280 characters.
Array containing barcode values/types that are required to be scanned at the dropoff waypoint.
The email of the contact at the dropoff location.
'now' or 'scheduled' when the delivery should be scheduled
The earliest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
The latest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
The earliest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
The latest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
Delivery window id if using Nash delivery windows
Order description and notes. Limited to 280 characters.
The number of items in this order
Local currency
Order value in cents
Tip paid to the driver in cents
Package requirements.
Detailed description: https://docs.usenash.com/reference/package-requirements.
photo_proof_of_delivery, signature_proof_of_delivery, photo_proof_of_pickup, signature_proof_of_pickup, age_verification_on_delivery, id_verification_on_delivery, barcode_scan_on_pickup, barcode_scan_on_dropoff, meet_on_delivery, shipping_label, two_person_team, pincode_verification, schedule_ii_controlled_substances, alcohol, parking_check_in, display_barcode_on_pickup [
"photo_proof_of_delivery",
"age_verification_on_delivery"
]
The requested minimum vehicle size. Allowed values: ['any', 'bike', 'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck', 'pickup', 'van', 'truck']
any, bike, motorbike, cargobike, sedan, car, suv, pickup_truck, pickup, van, truck "car"
The dispatch strategy id (or option group id) to be associated with the order
Key-value data to attach to this order.
Optional order tags, they will be included in every response
A non-unique identifier for orders, visible to the courier if supported by the provider.
The number on a house.
Secondary number on an address e.g. an apartment building.
The street of the address.
The city of the pickup address.
The county associated with the pickup address.
The state of the pickup address.
The zip or postal code of the pickup address.
The ISO 3166-1 alpha-2 country code of the pickup address.
The pickup latitude coordinate.
The pickup longitude coordinate.
The number on a house.
Secondary number on an address e.g. an apartment building.
The street of the address.
The city of the dropoff address.
The county associated with the dropoff address.
The state of the dropoff address.
The zip or postal code of the dropoff address.
The ISO 3166-1 alpha-2 country code of the dropoff address.
The dropoff latitude coordinate.
The dropoff longitude coordinate.
The total weight of the package in kilograms (kg)
The total height of the package in centimeters (cm)
The total width of the package in centimeters (cm)
The total depth of the package in centimeters (cm)
Lists of items in the delivery
Order-level optimization parameters
If set to true, the order will be re-evaluated with automations.
Response
The id of the order
"ord_1234567890"
The date and time when the order was created
"2023-08-29T19:17:46.264523"
The URL of the order in the Nash portal
"https://portal.dev.usenash.com/orders/ord_1234567890"
The URL of the order in the public tracking system
"https://tracking.dev.usenash.com/ord_1234567890"
The status of the order
"needs_attention"
The tags of the order
["quotes_only"]
The external id of the order
"1234567890"
A non-unique identifier for orders, visible to the courier if supported by the provider.
"1234567890"
Key-value data to attach to Nash Jobs.
{ "key": "value" }
The pickup address of the order
"185 University Ave, Palo Alto, CA 94301"
Google place id for the pickup location.
"ChIJd8BlQJq3t4kRUKhH43CQ"
The number on a house.
"185"
Secondary number on an address e.g. an apartment building.
The street of the address.
"University Ave"
The city of the pickup address.
"Palo Alto"
The county associated with the pickup address.
"Santa Clara"
The state of the pickup address.
"CA"
The zip or postal code of the pickup address.
"94301"
The ISO 3166-1 alpha-2 country code of the pickup address.
"US"
The pickup latitude coordinate.
37.422222
The pickup longitude coordinate.
-122.139776
The phone number to contact at the pickup location in the form: '+15555555555'
"+15555555555"
First name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
"Manager"
Last name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.
"Manager"
Pickup business name at the origin.
"Store ABC"
Any special instructions for pickup.
"Leave at the front door"
A unique identifier for store location created in Nash.
"stl_VwpoPJaaqWiPGnXEhWfX"
The external identifier used for your store.
"0021112"
A list of zone IDs to consider for the Order. The pickup store location will be selected later via selected delivery window.
Array containing barcode values that are required to be scanned at the pickup waypoint.
["1234567890", "0987654321"]
The dropoff address of the order
"401 San Antonio Rd, Mountain View, CA 94040"
Google place id for the dropoff location.
"ChIJd8BlQJq3t4kRUKhH43CQ"
The number on a house.
"401"
Secondary number on an address e.g. an apartment building.
The street of the address.
"San Antonio Rd"
The city of the dropoff address.
"Mountain View"
The county associated with the dropoff address.
"Santa Clara"
The state of the dropoff address.
"CA"
The zip or postal code of the dropoff address.
"94040"
The ISO 3166-1 alpha-2 country code of the dropoff address.
"US"
The dropoff latitude coordinate.
37.422222
The dropoff longitude coordinate.
-122.139776
The phone number to contact at the dropoff location in the form: '+15555555555'
"+15555555556"
First name of the contact at the destination.
"Quote"
Last name of the contact at the destination.
"Request"
Dropoff business name at the destination.
Any special instructions for dropoff.
"Leave at the front door"
A unique identifier for store location created in Nash.
Array containing barcode values that are required to be scanned at the dropoff waypoint.
The delivery mode of the order
"scheduled"
The start time of the pickup window.
"2024-08-22T23:54:08Z"
The end time of the pickup window.
"2024-08-22T23:54:08Z"
The start time of the dropoff window.
"2024-08-22T23:54:08Z"
The end time of the dropoff window.
"2024-08-22T23:54:08Z"
The description of the order
"Order description"
The number of items in the order
"1"
The requirements of the order
["photo_proof_of_delivery"]
The requested minimum vehicle size. Allowed values: ['any', 'bike', 'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck', 'pickup', 'van', 'truck']
any, bike, motorbike, cargobike, sedan, car, suv, pickup_truck, pickup, van, truck "car"
The currency of the order
"USD"
The value of the order in cents
"10000"
The tip amount of the order in cents
"1000"
The width of the order in cm
"100"
The depth of the order in cm
"100"
The height of the order in cm
"100"
The volume of the order in cm^3
The weight of the order in kg
"100"
The items of the order
The dispatch strategy id of the order
"dss_1234567890"
The documents of the order
Document object returned by the API.
[
{
"contentType": "application/pdf",
"data": "SGVsbG8gd29ybGQ=",
"id": "doc_1234567890",
"type": "shipping_label",
"url": "https://example.com/document.pdf"
}
]
The validation errors of the order
{ "pickupStartTime": "Time is in the past" }
The quotes of the order
Generic serializer for quotes used in many endpoints.
[
{
"costSplitBusinessCents": null,
"costSplitCustomerCents": null,
"createdTime": "2024-09-03T20:43:45.899094",
"currency": "USD",
"dropoffEta": "2024-09-03T22:20:47.569000",
"expireTime": "2024-09-03T21:43:45.899102",
"id": "qot_2oWASjGxMtucwGgu6A7BYC",
"insuranceFeeCents": 0,
"nashFeeCents": 300,
"pickupWindow": null,
"priceCents": 100,
"providerId": "dispatch_partner",
"providerIsInternal": false,
"providerLogo": "https://nash-provider-logos.s3.amazonaws.com/dispatchit-logo.jpg",
"providerName": "Dispatch",
"tags": null,
"taxAmountCents": null,
"tollFeeCents": 0,
"totalPriceBreakdown": { "priceCents": 100 },
"totalPriceCents": 100,
"type": "LOCAL"
}
]
The failed quotes of the order
["quote_1234567890", "quote_0987654321"]