openapi: 3.1.0
info:
title: Nash AI Functions Order API
version: 1.0.0
description: LLM-backed domain tools
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)
tags:
- name: Order
description: Order
x-nash-topic: wismo
paths:
/v1/order:
post:
tags:
- Order
summary: Create Order
description: Create a pre-dispatch order with pickup and dropoff details. Orders are flexible data structures that become packages when dispatched to a provider.
operationId: create_order_v1_order_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInput'
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'
/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'
/v1/order/external-identifier/{externalId}/autodispatch:
post:
tags:
- Order
summary: Autodispatch order by external identifier
description: Dispatch an order using your external identifier and the organization's dispatch strategy. Creates a job, requests quotes, and automatically selects the best quote.
operationId: autodispatch_order_by_external_id_v1_order_external_identifier__string_externalId__autodispatch_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'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/order/external-identifier/{externalId}/delivery-window:
post:
tags:
- Order
summary: Upsert order by external identifier with delivery window
description: Create or update an order by external identifier and associate it with a delivery window. The order is linked to the specified delivery window for scheduled delivery.
operationId: upsert_order_with_delivery_window_v1_order_external_identifier__string_externalId__delivery_window_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/OrderWithDeliveryWindowInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderWithDeliveryWindowOutputExample'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/order/get_quotes:
post:
tags:
- Order
summary: Get order quotes
description: Request delivery price quotes from available providers for an order. Returns the order with attached quotes that can be selected to dispatch.
operationId: get_order_quotes_v1_order_get_quotes_post
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'
/v1/order/refresh_quotes:
post:
tags:
- Order
summary: Refresh order quotes
description: Request fresh price quotes from delivery providers for an existing order. Replaces any existing quotes with updated pricing from available providers.
operationId: refresh_order_quotes_v1_order_refresh_quotes_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshOrderQuotesInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshOrderQuotesOutputExample'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/order/{id}:
get:
tags:
- Order
summary: Get order
description: Retrieve a single order by ID, including its pickup/dropoff details, status, and metadata.
operationId: get_order_v1_order__string_id__get
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
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'
delete:
tags:
- Order
summary: Archive order
description: Archive (soft-delete) an order. Archived orders are hidden from default listings but can be restored using the unarchive endpoint.
operationId: archive_order_v1_order__string_id__delete
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
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'
patch:
tags:
- Order
summary: Update order
description: Update an existing pre-dispatch order's details such as addresses, times, or metadata. Only provided fields are updated.
operationId: update_order_v1_order__string_id__patch
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_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'
/v1/order/{id}/autodispatch:
post:
tags:
- Order
summary: Autodispatch order
description: Dispatch an order using the organization's dispatch strategy. Creates a job, requests quotes from providers, and automatically selects the best quote.
operationId: autodispatch_order_v1_order__string_id__autodispatch_post
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullJobPayload'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/order/{id}/confirm:
patch:
tags:
- Order
summary: Confirm order
description: Confirm a valid order, changing its status from 'valid' to 'confirmed'.
operationId: confirm_order_v1_order__string_id__confirm_patch
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
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'
/v1/order/{id}/documents:
get:
tags:
- Order
summary: Get order documents
description: Retrieve documents associated with an order such as shipping labels or proof of delivery. Set load_data=true to include the document content in the response.
operationId: get_order_documents_v1_order__string_id__documents_get
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
- name: loadData
in: query
description: Whether to load the document data and return it as part of the response.
required: true
schema:
title: Loaddata
type: boolean
description: Whether to load the document data and return it as part of the response.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDocumentResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/order/{id}/events:
post:
tags:
- Order
summary: Add custom event to order
description: Add a custom event to an order's event timeline. Rate limited to 3 requests per second per order with a max payload of 1KB.
operationId: add_order_event_v1_order__string_id__events_post
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddEventInputSerializer'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AddEventOutputSerializer'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/order/{id}/unarchive:
patch:
tags:
- Order
summary: Unarchive order
description: Restore a previously archived order, making it visible in default listings again.
operationId: unarchive_order_v1_order__string_id__unarchive_patch
parameters:
- name: id
in: path
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
required: true
schema:
title: Id
type: string
description: 'Unique reference number for the order: either order.id (starts with "ord_") or order.externalId'
example: ord_1234567890
example: ord_1234567890
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'
/v1/orders:
get:
tags:
- Order
summary: List/Search Orders
description: List orders with filters, sorting, and pagination. Returns a slim payload suitable for discovery; use GET /v1/order/<id> for full details.
operationId: list_orders_v1_orders_get
parameters:
- name: limit
in: query
required: false
schema:
title: Limit
maximum: 100
minimum: 1.0
type: integer
default: 25
example: 25
example: 25
- name: offset
in: query
required: false
schema:
title: Offset
minimum: 0.0
type: integer
default: 0
example: 0
example: 0
- name: sortBy
in: query
description: 'Sort field: created_at, updated_at, value_cents, pickup_start_time, pickup_end_time, dropoff_start_time, dropoff_end_time'
required: false
schema:
title: Sortby
type: string
description: 'Sort field: created_at, updated_at, value_cents, pickup_start_time, pickup_end_time, dropoff_start_time, dropoff_end_time'
default: created_at
example: created_at
example: created_at
- name: sortDirection
in: query
description: 'Sort direction: ASC or DESC'
required: false
schema:
title: Sortdirection
type: string
description: 'Sort direction: ASC or DESC'
default: DESC
example: DESC
example: DESC
- name: startDate
in: query
description: Lower bound for pickup/dropoff/created-at window. Defaults to 30 days ago.
required: false
schema:
title: Startdate
anyOf:
- type: string
format: date-time
- type: 'null'
description: Lower bound for pickup/dropoff/created-at window. Defaults to 30 days ago.
default: null
- name: endDate
in: query
description: Upper bound for pickup/dropoff/created-at window. Defaults to now.
required: false
schema:
title: Enddate
anyOf:
- type: string
format: date-time
- type: 'null'
description: Upper bound for pickup/dropoff/created-at window. Defaults to now.
default: null
- name: status
in: query
description: Comma-separated list of order statuses (e.g. active,pending_confirmation)
required: false
schema:
title: Status
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of order statuses (e.g. active,pending_confirmation)
default: null
example: active,pending_confirmation
example: active,pending_confirmation
- name: ids
in: query
description: Comma-separated list of order ids. Bypasses date filter when set.
required: false
schema:
title: Ids
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of order ids. Bypasses date filter when set.
default: null
- name: tags
in: query
description: Comma-separated list of tags
required: false
schema:
title: Tags
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of tags
default: null
- name: search
in: query
description: Free-form search
required: false
schema:
title: Search
anyOf:
- type: string
- type: 'null'
description: Free-form search
default: null
- name: hasRoute
in: query
description: 'Filter by route state: has_route, no_route, or all'
required: false
schema:
title: Hasroute
anyOf:
- type: string
- type: 'null'
description: 'Filter by route state: has_route, no_route, or all'
default: null
example: all
example: all
- name: pickupStoreLocationIds
in: query
description: Comma-separated store location ids
required: false
schema:
title: Pickupstorelocationids
anyOf:
- type: string
- type: 'null'
description: Comma-separated store location ids
default: null
- name: dropoffStoreLocationIds
in: query
description: Comma-separated store location ids
required: false
schema:
title: Dropoffstorelocationids
anyOf:
- type: string
- type: 'null'
description: Comma-separated store location ids
default: null
- name: city
in: query
description: Comma-separated list of pickup or dropoff cities
required: false
schema:
title: City
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of pickup or dropoff cities
default: null
- name: state
in: query
description: Comma-separated list of pickup or dropoff states
required: false
schema:
title: State
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of pickup or dropoff states
default: null
- name: country
in: query
description: Comma-separated list of pickup or dropoff countries
required: false
schema:
title: Country
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of pickup or dropoff countries
default: null
- name: pickupBusinessName
in: query
description: Comma-separated list
required: false
schema:
title: Pickupbusinessname
anyOf:
- type: string
- type: 'null'
description: Comma-separated list
default: null
- name: dropoffBusinessName
in: query
description: Comma-separated list
required: false
schema:
title: Dropoffbusinessname
anyOf:
- type: string
- type: 'null'
description: Comma-separated list
default: null
- name: creationSource
in: query
description: Comma-separated list
required: false
schema:
title: Creationsource
anyOf:
- type: string
- type: 'null'
description: Comma-separated list
default: null
- name: dispatchStrategyId
in: query
description: Comma-separated list
required: false
schema:
title: Dispatchstrategyid
anyOf:
- type: string
- type: 'null'
description: Comma-separated list
default: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrdersListResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
post:
tags:
- Order
summary: Create Orders
description: Create multiple pre-dispatch orders in a single request. Each order is created independently with its own pickup and dropoff details.
operationId: create_orders_v1_orders_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrdersInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrdersOutputExample'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/orders/bulk:
post:
tags:
- Order
summary: Create, update, upsert, or delete orders asynchronously in bulk
description: Submit a bulk operation to create, update, upsert, or delete multiple orders asynchronously. Returns a bulk operation ID that can be polled for results using the GET bulk endpoint.
operationId: orders_bulk_operation_v1_orders_bulk_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrdersBulkOperationInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperationResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/orders/bulk/{id}:
get:
tags:
- Order
summary: Get response from asynchronous bulk order operation
description: Retrieve the results of a previously submitted bulk order operation. Returns the status and individual results for each order in the batch.
operationId: get_orders_bulk_response_v1_orders_bulk__string_id__get
parameters:
- name: id
in: path
description: The ID of the bulk operation
required: true
schema:
title: Id
type: string
description: The ID of the bulk operation
example: act_1234567890
example: act_1234567890
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetBulkOperationResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/orders/external-identifier:
post:
tags:
- Order
summary: Create or update orders by external identifier
description: Create new orders or update existing ones using external identifiers. If an order with a given external identifier exists, it is updated; otherwise a new order is created.
operationId: create_or_update_orders_by_external_id_v1_orders_external_identifier_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrdersInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrdersOutputExample'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/orders/external-identifier/{external_id}/undispatch:
post:
tags:
- Order
summary: Undispatch an order
description: 'Un-dispatch a route-based order: cancel its active task and provider delivery, remove it from its route (re-syncing the linked batch), and revert it to the `valid` status. Returns the updated order. Errors if the order is not dispatched, or is not associated with a route.'
operationId: orders_undispatch_v1_undispatch_order_by_external_id_route_external_identifier__external_id__undispatch_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'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v1/orders/{order_id}/undispatch:
post:
tags:
- Order
summary: Undispatch an order by id
description: 'Un-dispatch a route-based order by id: cancel its active task and provider delivery, remove it from its route (re-syncing the linked batch), and revert it to the `valid` status. Returns the updated order. Errors if the order is not dispatched, or is not associated with a route.'
operationId: orders_undispatch_v1_undispatch_order_by_id_route__order_id__undispatch_post
parameters:
- name: orderId
in: path
description: The id of the order (starts with "ord_").
required: true
schema:
title: Orderid
type: string
description: The id of the order (starts with "ord_").
example: ord_1234567890
example: ord_1234567890
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidationError'
/v2/orders/upsert/bulk:
post:
tags:
- Order
summary: Create or update orders by external identifier (v2)
description: Create new orders or update existing ones by external identifier. Returns a `results` array — one entry per input order, in the same order as the request — each carrying a `success` or `failed` status, plus a `summary` of the counts. A hard failure on one order does not fail the batch; the rest still commit.
operationId: orders_v2_bulk_upsert_orders_route_upsert_bulk_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrdersInput'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUpsertOrdersResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NashValidatio
# --- truncated at 32 KB (314 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nash/refs/heads/main/openapi/nash-order-api-openapi.yml