> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create or update order by external identifier
> Create a new order or update an existing one using your external identifier. If an order with the given external identifier exists, it is updated; otherwise a new order is created.
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.
If `quotes_only` is included in the `tags` field, the response will include quotes for the order.
## OpenAPI
````yaml post /v1/order/external-identifier/{externalId}
openapi: 3.1.0
info:
title: Nash API
version: 1.0.0
servers:
- url: https://api.sandbox.usenash.com
description: Sandbox API
- url: https://api.sandbox.ap-southeast-2.usenash.com
description: Sandbox API (Australia)
- url: https://api.usenash.com
description: Production API
- url: https://api.ap-southeast-2.usenash.com
description: Production API (Australia)
security: []
tags:
- name: Notifications
description: Notifications
x-nash-topic: config
- name: Annotate
description: Annotate
x-nash-topic: wismo
- name: Notifications — Send
description: One-off notification send without a NotificationTrigger.
x-nash-topic: notifications
- name: Shipping
description: Shipping operations
x-nash-topic: shipping
- name: Workflow
description: Workflow automation management
x-nash-topic: scheduling
- name: Workflow Execution
description: Workflow execution history and monitoring
x-nash-topic: scheduling
- name: Optimization Strategies
description: Create, read, update, and delete route optimization strategies.
x-nash-topic: scheduling
- name: AI Agents
description: AI agent management — create, read, update, and delete agents
x-nash-topic: config
- name: AI Functions
description: LLM-backed domain tools
x-nash-topic: ai
- name: Webhooks
description: Webhook delivery inspection
x-nash-topic: webhooks
- name: Fleet Simulator
description: Simulate delivery status transitions in dev and sandbox environments.
x-nash-topic: testing
- name: Miscellaneous
description: Miscellaneous
- name: Job
description: Job
x-nash-topic: wismo
- name: Batch Job
description: Batch Job
x-nash-topic: wismo
- name: Order
description: Order
x-nash-topic: wismo
- name: Route
description: Route
x-nash-topic: scheduling
- name: Provider
description: Provider
x-nash-topic: provider
- name: Dispatch Strategies
description: Dispatch Strategies
x-nash-topic: scheduling
- name: Store Locations
description: Store Locations
x-nash-topic: config
- name: Vehicles
description: Vehicles
x-nash-topic: provider
- name: Couriers
description: Couriers
x-nash-topic: provider
- name: Shifts
description: Shifts
x-nash-topic: provider
- name: Delivery Windows
description: Delivery Windows
x-nash-topic: config
- name: Templates
description: Templates
x-nash-topic: config
- name: Zones
description: Zones
x-nash-topic: config
- name: Feedback
description: Feedback
x-nash-topic: reporting
- name: Organizations
description: Organizations
x-nash-topic: config
- name: Store Catalog
description: Store Catalog
x-nash-topic: config
- name: Messaging
description: Messaging
x-nash-topic: config
- name: Contracts
description: Provider contract pricing and version listings
x-nash-topic: provider
- name: Event Timeline
description: Entity-scoped event timeline + outbound provider traffic for one entity.
x-nash-topic: internal
- name: Fleet
description: Inbound endpoints fleets call to update in-flight deliveries.
x-nash-topic: delivery
- name: Route Restrictions
description: Org-scoped geographic areas the route optimizer must avoid traversing.
x-nash-topic: config
- name: Users
description: User, role, and organization-membership management.
x-nash-topic: config
paths:
/v1/order/external-identifier/{externalId}:
post:
tags:
- Order
summary: Create or update order by external identifier
description: >-
Create a new order or update an existing one using your external
identifier. If an order with the given external identifier exists, it is
updated; otherwise a new order is created.
operationId: >-
upsert_order_by_external_id_v1_order_external_identifier__string_externalId__post
parameters:
- name: externalId
in: path
description: The external id of the order to update
required: true
schema:
title: Externalid
type: string
description: The external id of the order to update
example: '1234567890'
example: '1234567890'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInputWithReturnFirstQuoteApiOnly'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderOutputExample'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
components:
schemas:
OrderInputWithReturnFirstQuoteApiOnly:
title: OrderInputWithReturnFirstQuoteApiOnly
type: object
properties:
externalId:
title: Externalid
anyOf:
- type: string
- type: 'null'
description: Order unique identifier from an external system.
default: null
pickupAddress:
title: Pickupaddress
anyOf:
- type: string
- type: 'null'
description: >-
The full address in one line for the pickup location. Format:
[Number] [Street], [second line], [city], [state], [zip code].
default: null
pickupPlaceId:
title: Pickupplaceid
anyOf:
- type: string
- type: 'null'
description: Google place id for the pickup location.
default: null
pickupPhoneNumber:
title: Pickupphonenumber
anyOf:
- type: string
- type: 'null'
description: >-
The phone number to contact at the pickup location in the form:
'+15555555555'
default: null
pickupBusinessName:
title: Pickupbusinessname
anyOf:
- type: string
- type: 'null'
description: Pickup business name at the origin. Limited to 80 characters.
default: null
pickupFirstName:
title: Pickupfirstname
anyOf:
- type: string
- type: 'null'
description: >-
First name of the person to pickup from. If unknown pass 'Manager'.
Limited to 80 characters.
default: null
pickupLastName:
title: Pickuplastname
anyOf:
- type: string
- type: 'null'
description: >-
Last name of the person to pickup from. If unknown pass 'Manager'.
Limited to 80 characters.
default: null
pickupInstructions:
title: Pickupinstructions
anyOf:
- type: string
- type: 'null'
description: Any special instructions for pickup. Limited to 280 characters.
default: null
pickupStoreLocationId:
title: Pickupstorelocationid
anyOf:
- type: string
- type: 'null'
description: A unique identifier for store location created in Nash.
default: null
pickupExternalStoreLocationId:
title: Pickupexternalstorelocationid
anyOf:
- type: string
- type: 'null'
description: The external identifier used for your store.
default: null
pickupStoreLocationIds:
title: Pickupstorelocationids
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
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`.
default: null
pickupZoneIds:
title: Pickupzoneids
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
A list of zone IDs to consider for the Order. The pickup store
location will be selected later via selected delivery window.
default: null
pickupBarcodes:
title: Pickupbarcodes
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
Array containing barcode values that are required to be scanned at
the pickup waypoint.
default: null
pickupEmail:
title: Pickupemail
anyOf:
- type: string
- type: 'null'
description: The email of the contact at the pickup location.
default: null
dropoffAddress:
title: Dropoffaddress
anyOf:
- type: string
- type: 'null'
description: >-
The full address in one line for the dropoff location. Format:
[Number] [Street], [second line], [city], [state], [zip code].
default: null
dropoffPlaceId:
title: Dropoffplaceid
anyOf:
- type: string
- type: 'null'
description: Google place id for the dropoff location.
default: null
dropoffPhoneNumber:
title: Dropoffphonenumber
anyOf:
- type: string
- type: 'null'
description: >-
The phone number to contact at the dropoff location in the form:
'+15555555555'
default: null
dropoffBusinessName:
title: Dropoffbusinessname
anyOf:
- type: string
- type: 'null'
description: >-
Name of the business at the destination. Should be left empty if
there is no business. Limited to 80 characters.
default: null
dropoffFirstName:
title: Dropofffirstname
anyOf:
- type: string
- type: 'null'
description: >-
First name of the contact at the destination. Limited to 80
characters.
default: null
dropoffLastName:
title: Dropofflastname
anyOf:
- type: string
- type: 'null'
description: >-
Last name of the contact at the destination. Limited to 80
characters.
default: null
dropoffInstructions:
title: Dropoffinstructions
anyOf:
- type: string
- type: 'null'
description: Any special instructions for dropoff. Limited to 280 characters.
default: null
dropoffBarcodes:
title: Dropoffbarcodes
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
Array containing barcode values/types that are required to be
scanned at the dropoff waypoint.
default: null
dropoffEmail:
title: Dropoffemail
anyOf:
- type: string
- type: 'null'
description: The email of the contact at the dropoff location.
default: null
deliveryMode:
title: Deliverymode
anyOf:
- type: string
- type: 'null'
description: '''now'' or ''scheduled'' when the delivery should be scheduled'
default: null
pickupStartTime:
title: Pickupstarttime
anyOf:
- type: string
format: date-time
- type: 'null'
description: The earliest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
default: null
pickupEndTime:
title: Pickupendtime
anyOf:
- type: string
format: date-time
- type: 'null'
description: The latest pickup time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
default: null
dropoffStartTime:
title: Dropoffstarttime
anyOf:
- type: string
format: date-time
- type: 'null'
description: The earliest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
default: null
dropoffEndTime:
title: Dropoffendtime
anyOf:
- type: string
format: date-time
- type: 'null'
description: The latest dropoff time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'
default: null
deliveryWindowId:
title: Deliverywindowid
anyOf:
- type: string
- type: 'null'
description: Delivery window id if using Nash delivery windows
default: null
description:
title: Description
anyOf:
- type: string
- type: 'null'
description: Order description and notes. Limited to 280 characters.
default: null
itemsCount:
title: Itemscount
anyOf:
- type: integer
- type: 'null'
description: The number of items in this order
default: null
currency:
title: Currency
anyOf:
- type: string
- type: 'null'
description: Local currency
default: null
valueCents:
title: Valuecents
anyOf:
- type: integer
- type: string
- type: 'null'
description: Order value in cents
default: null
tipAmountCents:
title: Tipamountcents
anyOf:
- type: integer
- type: 'null'
description: Tip paid to the driver in cents
default: null
requirements:
title: Requirements
anyOf:
- type: array
items:
$ref: '#/components/schemas/PackageRequirements'
- type: array
items:
type: string
- type: 'null'
description: Package requirements.
default: null
example:
- photo_proof_of_delivery
- age_verification_on_delivery
minimumVehicleSize:
title: Minimumvehiclesize
enum:
- any
- bike
- motorbike
- cargobike
- sedan
- car
- suv
- pickup_truck
- pickup
- van
- large_van
- extra_large_van
- truck
anyOf:
- type: string
- type: 'null'
description: >-
The requested minimum vehicle size. Allowed values: ['any', 'bike',
'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck',
'pickup', 'van', 'large_van', 'extra_large_van', 'truck']
default: null
example: car
dispatchStrategyId:
title: Dispatchstrategyid
anyOf:
- type: string
- type: 'null'
description: >-
The dispatch strategy id (or option group id) to be associated with
the order.
Note: Best practice is to allow automations to control dispatch strategy and not send the dispatch strategy id in the request.
default: null
orderMetadata:
title: Ordermetadata
anyOf:
- type: object
additionalProperties: true
- type: 'null'
description: Key-value data to attach to this order.
default: null
tags:
title: Tags
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Optional order tags, they will be included in every response
default: null
referenceId:
title: Referenceid
anyOf:
- type: string
- type: 'null'
description: >-
A non-unique identifier for orders, visible to the courier if
supported by the provider.
default: null
pickupAddressNumber:
title: Pickupaddressnumber
anyOf:
- type: string
- type: 'null'
description: The number on a house.
default: null
pickupAddressSecondarynumber:
title: Pickupaddresssecondarynumber
anyOf:
- type: string
- type: 'null'
description: Secondary number on an address e.g. an apartment building.
default: null
pickupAddressFormattedStreet:
title: Pickupaddressformattedstreet
anyOf:
- type: string
- type: 'null'
description: The street of the address.
default: null
pickupAddressCity:
title: Pickupaddresscity
anyOf:
- type: string
- type: 'null'
description: The city of the pickup address.
default: null
pickupAddressCounty:
title: Pickupaddresscounty
anyOf:
- type: string
- type: 'null'
description: The county associated with the pickup address.
default: null
pickupAddressState:
title: Pickupaddressstate
anyOf:
- type: string
- type: 'null'
description: The state of the pickup address.
default: null
pickupAddressZip:
title: Pickupaddresszip
anyOf:
- type: string
- type: 'null'
description: The zip or postal code of the pickup address.
default: null
pickupAddressCountry:
title: Pickupaddresscountry
anyOf:
- type: string
- type: 'null'
description: The ISO 3166-1 alpha-2 country code of the pickup address.
default: null
pickupLat:
title: Pickuplat
anyOf:
- type: number
- type: 'null'
description: The pickup latitude coordinate.
default: null
pickupLng:
title: Pickuplng
anyOf:
- type: number
- type: 'null'
description: The pickup longitude coordinate.
default: null
dropoffAddressNumber:
title: Dropoffaddressnumber
anyOf:
- type: string
- type: 'null'
description: The number on a house.
default: null
dropoffAddressSecondarynumber:
title: Dropoffaddresssecondarynumber
anyOf:
- type: string
- type: 'null'
description: Secondary number on an address e.g. an apartment building.
default: null
dropoffAddressFormattedStreet:
title: Dropoffaddressformattedstreet
anyOf:
- type: string
- type: 'null'
description: The street of the address.
default: null
dropoffAddressCity:
title: Dropoffaddresscity
anyOf:
- type: string
- type: 'null'
description: The city of the dropoff address.
default: null
dropoffAddressCounty:
title: Dropoffaddresscounty
anyOf:
- type: string
- type: 'null'
description: The county associated with the dropoff address.
default: null
dropoffAddressState:
title: Dropoffaddressstate
anyOf:
- type: string
- type: 'null'
description: The state of the dropoff address.
default: null
dropoffAddressZip:
title: Dropoffaddresszip
anyOf:
- type: string
- type: 'null'
description: The zip or postal code of the dropoff address.
default: null
dropoffAddressCountry:
title: Dropoffaddresscountry
anyOf:
- type: string
- type: 'null'
description: The ISO 3166-1 alpha-2 country code of the dropoff address.
default: null
dropoffLat:
title: Dropofflat
anyOf:
- type: number
- type: 'null'
description: The dropoff latitude coordinate.
default: null
dropoffLng:
title: Dropofflng
anyOf:
- type: number
- type: 'null'
description: The dropoff longitude coordinate.
default: null
weight:
title: Weight
anyOf:
- type: number
- type: integer
- type: string
- type: 'null'
description: The total weight of the package in kilograms (kg)
default: null
height:
title: Height
anyOf:
- type: number
- type: integer
- type: 'null'
description: The total height of the package in centimeters (cm)
default: null
width:
title: Width
anyOf:
- type: number
- type: integer
- type: 'null'
description: The total width of the package in centimeters (cm)
default: null
depth:
title: Depth
anyOf:
- type: number
- type: integer
- type: 'null'
description: The total depth of the package in centimeters (cm)
default: null
items:
title: Items
anyOf:
- type: array
items:
$ref: '#/components/schemas/ItemInput'
- type: 'null'
description: Lists of items in the delivery
default: null
optimizationParameters:
anyOf:
- $ref: '#/components/schemas/OptimizationParameters'
- type: 'null'
description: Order-level optimization parameters
default: null
pickupPayment:
anyOf:
- $ref: '#/components/schemas/PickupPayment'
- type: 'null'
description: >-
How the courier should pay for the order at pickup (e.g. a barcode
or provider card).
default: null
reapplyAutomations:
title: Reapplyautomations
anyOf:
- type: boolean
- type: 'null'
description: If set to true, the order will be re-evaluated with automations.
default: null
maxDeliveryFeeCents:
title: Maxdeliveryfeecents
anyOf:
- type: integer
- type: 'null'
description: >-
The maximum delivery fee for the order in cents. This will override
the dispatch strategy max delivery fee if both are set.
default: null
returnFirstQuoteApiOnly:
title: Returnfirstquoteapionly
anyOf:
- type: boolean
- type: 'null'
description: >-
If set to true, order quotes will only include the first available
API quote
default: null
OrderOutputExample:
title: OrderOutputExample
required:
- id
- createdAt
- portalUrl
- publicTrackingUrl
- status
- tags
type: object
properties:
id:
title: Id
type: string
description: The id of the order
example: ord_1234567890
createdAt:
title: Createdat
type: string
description: The date and time when the order was created
format: date-time
example: '2023-08-29T19:17:46.264523'
externalId:
title: Externalid
anyOf:
- type: string
- type: 'null'
description: The external id of the order
default: null
example: '1234567890'
externalGroupId:
title: Externalgroupid
anyOf:
- type: string
- type: 'null'
description: The external group id of the order
default: null
example: '1234567890'
referenceId:
title: Referenceid
anyOf:
- type: string
- type: 'null'
description: >-
A non-unique identifier for orders, visible to the courier if
supported by the provider.
default: null
example: '1234567890'
portalUrl:
title: Portalurl
type: string
description: The URL of the order in the Nash portal
example: https://portal.dev.usenash.com/orders/ord_1234567890
publicTrackingUrl:
title: Publictrackingurl
type: string
description: The URL of the order in the public tracking system
example: https://tracking.dev.usenash.com/ord_1234567890
status:
title: Status
type: string
description: The status of the order
example: needs_attention
tags:
title: Tags
anyOf:
- type: array
items:
type: string
- type: 'null'
description: The tags of the order
example:
- REST_API
orderMetadata:
title: Ordermetadata
anyOf:
- type: object
additionalProperties: true
- type: 'null'
description: Key-value data to attach to Nash Jobs.
default: null
example:
key: value
pickupAddress:
title: Pickupaddress
anyOf:
- type: string
- type: 'null'
description: The pickup address of the order
default: null
example: 185 University Ave, Palo Alto, CA 94301
pickupPlaceId:
title: Pickupplaceid
anyOf:
- type: string
- type: 'null'
description: Google place id for the pickup location.
default: null
example: ChIJd8BlQJq3t4kRUKhH43CQ
pickupAddressNumber:
title: Pickupaddressnumber
anyOf:
- type: string
- type: 'null'
description: The number on a house.
default: null
example: '185'
pickupAddressSecondarynumber:
title: Pickupaddresssecondarynumber
anyOf:
- type: string
- type: 'null'
description: Secondary number on an address e.g. an apartment building.
default: null
pickupAddressFormattedStreet:
title: Pickupaddressformattedstreet
anyOf:
- type: string
- type: 'null'
description: The street of the address.
default: null
example: University Ave
pickupAddressCity:
title: Pickupaddresscity
anyOf:
- type: string
- type: 'null'
description: The city of the pickup address.
default: null
example: Palo Alto
pickupAddressCounty:
title: Pickupaddresscounty
anyOf:
- type: string
- type: 'null'
description: The county associated with the pickup address.
default: null
example: Santa Clara
pickupAddressState:
title: Pickupaddressstate
anyOf:
- type: string
- type: 'null'
description: The state of the pickup address.
default: null
example: CA
pickupAddressZip:
title: Pickupaddresszip
anyOf:
- type: string
- type: 'null'
description: The zip or postal code of the pickup address.
default: null
example: '94301'
pickupAddressCountry:
title: Pickupaddresscountry
anyOf:
- type: string
- type: 'null'
description: The ISO 3166-1 alpha-2 country code of the pickup address.
default: null
example: US
pickupLat:
title: Pickuplat
anyOf:
- type: number
- type: 'null'
description: The pickup latitude coordinate.
default: null
example: 37.422222
pickupLng:
title: Pickuplng
anyOf:
- type: number
- type: 'null'
description: The pickup longitude coordinate.
default: null
example: -122.139776
pickupPhoneNumber:
title: Pickupphonenumber
anyOf:
- type: string
- type: 'null'
description: >-
The phone number to contact at the pickup location in the form:
'+15555555555'
default: null
example: '+15555555555'
pickupFirstName:
title: Pickupfirstname
anyOf:
- type: string
- type: 'null'
description: >-
First name of the person to pickup from. If unknown pass 'Manager'.
Limited to 80 characters.
default: null
example: Manager
pickupLastName:
title: Pickuplastname
anyOf:
- type: string
- type: 'null'
description: >-
Last name of the person to pickup from. If unknown pass 'Manager'.
Limited to 80 characters.
default: null
example: Manager
pickupBusinessName:
title: Pickupbusinessname
anyOf:
- type: string
- type: 'null'
description: Pickup business name at the origin.
default: null
example: Store ABC
pickupInstructions:
title: Pickupinstructions
anyOf:
- type: string
- type: 'null'
description: Any special instructions for pickup.
default: null
example: Leave at the front door
pickupStoreLocationId:
title: Pickupstorelocationid
anyOf:
- type: string
- type: 'null'
description: A unique identifier for store location created in Nash.
default: null
example: stl_VwpoPJaaqWiPGnXEhWfX
pickupExternalStoreLocationId:
title: Pickupexternalstorelocationid
anyOf:
- type: string
- type: 'null'
description: The external identifier used for your store.
default: null
example: '0021112'
pickupZoneIds:
title: Pickupzoneids
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
A list of zone IDs to consider for the Order. The pickup store
location will be selected later via selected delivery window.
default: null
pickupBarcodes:
title: Pickupbarcodes
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
Array containing barcode values that are required to be scanned at
the pickup waypoint.
default: null
example:
- '1234567890'
- '0987654321'
pickupPayment:
anyOf:
- $ref: '#/components/schemas/PickupPayment'
- type: 'null'
description: >-
How the courier should pay for the order at pickup (e.g. a barcode
or provider card).
default: null
example:
barcode:
type: CODE128
value: '1234567890'
providerCard: false
dropoffAddress:
title: Dropoffaddress
anyOf:
- type: string
- type: 'null'
description: The dropoff address of the order
default: null
example: 401 San Antonio Rd, Mountain View, CA 94040
dropoffPlaceId:
title: Dropoffplaceid
anyOf:
- type: string
- type: 'null'
description: Google place id for the dropoff location.
default: null
example: ChIJd8BlQJq3t4kRUKhH43CQ
dropoffAddressNumber:
title: Dropoffaddressnumber
anyOf:
- type: string
- type: 'null'
description: The number on a house.
default: null
example: '401'
dropoffAddressSecondarynumber:
title: Dropoffaddresssecondarynumber
anyOf:
- type: string
- type: 'null'
description: Secondary number on an address e.g. an apartment building.
default: null
dropoffAddressFormattedStreet:
title: Dropoffaddressformattedstreet
anyOf:
- type: string
- type: 'null'
description: The street of the address.
default: null
example: San Antonio Rd
dropoffAddressCity:
title: Dropoffaddresscity
anyOf:
- type: string
- type: 'null'
description: The city of the dropoff address.
default: null
example: Mountain View
dropoffAddressCounty:
title: Dropoffaddresscounty
anyOf:
- type: string
- type: 'null'
description: The county associated with the dropoff address.
default: null
example: Santa Clara
dropoffAddressState:
title: Dropoffaddressstate
anyOf:
- type: string
- type: 'null'
description: The state of the dropoff address.
default: null
example: CA
dropoffAddressZip:
title: Dropoffaddresszip
anyOf:
- type: string
- type: 'null'
description: The zip or postal code of the dropoff address.
default: null
example: '94040'
dropoffAddressCountry:
title: Dropoffaddresscountry
anyOf:
- type: string
- type: 'null'
description: The ISO 3166-1 alpha-2 country code of the dropoff address.
default: null
example: US
dropoffLat:
title: Dropofflat
anyOf:
- type: number
- type: 'null'
description: The dropoff latitude coordinate.
default: null
example: 37.422222
dropoffLng:
title: Dropofflng
anyOf:
- type: number
- type: 'null'
description: The dropoff longitude coordinate.
default: null
example: -122.139776
dropoffPhoneNumber:
title: Dropoffphonenumber
anyOf:
- type: string
- type: 'null'
description: >-
The phone number to contact at the dropoff location in the form:
'+15555555555'
default: null
example: '+15555555556'
dropoffFirstName:
title: Dropofffirstname
anyOf:
- type: string
- type: 'null'
description: First name of the contact at the destination.
default: null
example: Quote
dropoffLastName:
title: Dropofflastname
anyOf:
- type: string
- type: 'null'
description: Last name of the contact at the destination.
default: null
example: Request
dropoffBusinessName:
title: Dropoffbusinessname
anyOf:
- type: string
- type: 'null'
description: Dropoff business name at the destination.
default: null
dropoffInstructions:
title: Dropoffinstructions
anyOf:
- type: string
- type: 'null'
description: Any special instructions for dropoff.
default: null
example: Leave at the front door
dropoffStoreLocationId:
title: Dropoffstorelocationid
anyOf:
- type: string
- type: 'null'
description: A unique identifier for store location created in Nash.
default: null
dropoffBarcodes:
title: Dropoffbarcodes
anyOf:
- type: array
items:
type: string
- type: 'null'
description: >-
Array containing barcode values that are required to be scanned at
the dropoff waypoint.
default: null
deliveryMode:
title: Deliverymode
anyOf:
- type: string
- type: 'null'
description: The delivery mode of the order
default: null
example: scheduled
pickupStartTime:
title: Pickupstarttime
anyOf:
- type: string
- type: 'null'
description: The start time of the pickup window.
default: null
example: '2024-08-22T23:54:08Z'
pickupEndTime:
title: Pickupendtime
anyOf:
- type: string
- type: 'null'
description: The end time of the pickup window.
default: null
example: '2024-08-22T23:54:08Z'
dropoffStartTime:
title: Dropoffstarttime
anyOf:
- type: string
- type: 'null'
description: The start time of the dropoff window.
default: null
example: '2024-08-22T23:54:08Z'
dropoffEndTime:
title: Dropoffendtime
anyOf:
- type: string
- type: 'null'
description: The end time of the dropoff window.
default: null
example: '2024-08-22T23:54:08Z'
description:
title: Description
anyOf:
- type: string
- type: 'null'
description: The description of the order
default: null
example: Order description
itemsCount:
title: Itemscount
anyOf:
- type: string
- type: 'null'
description: The number of items in the order
default: null
example: '1'
requirements:
title: Requirements
anyOf:
- type: array
items:
type: string
- type: 'null'
description: The requirements of the order
default: null
example:
- photo_proof_of_delivery
minimumVehicleSize:
title: Minimumvehiclesize
enum:
- any
- bike
- motorbike
- cargobike
- sedan
- car
- suv
- pickup_truck
- pickup
- van
- large_van
- extra_large_van
- truck
anyOf:
- type: string
- type: 'null'
description: >-
The requested minimum vehicle size. Allowed values: ['any', 'bike',
'motorbike', 'cargobike', 'sedan', 'car', 'suv', 'pickup_truck',
'pickup', 'van', 'large_van', 'extra_large_van', 'truck']
default: null
example: car
currency:
title: Currency
anyOf:
- type: string
- type: 'null'
description: The currency of the order
default: null
example: USD
valueCents:
title: Valuecents
anyOf:
- type: string
- type: 'null'
description: The value of the order in cents
default: null
example: '10000'
tipAmountCents:
title: Tipamountcents
anyOf:
- type: string
- type: 'null'
description: The tip amount of the order in cents
default: null
example: '1000'
width:
title: Width
anyOf:
- type: string
- type: 'null'
description: The width of the order in cm
default: null
example: '100'
depth:
title: Depth
anyOf:
- type: string
- type: 'null'
description: The depth of the order in cm
default: null
example: '100'
height:
title: Height
anyOf:
- type: string
- type: 'null'
description: The height of the order in cm
default: null
example: '100'
volume:
title: Volume
anyOf:
- type: string
- type: 'null'
description: The volume of the order in cm^3
default: null
weight:
title: Weight
anyOf:
- type: string
- type: 'null'
description: The weight of the order in kg
default: null
example: '100'
items:
title: Items
anyOf:
- type: array
items:
$ref: '#/components/schemas/ItemInput'
- type: 'null'
description: The items of the order
default: null
dispatchStrategyId:
title: Dispatchstrategyid
anyOf:
- type: string
- type: 'null'
description: >-
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.
default: null
example: dss_1234567890
maxDeliveryFeeCents:
title: Maxdeliveryfeecents
anyOf:
- type: string
- type: 'null'
description: The max delivery fee of the order in cents
default: null
example: '1000'
documents:
title: Documents
anyOf:
- type: array
items:
$ref: '#/components/schemas/OrderDocumentOutput'
- type: 'null'
description: The documents of the order
default: null
example:
- contentType: application/pdf
data: SGVsbG8gd29ybGQ=
id: doc_1234567890
type: shipping_label
url: https://example.com/document.pdf
validationErrors:
title: Validationerrors
anyOf:
- type: object
additionalProperties:
type: string
- type: 'null'
description: The validation errors of the order
default: null
example:
pickupStartTime: Time is in the past
quotes:
title: Quotes
anyOf:
- type: array
items:
$ref: '#/components/schemas/QuoteSerializer'
- type: 'null'
description: The quotes of the order
default: null
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:
title: Failedquotes
anyOf:
- type: array
items:
type: string
- type: 'null'
description: The failed quotes of the order
default: null
example:
- quote_1234567890
- quote_0987654321
NashValidationError:
title: NashValidationError
required:
- error
- response_status
- RequestID
type: object
properties:
error:
$ref: '#/components/schemas/NashErrorDetails'
response_status:
title: Response Status
type: string
RequestID:
title: Requestid
type: string
PackageRequirements:
title: PackageRequirements
enum:
- photo_proof_of_delivery
- signature_proof_of_delivery
- photo_proof_of_pickup
- photo_reference_on_dropoff
- photo_reference_capture_on_dropoff
- signature_proof_of_pickup
- photo_pre_delivery_verification
- age_verification_on_delivery
- id_verification_on_delivery
- barcode_scan_on_pickup
- barcode_scan_on_dropoff
- barcode_scan_on_return
- meet_on_delivery
- shipping_label
- two_person_team
- pincode_verification
- schedule_ii_controlled_substances
- alcohol
- tobacco
- vapes
- parking_check_in
- display_barcode_on_pickup
- pick_and_pack
type: string
description: >-
Detailed description:
https://docs.usenash.com/reference/package-requirements.
ItemInput:
title: ItemInput
type: object
properties:
id:
title: Id
anyOf:
- type: string
- type: 'null'
description: The merchant ID of the item
default: null
example: abc-123
description:
title: Description
anyOf:
- type: string
- type: 'null'
description: The description of the item
default: null
example: A box of books
count:
title: Count
type: integer
description: The quantity of the item
default: 1
example: 2
dimensions:
anyOf:
- $ref: '#/components/schemas/Dimensions'
- type: 'null'
description: The dimensions of the item
default: null
example:
depth: 14
height: 10
width: 12
weight:
title: Weight
anyOf:
- type: number
- type: integer
- type: 'null'
description: The weight of the item in kilograms (kg)
default: null
example: 1.5
valueCents:
title: Valuecents
anyOf:
- type: integer
- type: 'null'
description: The value of the item in cents
default: null
example: 1000
requirements:
title: Requirements
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of requirements for this item
default: null
example:
- age_verification_on_delivery
category:
title: Category
anyOf:
- type: string
- type: 'null'
description: The category of the item
default: null
barcode:
title: Barcode
anyOf:
- type: string
- type: 'null'
description: Barcode value for this item.
default: null
example: 0199312650999998913643M221872801002010908
metadata:
title: Metadata
anyOf:
- type: object
additionalProperties: true
- type: 'null'
description: Key-value data to attach to this item.
default: null
example:
packaging_type: CTN
subItems:
title: Subitems
anyOf:
- type: array
items:
$ref: '#/components/schemas/SubItemInput'
- type: 'null'
description: The nested sub-items
default: null
description: Item input object for API requests.
OptimizationParameters:
title: OptimizationParameters
type: object
properties:
pickupDoorstepTimeSeconds:
title: Pickupdoorsteptimeseconds
anyOf:
- type: integer
- type: 'null'
description: >-
Length of time (in seconds) it take the courier at the pickup
location's doorstep.
default: null
example: 90
dropoffDoorstepTimeSeconds:
title: Dropoffdoorsteptimeseconds
anyOf:
- type: integer
- type: 'null'
description: >-
Length of time (in seconds) it take the courier at the dropoff
location's doorstep.
default: null
example: 180
costsByMetric:
title: Costsbymetric
anyOf:
- type: object
additionalProperties: true
- type: 'null'
description: The cost metric to use for the order
default: null
example:
distance: 10
weight: 200
clusterLabel:
title: Clusterlabel
anyOf:
- type: string
- type: 'null'
description: The cluster label for the order
default: null
mxLabel:
title: Mxlabel
anyOf:
- type: string
- type: 'null'
description: The mutually exclusive label for the order
default: null
assignmentPriority:
title: Assignmentpriority
anyOf:
- maximum: 3
minimum: 0
type: integer
- type: 'null'
description: The assignment priority for the order
default: null
sequencePriority:
title: Sequencepriority
anyOf:
- maximum: 499
minimum: 0
type: integer
- type: 'null'
description: The sequence priority for the order
default: null
sequenceGroup:
title: Sequencegroup
anyOf:
- type: string
- type: 'null'
description: The sequence group for the order
default: null
PickupPayment:
title: PickupPayment
type: object
properties:
barcode:
anyOf:
- $ref: '#/components/schemas/PickupPaymentBarcode'
- type: 'null'
description: >-
Barcode the courier presents at the pickup location to pay for the
order.
default: null
providerCard:
title: Providercard
anyOf:
- type: boolean
- type: 'null'
description: >-
If true, the courier pays for the order at pickup using a
provider-issued card.
default: null
example: true
OrderDocumentOutput:
title: OrderDocumentOutput
required:
- createdAt
- id
- type
- contentType
type: object
properties:
createdAt:
title: Createdat
type: string
description: The date and time when the document was created
format: date-time
example: '2023-08-29T19:17:46.264523'
id:
title: Id
type: string
description: The id of the document
example: doc_1234567890
type:
$ref: '#/components/schemas/DocumentType'
description: The type of the document
example: shipping_label
contentType:
title: Contenttype
type: string
description: The content type of the document
example: application/pdf
url:
title: Url
anyOf:
- type: string
- type: 'null'
description: The URL of the document
default: null
example: https://example.com/document.pdf
data:
title: Data
anyOf:
- type: string
- type: 'null'
description: The data of the document
default: null
example: SGVsbG8gd29ybG=
description: Document object returned by the API.
QuoteSerializer:
title: QuoteSerializer
required:
- id
- providerId
- providerName
- createdTime
- priceCents
type: object
properties:
id:
title: Id
type: string
description: Quote ID
example: qot_01234567890
type:
title: Type
anyOf:
- type: string
- type: 'null'
description: Quote type
default: null
providerId:
title: Providerid
type: string
description: Provider ID
example: uber_standard_mini_mart
providerName:
title: Providername
type: string
description: Provider name
example: Nash
providerLogo:
title: Providerlogo
anyOf:
- type: string
- type: 'null'
description: Provider logo
default: null
example: https://nash.com/logo.png
providerIsInternal:
title: Providerisinternal
anyOf:
- type: boolean
- type: 'null'
description: Is the provider internal
default: null
createdTime:
title: Createdtime
type: string
description: Created time
example: '2021-01-01T00:00:00Z'
expireTime:
title: Expiretime
anyOf:
- type: string
- type: 'null'
description: Expire time
default: null
example: '2021-01-01T00:00:00Z'
priceCents:
title: Pricecents
type: integer
description: Price in cents
example: 1000
taxAmountCents:
title: Taxamountcents
anyOf:
- type: integer
- type: 'null'
description: Tax amount in cents
default: null
example: 100
tollFeeCents:
title: Tollfeecents
anyOf:
- type: integer
- type: 'null'
description: Toll fee in cents
default: null
example: 100
nashFeeCents:
title: Nashfeecents
anyOf:
- type: integer
- type: 'null'
description: Nash fee in cents
default: null
example: 100
insuranceFeeCents:
title: Insurancefeecents
anyOf:
- type: integer
- type: 'null'
description: Insurance fee in cents
default: null
example: 100
currency:
title: Currency
anyOf:
- type: string
- type: 'null'
description: Currency
default: null
example: USD
pickupWindow:
title: Pickupwindow
anyOf:
- type: string
- type: 'null'
description: Pickup window
default: null
example: '2021-01-01T00:00:00Z'
dropoffEta:
title: Dropoffeta
anyOf:
- type: string
- type: 'null'
description: Dropoff ETA
default: null
example: '2021-01-01T00:00:00Z'
tags:
title: Tags
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Tags
default: null
example:
- tag1
- tag2
- autodispatch_preferred_quote
costSplitCustomerCents:
title: Costsplitcustomercents
anyOf:
- type: integer
- type: 'null'
description: Cost split customer in cents
default: null
example: 100
costSplitBusinessCents:
title: Costsplitbusinesscents
anyOf:
- type: integer
- type: 'null'
description: Cost split business in cents
default: null
example: 100
totalPriceBreakdown:
title: Totalpricebreakdown
anyOf:
- type: object
additionalProperties: true
- type: 'null'
description: Total price breakdown
default: null
example:
subtotal: 1000
tax: 100
total: 1100
totalPriceCents:
title: Totalpricecents
anyOf:
- type: integer
- type: 'null'
description: Total price in cents
default: null
example: 1000
rank:
title: Rank
anyOf:
- type: integer
- type: 'null'
description: Quote rank for preferred provider ordering
default: null
example: 1
price:
title: Price
anyOf:
- type: number
- type: 'null'
description: Price
default: null
example: 1000
isSuccessful:
title: Issuccessful
anyOf:
- type: boolean
- type: 'null'
description: Is successful
default: null
example: true
errorMessage:
title: Errormessage
anyOf:
- type: string
- type: 'null'
description: Error message
default: null
example: Error message
description: Generic serializer for quotes used in many endpoints.
NashErrorDetails:
title: NashErrorDetails
required:
- code
- message
type: object
properties:
code:
title: Code
type: string
message:
title: Message
type: string
details:
title: Details
anyOf:
- type: object
additionalProperties: true
- type: 'null'
default: null
Dimensions:
title: Dimensions
type: object
properties:
height:
title: Height
anyOf:
- type: number
- type: integer
- type: 'null'
description: The height of the item in centimeters (cm)
default: null
example: 10
width:
title: Width
anyOf:
- type: number
- type: integer
- type: 'null'
description: The width of the item in centimeters (cm)
default: null
example: 12
depth:
title: Depth
anyOf:
- type: number
- type: integer
- type: 'null'
description: The depth of the item in centimeters (cm)
default: null
example: 14
SubItemInput:
title: SubItemInput
type: object
properties:
id:
title: Id
anyOf:
- type: string
- type: 'null'
description: The merchant ID of the item
default: null
example: abc-123
description:
title: Description
anyOf:
- type: string
- type: 'null'
description: The description of the item
default: null
example: A box of books
count:
title: Count
type: integer
description: The quantity of the item
default: 1
example: 2
dimensions:
anyOf:
- $ref: '#/components/schemas/Dimensions'
- type: 'null'
description: The dimensions of the item
default: null
example:
depth: 14
height: 10
width: 12
weight:
title: Weight
anyOf:
- type: number
- type: integer
- type: 'null'
description: The weight of the item in kilograms (kg)
default: null
example: 1.5
valueCents:
title: Valuecents
anyOf:
- type: integer
- type: 'null'
description: The value of the item in cents
default: null
example: 1000
requirements:
title: Requirements
anyOf:
- type: array
items:
type: string
- type: 'null'
description: List of requirements for this item
default: null
example:
- age_verification_on_delivery
category:
title: Category
anyOf:
- type: string
- type: 'null'
description: The category of the item
default: null
barcode:
title: Barcode
anyOf:
- type: string
- type: 'null'
description: Barcode value for this item.
default: null
example: 0199312650999998913643M221872801002010908
metadata:
title: Metadata
anyOf:
- type: object
additionalProperties: true
- type: 'null'
description: Key-value data to attach to this item.
default: null
example:
packaging_type: CTN
sku:
title: Sku
anyOf:
- type: string
- type: 'null'
description: The SKU of the sub-item
default: null
substitution:
anyOf:
- $ref: '#/components/schemas/SubstitutionObject'
- type: 'null'
description: Substitution preferences for the sub-item
default: null
subItems:
title: Subitems
anyOf:
- type: array
items:
$ref: '#/components/schemas/SubItemInput'
- type: 'null'
description: The nested sub-items
default: null
description: Sub-item input object for API requests.
PickupPaymentBarcode:
title: PickupPaymentBarcode
type: object
properties:
type:
title: Type
anyOf:
- type: string
- type: 'null'
description: The barcode symbology (e.g. CODE128, QR).
default: null
example: CODE128
value:
title: Value
anyOf:
- type: string
- type: 'null'
description: The barcode value the courier should present at pickup.
default: null
example: '1234567890'
DocumentType:
title: DocumentType
enum:
- shipping_label
- pickup_label
- manifest
- packing_slip_label
- proof_of_delivery
type: string
SubstitutionObject:
title: SubstitutionObject
type: object
properties:
preference:
title: Preference
anyOf:
- type: string
- type: 'null'
description: 'Substitution preference: refund or substitute'
default: null
source:
title: Source
anyOf:
- type: string
- type: 'null'
description: Source of substitution, e.g., merchant, customer
default: null
substituteItems:
title: Substituteitems
anyOf:
- type: array
items:
$ref: '#/components/schemas/SubstituteItemObject'
- type: 'null'
description: List of substitute items
default: null
SubstituteItemObject:
title: SubstituteItemObject
type: object
properties:
id:
title: Id
anyOf:
- type: string
- type: 'null'
description: The ID of the substitute item
default: null
sku:
title: Sku
anyOf:
- type: string
- type: 'null'
description: The SKU of the substitute item
default: null
quantity:
title: Quantity
anyOf:
- type: integer
- type: 'null'
description: The quantity of the substitute item
default: null
````