POST
/
v1
/
order
/
external-identifier
/
{externalId}

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.

Note: 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.

Path Parameters

externalId
string
required

The external id of the order to update

Body

application/json

Order input for creating an order.

externalId
string | null

Order unique identifier from an external system.

pickupAddress
string | null

The full address in one line for the pickup location. Format: [Number] [Street], [second line], [city], [state], [zip code].

pickupPlaceId
string | null

Google place id for the pickup location.

pickupPhoneNumber
string | null

The phone number to contact at the pickup location in the form: '+15555555555'

pickupBusinessName
string | null

Pickup business name at the origin. Limited to 80 characters.

pickupFirstName
string | null

First name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.

pickupLastName
string | null

Last name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.

pickupInstructions
string | null

Any special instructions for pickup. Limited to 280 characters.

pickupStoreLocationId
string | null

A unique identifier for store location created in Nash.

pickupExternalStoreLocationId
string | null

The external identifier used for your store.

pickupBarcodes
string[] | null

Array containing barcode values that are required to be scanned at the pickup waypoint.

pickupEmail
string | null

The email of the contact at the pickup location.

dropoffAddress
string | null

The full address in one line for the dropoff location. Format: [Number] [Street], [second line], [city], [state], [zip code].

dropoffPlaceId
string | null

Google place id for the dropoff location.

dropoffPhoneNumber
string | null

The phone number to contact at the dropoff location in the form: '+15555555555'

dropoffBusinessName
string | null

Name of the business at the destination. Should be left empty if there is no business. Limited to 80 characters.

dropoffFirstName
string | null

First name of the contact at the destination. Limited to 80 characters.

dropoffLastName
string | null

Last name of the contact at the destination. Limited to 80 characters.

dropoffInstructions
string | null

Any special instructions for dropoff. Limited to 280 characters.

dropoffBarcodes
string[] | null

Array containing barcode values/types that are required to be scanned at the dropoff waypoint.

dropoffEmail
string | null

The email of the contact at the dropoff location.

deliveryMode
string | null

'now' or 'scheduled' when the delivery should be scheduled

pickupStartTime
string | null

The earliest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'

pickupEndTime
string | null

The latest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'

dropoffStartTime
string | null

The earliest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'

dropoffEndTime
string | null

The latest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'

description
string | null

Order description and notes. Limited to 280 characters.

itemsCount
integer | null

The number of items in this order

currency
string | null

Local currency

valueCents

Order value in cents

tipAmountCents
integer | null

Tip paid to the driver in cents

requirements

Package requirements.

Available options:
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
minimumVehicleSize
string | null

The requested minimum vehicle size.

dispatchStrategyId
string | null

The dispatch strategy id (or option group id) to be associated with the order

orderMetadata
object | null

Key-value data to attach to this order.

tags
string[] | null

Optional order tags, they will be included in every response

referenceId
string | null

A non-unique identifier for orders, visible to the courier if supported by the provider.

pickupAddressNumber
string | null

The number on a house.

pickupAddressSecondarynumber
string | null

Secondary number on an address e.g. an apartment building.

pickupAddressFormattedStreet
string | null

The street of the address.

pickupAddressCity
string | null

The city of the pickup address.

pickupAddressCounty
string | null

The county associated with the pickup address.

pickupAddressState
string | null

The state of the pickup address.

pickupAddressZip
string | null

The zip or postal code of the pickup address.

pickupAddressCountry
string | null

The ISO 3166-1 alpha-2 country code of the pickup address.

pickupLat
number | null

The pickup latitude coordinate.

pickupLng
number | null

The pickup longitude coordinate.

dropoffAddressNumber
string | null

The number on a house.

dropoffAddressSecondarynumber
string | null

Secondary number on an address e.g. an apartment building.

dropoffAddressFormattedStreet
string | null

The street of the address.

dropoffAddressCity
string | null

The city of the dropoff address.

dropoffAddressCounty
string | null

The county associated with the dropoff address.

dropoffAddressState
string | null

The state of the dropoff address.

dropoffAddressZip
string | null

The zip or postal code of the dropoff address.

dropoffAddressCountry
string | null

The ISO 3166-1 alpha-2 country code of the dropoff address.

dropoffLat
number | null

The dropoff latitude coordinate.

dropoffLng
number | null

The dropoff longitude coordinate.

weight

The total weight of the package in kilograms (kg)

height

The total height of the package in centimeters (cm)

width

The total width of the package in centimeters (cm)

depth

The total depth of the package in centimeters (cm)

requestedDeliveryWindow
object | null

Specify the delivery window time slot that the end customer requested this order to be delivered in

items
object[] | null

Lists of items in the delivery

optimizationParameters
object | null

Order-level optimization parameters

Response

200 - application/json
id
string
required

The id of the order

createdAt
string
required

The date and time when the order was created

externalId
string | null

The external id of the order

referenceId
string | null

A non-unique identifier for orders, visible to the courier if supported by the provider.

portalUrl
string
required

The URL of the order in the Nash portal

publicTrackingUrl
string
required

The URL of the order in the public tracking system

status
string
required

The status of the order

tags
string[]
required

The tags of the order

orderMetadata
object | null

Key-value data to attach to Nash Jobs.

pickupAddress
string | null

The pickup address of the order

pickupPlaceId
string | null

Google place id for the pickup location.

pickupAddressNumber
string | null

The number on a house.

pickupAddressSecondarynumber
string | null

Secondary number on an address e.g. an apartment building.

pickupAddressFormattedStreet
string | null

The street of the address.

pickupAddressCity
string | null

The city of the pickup address.

pickupAddressCounty
string | null

The county associated with the pickup address.

pickupAddressState
string | null

The state of the pickup address.

pickupAddressZip
string | null

The zip or postal code of the pickup address.

pickupAddressCountry
string | null

The ISO 3166-1 alpha-2 country code of the pickup address.

pickupLat
number | null

The pickup latitude coordinate.

pickupLng
number | null

The pickup longitude coordinate.

pickupPhoneNumber
string | null

The phone number to contact at the pickup location in the form: '+15555555555'

pickupFirstName
string | null

First name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.

pickupLastName
string | null

Last name of the person to pickup from. If unknown pass 'Manager'. Limited to 80 characters.

pickupBusinessName
string | null

Pickup business name at the origin.

pickupInstructions
string | null

Any special instructions for pickup.

pickupStoreLocationId
string | null

A unique identifier for store location created in Nash.

pickupExternalStoreLocationId
string | null

The external identifier used for your store.

pickupBarcodes
string[] | null

Array containing barcode values that are required to be scanned at the pickup waypoint.

bookedDeliveryWindow
object | null

The delivery window time slot that the end customer requested this order to be delivered in.

dropoffAddress
string | null

The dropoff address of the order

dropoffPlaceId
string | null

Google place id for the dropoff location.

dropoffAddressNumber
string | null

The number on a house.

dropoffAddressSecondarynumber
string | null

Secondary number on an address e.g. an apartment building.

dropoffAddressFormattedStreet
string | null

The street of the address.

dropoffAddressCity
string | null

The city of the dropoff address.

dropoffAddressCounty
string | null

The county associated with the dropoff address.

dropoffAddressState
string | null

The state of the dropoff address.

dropoffAddressZip
string | null

The zip or postal code of the dropoff address.

dropoffAddressCountry
string | null

The ISO 3166-1 alpha-2 country code of the dropoff address.

dropoffLat
number | null

The dropoff latitude coordinate.

dropoffLng
number | null

The dropoff longitude coordinate.

dropoffPhoneNumber
string | null

The phone number to contact at the dropoff location in the form: '+15555555555'

dropoffFirstName
string | null

First name of the contact at the destination.

dropoffLastName
string | null

Last name of the contact at the destination.

dropoffBusinessName
string | null

Dropoff business name at the destination.

dropoffInstructions
string | null

Any special instructions for dropoff.

dropoffStoreLocationId
string | null

A unique identifier for store location created in Nash.

dropoffBarcodes
string[] | null

Array containing barcode values that are required to be scanned at the dropoff waypoint.

deliveryMode
string | null

The delivery mode of the order

pickupStartTime
string | null

The start time of the pickup window.

pickupEndTime
string | null

The end time of the pickup window.

dropoffStartTime
string | null

The start time of the dropoff window.

dropoffEndTime
string | null

The end time of the dropoff window.

description
string | null

The description of the order

itemsCount
string | null

The number of items in the order

requirements
string[] | null

The requirements of the order

minimumVehicleSize
string | null

The requested minimum vehicle size.

currency
string | null

The currency of the order

valueCents
string | null

The value of the order in cents

tipAmountCents
string | null

The tip amount of the order in cents

width
string | null

The width of the order in cm

depth
string | null

The depth of the order in cm

height
string | null

The height of the order in cm

volume
string | null

The volume of the order in cm^3

weight
string | null

The weight of the order in kg

items
object[] | null

The items of the order

dispatchStrategyId
string | null

The dispatch strategy id of the order

documents
object[] | null

The documents of the order

validationErrors
object | null

The validation errors of the order

quotes
object[] | null

The quotes of the order

failedQuotes
string[] | null

The failed quotes of the order