Orders overview

An Order represents the delivery details for package(s) in the real world. It’s the most flexible way to initiate deliveries in Nash. Orders enable you to:

Update the delivery details before a delivery is created (contact details, addresses, times, and requirements) e.g. E-Commerce Checkout Experience
Understand whether the order meets the criteria to become a delivery (validation) e.g. Error handling as early as possible
Batch orders through Nash Platform (not optimized or batched on your end) e.g. Optimizing catering routes

When one or more Orders are dispatched, they become a Job.

Choose an order creation flow

The order endpoints return similar response objects, but they create, validate, quote, and dispatch Orders differently.

Recommended checkout flow

For most checkout integrations, start with Create Quote, then update the returned Order after checkout. This separates the eligibility and price check from the final fulfillment details.

Create the Order and request quotes

Send the details needed to evaluate delivery eligibility and price. Create Quote always starts a new Order; it does not look up an existing Order by externalId. If order-level validation fails, Nash returns 400 VALIDATION_ERRORS and does not save the new Order. A successful response includes the saved Order, its provider quotes, and the quotes_only tag.

Finalize the Order after checkout

Call Update Order with the returned Order ID. If the Create Quote request included externalId, you can use that identifier in the same update path instead. Send the final fulfillment details and the complete tags list without quotes_only. Nash runs full order validation. If the Order is valid, it can auto-dispatch when its dispatch strategy has auto-dispatch enabled.

Using externalId in the Update Order path does not turn it into an upsert. The Order must already exist. Update Order refreshes an existing quote set after the update. Create or Update by External Identifier creates the Order when no match exists and requests fresh quotes on each call while quotes_only remains. Use a different creation flow when you do not need quotes before saving an Order or need one request that creates or updates by your own identifier.

Flow	Use when	Behavior
Create Order	You need a new Order without quotes in the same call.	Runs order-creation workflows and can auto-dispatch a valid Order.
Create Quote	You need to check delivery eligibility and price before checkout.	Always attempts a new Order; it does not look up `externalId`. On success, it saves the Order, requests quotes, and adds `quotes_only`.
Create or Update by External Identifier	You need one request to create the Order when your identifier is new and update it when it already exists.	Creates once, then updates. With `quotes_only`, each request replaces the previous quotes.

quotes_only is persistent Order state, not a response option. When an Order created by external identifier remains tagged quotes_only, each later create-or-update request asks providers for fresh quotes. Omitting tags preserves the existing tag. To return the Order to its normal dispatch flow, send the complete tags list without quotes_only.

Validation behavior

Create Order and Create Quote use normal order-creation validation when quotes_only is absent from the request. Create Quote adds the tag only after it validates the Order and requests quotes. If externalId already belongs to another Order, Create Quote returns 400 VALIDATION_ERRORS and does not save the new attempt. Later updates use quote-specific validation while the tag remains, so Nash can price an Order that has enough information for quoting but is not ready for fulfillment.

Flow	Response	Order state
Create Order	`200` with `validationErrors`	Saved as `needs_attention`.
Create Quote	`400 VALIDATION_ERRORS`	Not saved.
Create or Update by External Identifier	Without `quotes_only`: `200` with saved errors. With it: quote generation can return `400`.	The Order may already exist after a `400`, so retrieve it by external identifier before retrying.

The outcomes in the table describe order-level validation, which runs after Nash accepts the request body. Request-shape errors, such as a field with the wrong type, return 422 VALIDATION_ERRORS before the Order is created or updated. When moving from checkout to dispatch, update the Order with the remaining fulfillment fields and remove quotes_only before relying on normal validation or auto-dispatch.

The Orders page in the Nash Portal, with orders grouped into status tabs

Order data model

Order status

needs_attention: The order requires attention due to some data issues (e.g. invalid address)
valid: The order is valid and is ready to be dispatched to a Nash Job & Delivery.
dispatched: The order has been dispatched and a job (delivery) created for it. Open the job from the view dispatched job action in the Portal.
archived: The order has been archived and is moved to the archived tab in the Nash Portal.

Note: All timestamps are in UTC and in this format %Y-%m-%dT%H:%M:%S.%f

{
  "id": "ord_PewiSWzxmCFPzW62Ry3A6V",
  "createdAt": "2024-01-25T21:10:43.722214",
  "externalId": null,
  "externalGroupId": null,
  "referenceId": null,
  "portalUrl": "https://portal.sandbox.usenash.com/orders/ord_PewiSWzxmCFPzW62Ry3A6V",
  "publicTrackingUrl": "https://tracking.sandbox.usenash.com/ord_PewiSWzxmCFPzW62Ry3A6V",
  "status": "valid",
  "tags": null,
  "orderMetadata": null,
  "pickupAddress": null,
  "pickupPhoneNumber": "+15005550005",
  "pickupFirstName": "pickupFName",
  "pickupLastName": "pickupLName",
  "pickupBusinessName": "pickupBusinessName",
  "pickupInstructions": "Ask for the manager at the counter",
  "pickupBarcodes": null,
  "dropoffAddress": "401 San Antonio Rd, Mountain View, CA 94040",
  "dropoffPhoneNumber": "+15005550006",
  "dropoffFirstName": "dropoffFName",
  "dropoffLastName": "dropoffLName",
  "dropoffBusinessName": "dropoffBusinessName",
  "dropoffInstructions": "Leave the package at the front desk",
  "dropoffBarcodes": null,
  "deliveryMode": "now",
  "pickupStartTime": null,
  "pickupEndTime": null,
  "dropoffStartTime": null,
  "dropoffEndTime": null,
  "description": "Test package description",
  "itemsCount": null,
  "requirements": ["photo_proof_of_delivery"],
  "minimumVehicleSize": null,
  "currency": null,
  "documents": [
    {
      "id": "doc_ELre5GCELQ6w3UHKAgbm6F",
      "type": "shipping_label",
      "url": "https://nash-documents.s3-us-west-1.amazonaws.com/dlv_bR7NWwhWSQRohyjs7UZd7D_fEavuZda787M70sJEhtCAA==.png",
      "data": null,
      "contentType": "image/png"
    },
    {
      "id": "doc_nuKEL5W8mMgnXuRrFqwwsc",
      "type": "pickup_label",
      "url": "https://nash-documents.s3-us-west-1.amazonaws.com/dlv_bR7NWwhWSQRohyjs7UZd7D_QPiARbKwfJRkC94KVQrT8w==.png",
      "data": null,
      "contentType": "image/png"
    }
  ],
  "valueCents": "5000",
  "tipAmountCents": "100",
  "width": null,
  "depth": null,
  "height": null,
  "volume": null,
  "weight": null,
  "dispatchStrategyId": null,
  "validationErrors": {}
}

Getting started

Order

Dispatch strategies

Notifications

Store locations & zones

Jobs

Batch jobs

Providers

Routes

Optimization strategies

Shifts

Templates

Store catalog

Feedback

Shipping

Simulate delivery

Fleet

Miscellaneous

Orders overview

Choose an order creation flow

Recommended checkout flow

Validation behavior

Order data model

​Choose an order creation flow

​Recommended checkout flow

​Validation behavior

​Order data model

Choose an order creation flow

Recommended checkout flow

Validation behavior

Order data model