Create or Update Orders by External Identifier

This endpoint allows you to create and/or update multiple orders by specifying external identifiers. This is useful for batch operations where you need to process multiple orders at once, such as importing orders from an external system or updating multiple orders based on their external IDs.

Create or Update Orders by External Identifier behavior: For each order with an external_id, Nash will check if an order with that external ID already exists. If it exists, the order will be updated; if not, a new order will be created. This ensures efficient batch processing of orders.

Updating archived orders will also unarchive them.

This endpoint is particularly useful for:

Bulk importing orders from external systems
Synchronizing order data between systems
Batch updating multiple orders based on external identifiers

Body

application/json

orders

OrderInput · object[]

required

List of orders to create

Show child attributes

Response

string

required

The id of the order

Example:

"ord_1234567890"

createdAt

string<date-time>

required

The date and time when the order was created

Example:

"2023-08-29T19:17:46.264523"

portalUrl

string

required

The URL of the order in the Nash portal

Example:

"https://portal.dev.usenash.com/orders/ord_1234567890"

publicTrackingUrl

string

required

The URL of the order in the public tracking system

Example:

"https://tracking.dev.usenash.com/ord_1234567890"

status

string

required

The status of the order

Example:

"needs_attention"

tags

string[] | null

required

The tags of the order

Example:

["REST_API"]

externalId

string | null

The external id of the order

Example:

"1234567890"

externalGroupId

string | null

The external group id of the order

Example:

"1234567890"

referenceId

string | null

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

Example:

"1234567890"

orderMetadata

object | null

Key-value data to attach to Nash Jobs.

Example:

{ "key": "value" }

pickupAddress

string | null

The pickup address of the order

Example:

"185 University Ave, Palo Alto, CA 94301"

pickupPlaceId

string | null

Google place id for the pickup location.

Example:

"ChIJd8BlQJq3t4kRUKhH43CQ"

pickupAddressNumber

string | null

The number on a house.

Example:

"185"

pickupAddressSecondarynumber

string | null

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

pickupAddressFormattedStreet

string | null

The street of the address.

Example:

"University Ave"

pickupAddressCity

string | null

The city of the pickup address.

Example:

"Palo Alto"

pickupAddressCounty

string | null

The county associated with the pickup address.

Example:

"Santa Clara"

pickupAddressState

string | null

The state of the pickup address.

Example:

"CA"

pickupAddressZip

string | null

The zip or postal code of the pickup address.

Example:

"94301"

pickupAddressCountry

string | null

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

Example:

"US"

pickupLat

number | null

The pickup latitude coordinate.

Example:

37.422222

pickupLng

number | null

The pickup longitude coordinate.

Example:

-122.139776

pickupPhoneNumber

string | null

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

Example:

"+15555555555"

pickupFirstName

string | null

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

Example:

"Manager"

pickupLastName

string | null

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

Example:

"Manager"

pickupBusinessName

string | null

Pickup business name at the origin.

Example:

"Store ABC"

pickupInstructions

string | null

Any special instructions for pickup.

Example:

"Leave at the front door"

pickupStoreLocationId

string | null

A unique identifier for store location created in Nash.

Example:

"stl_VwpoPJaaqWiPGnXEhWfX"

pickupExternalStoreLocationId

string | null

The external identifier used for your store.

Example:

"0021112"

pickupZoneIds

string[] | null

A list of zone IDs to consider for the Order. The pickup store location will be selected later via selected delivery window.

pickupBarcodes

string[] | null

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

Example:

["1234567890", "0987654321"]

dropoffAddress

string | null

The dropoff address of the order

Example:

"401 San Antonio Rd, Mountain View, CA 94040"

dropoffPlaceId

string | null

Google place id for the dropoff location.

Example:

"ChIJd8BlQJq3t4kRUKhH43CQ"

dropoffAddressNumber

string | null

The number on a house.

Example:

"401"

dropoffAddressSecondarynumber

string | null

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

dropoffAddressFormattedStreet

string | null

The street of the address.

Example:

"San Antonio Rd"

dropoffAddressCity

string | null

The city of the dropoff address.

Example:

"Mountain View"

dropoffAddressCounty

string | null

The county associated with the dropoff address.

Example:

"Santa Clara"

dropoffAddressState

string | null

The state of the dropoff address.

Example:

"CA"

dropoffAddressZip

string | null

The zip or postal code of the dropoff address.

Example:

"94040"

dropoffAddressCountry

string | null

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

Example:

"US"

dropoffLat

number | null

The dropoff latitude coordinate.

Example:

37.422222

dropoffLng

number | null

The dropoff longitude coordinate.

Example:

-122.139776

dropoffPhoneNumber

string | null

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

Example:

"+15555555556"

dropoffFirstName

string | null

First name of the contact at the destination.

Example:

"Quote"

dropoffLastName

string | null

Last name of the contact at the destination.

Example:

"Request"

dropoffBusinessName

string | null

Dropoff business name at the destination.

dropoffInstructions

string | null

Any special instructions for dropoff.

Example:

"Leave at the front door"

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

Example:

"scheduled"

pickupStartTime

string | null

The start time of the pickup window.

Example:

"2024-08-22T23:54:08Z"

pickupEndTime

string | null

The end time of the pickup window.

Example:

"2024-08-22T23:54:08Z"

dropoffStartTime

string | null

The start time of the dropoff window.

Example:

"2024-08-22T23:54:08Z"

dropoffEndTime

string | null

The end time of the dropoff window.

Example:

"2024-08-22T23:54:08Z"

description

string | null

The description of the order

Example:

"Order description"

itemsCount

string | null

The number of items in the order

Example:

"1"

requirements

string[] | null

The requirements of the order

Example:

["photo_proof_of_delivery"]

minimumVehicleSize

enum<string> | null

The requested minimum vehicle size. Allowed values: ['any', 'bike', 'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck', 'pickup', 'van', 'large_van', 'extra_large_van', 'truck']

Available options:

any,

bike,

motorbike,

cargobike,

sedan,

car,

suv,

pickup_truck,

pickup,

van,

large_van,

extra_large_van,

truck

Example:

"car"

currency

string | null

The currency of the order

Example:

"USD"

valueCents

string | null

The value of the order in cents

Example:

"10000"

tipAmountCents

string | null

The tip amount of the order in cents

Example:

"1000"

width

string | null

The width of the order in cm

Example:

"100"

depth

string | null

The depth of the order in cm

Example:

"100"

height

string | null

The height of the order in cm

Example:

"100"

volume

string | null

The volume of the order in cm^3

weight

string | null

The weight of the order in kg

Example:

"100"

items

ItemInput · object[] | null

The items of the order

Show child attributes

dispatchStrategyId

string | null

The dispatch strategy id (or option group id) to be associated with the order. Note: It is the best practice to allow automations to control dispatch strategy and not send the dispatch strategy id in the request.

Example:

"dss_1234567890"

maxDeliveryFeeCents

string | null

The max delivery fee of the order in cents

Example:

"1000"

documents

OrderDocumentOutput · object[] | null

The documents of the order

Show child attributes

Example:

[
  {
    "contentType": "application/pdf",
    "data": "SGVsbG8gd29ybGQ=",
    "id": "doc_1234567890",
    "type": "shipping_label",
    "url": "https://example.com/document.pdf"
  }
]

validationErrors

object | null

The validation errors of the order

Show child attributes

Example:

{ "pickupStartTime": "Time is in the past" }

quotes

QuoteSerializer · object[] | null

The quotes of the order

Show child attributes

Example:

[
  {
    "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"
  }
]

failedQuotes

string[] | null

The failed quotes of the order

Example:

["quote_1234567890", "quote_0987654321"]

API Documentation

Order

Dispatch Strategies

Notifications

Store Locations & Zones

Jobs

Batch Jobs

Providers

Routes

Shifts

Templates

Store Catalog

Miscellaneous

Create or Update Orders by External Identifier

Body

Response