Skip to main content
This guide demonstrates how to integrate Nash into the checkout and delivery process. It uses our fictional company Nom Nom Goods as an example, following our customer Sammy through the process.

​
Introduction

Imagine you built a business and app called Nom Nom Goods. Nom Nom Goods manages hundreds of stores across the country and uses Nash to orchestrate its deliveries.

​
The typical customer experience

Here’s what Sammy’s experience looks like in the Nom Nom app:
  1. Sammy adds items to his cart and selects a nearby store location.
  2. At checkout, he chooses to have his order delivered immediately.
  3. Nash, integrated into the checkout flow, provides delivery quotes and manages the delivery.
  4. Sammy receives his order quickly and reliably, along with status updates about his delivery.

​
Integration with Nash on checkout

To integrate Nash into your Nom Nom Goods checkout flow, you’ll follow these steps:
  1. Build the Dispatch Strategy: Configure how Nash selects the best delivery provider for each order.
  2. Set up Automations: Automatically apply the appropriate Dispatch Strategy based on predefined rules.
  3. Create an Order: When Sammy completes checkout, create a new order in Nash for delivery coverage and pricing.
  4. Autodispatch the Order: After Sammy places his order, let Nash dispatch it to the best provider automatically.
  5. Track the Delivery: Use live updates from Nash to keep Sammy informed about his order status.
The examples below use the sandbox host. You’ll need a sandbox API key, and the Nash-Org-Id header if your key has access to multiple organizations — see API Key and Org ID.
Here’s a diagram of the process we’ll build: Overview of how Nom Nom interacts with Nash and the delivery providers.

​
1. Building the Dispatch Strategy

Dispatch Strategies are configurations that determine how Nash selects delivery providers for your orders. You may prefer selecting the lowest-cost provider or have a ranked list of providers. To create a Dispatch Strategy, you can use either the Nash API or the Nash Portal. Below is an example of using the API to create a Dispatch Strategy with the following configuration:
  • Allowed Providers: NomNomDrive, HotRodWheels, FastFleet
  • Provider Selection Strategy: lowest_price (This indicates that Nash will choose the provider with the lowest delivery cost.)
  • Reassign on Failure: true (Nash will seek an alternative provider if the first choice cannot fulfill the order.)
  • Auto Dispatch: false (Indicate that we will manually manage the autodispatch of orders.)
For more details, refer to Dispatch Strategies. Here’s a sample curl command to create the Dispatch Strategy:
create dispatch strategy
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/options_group \
  --header 'Authorization: Bearer $NASH_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
	"label": "NomNomCheckoutStrategy",
	"allowedProviders": [
		"NomNomDrive", "HotRodWheels", "FastFleet"
	],
	"enableAutoDispatch": false,
	"providerSelectionStrategy": "lowest_price",
	"reassignOnFailure": true
}'

​
2. Setting up Automations

Automations allow you to apply Dispatch Strategies to your orders based on predefined rules, such as package value or delivery location. This ensures the correct Dispatch Strategy applies without manual intervention. You can configure Automations in the Nash Portal. For example, create a rule that applies the “NomNomCheckoutStrategy” Dispatch Strategy to any order with a package value over $50. This helps ensure that higher-value deliveries receive appropriate treatment.

​
3. Creating an order

When customer Sammy completes checkout in your Nom Nom Goods app, you’ll create a new order in Nash using the /v1/order endpoint. The order payload should include details such as:
  • Pickup address
  • Dropoff address
  • Package description
  • Package value
  • Any special instructions
Below is an example of an order creation payload:
payload for creating an order
{
  "pickupAddress": "185 University Ave, Palo Alto, CA 94301",
  "pickupBusinessName": "Yummy Donuts",
  "pickupPhoneNumber": "+172012345678",
  "pickupInstructions": "Pickup 10 boxes of glazed for Sammy. Order Number 1234",

  "dropoffAddress": "401 San Antonio Rd, Mountain View, CA 94040",
  "dropoffBusinessName": "Sammy's House",
  "dropoffFirstName": "Sammy",
  "dropoffLastName": "Camchaw",
  "dropoffPhoneNumber": "+12345679019",
  "dropoffInstructions": "Leave at the doorstep, plz!",

  "deliveryMode": "now",
  "description": "10 boxes of donuts",
  "valueCents": 8990,
  "taxAmountCents": 930,
  "tipAmountCents": 1000,
  "currency": "USD",
  "itemsCount": 10,

  "dispatchStrategyId": "dss_1234567890"
}
After creating the order, Nash will return a list of quotes from available delivery providers, including the price, estimated delivery time, and a tag indicating the preferred quote for autodispatch.
quote list in create order response
  "quotes": [
	{
		"id": "qot_UPVrXwaAt4tQraeY2mDgH2",
		"providerId": "NomNomDrive",
		"providerName": "NomNomDrive",
		"providerLogo": "https://nash-provider-logos.s3.amazonaws.com/FleetSimulator.png",
		"createdTime": "2022-09-21T22:28:47.533139",
		"expireTime": "2022-09-21T23:28:47.533139",
		"priceCents": 1800,
		"nashFeeCents": 100,
		"currency": "USD",
		"pickupWindow": null,
		"dropoffEta": "2022-09-21T22:31:47.533124",
		"costSplitCustomerCents": null,
		"costSplitBusinessCents": null
	},
	{
		"id": "qot_coBkLwCrgvtbAewhUGehf3",
		"providerId": "FastFleet",
		"providerName": "FastFleet",
		"providerLogo": "https://nash-provider-logos.s3.amazonaws.com/FleetSimulator.png",
		"createdTime": "2022-09-21T22:28:47.533681",
		"expireTime": "2022-09-21T23:28:47.533682",
		"priceCents": 650,
		"nashFeeCents": 100,
		"currency": "USD",
		"pickupWindow": null,
		"dropoffEta": "2022-09-21T22:37:47.533667",
		"tags": [
			"autodispatch_preferred_quote"
		],
		"costSplitCustomerCents": null,
		"costSplitBusinessCents": null
	},
	{
		"id": "qot_dvwfGGNGSc8yUrQxrp6cgp",
		"providerId": "HotRodWheels",
		"providerName": "HotRodWheels",
		"providerLogo": "https://nash-provider-logos.s3.amazonaws.com/FleetSimulator.png",
		"createdTime": "2022-09-21T22:28:47.534574",
		"expireTime": "2022-09-21T23:28:47.534574",
		"priceCents": 2000,
		"nashFeeCents": 100,
		"currency": "USD",
		"pickupWindow": null,
		"dropoffEta": "2022-09-21T22:34:47.534567",
		"tags": null,
		"costSplitCustomerCents": null,
		"costSplitBusinessCents": null
	}
]
Let’s say several minutes elapse while Sammy lingers on checkout, deciding whether to add an 11th box of donuts. The quotes have expired, so we refresh them for the order:
refresh order quotes
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/order/refresh_quotes \
  --header 'Authorization: Bearer $NASH_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "orderId": "ord_1234567890"
}'
Finally, Sammy clicks the Place Order button in the Nom Nom app. Since Nom Nom already created the order with the appropriate details in Nash, the only thing left is to autodispatch.

​
4. Autodispatching the order

Once you have reviewed the quotes, you can use Nash’s autodispatch feature to assign the delivery automatically to the best provider based on your Dispatch Strategy. To initiate the autodispatch process, you will call the /v1/order/{id}/autodispatch endpoint. Here’s an example of how to autodispatch an order:
autodispatch order
curl --request POST \
  --url https://api.sandbox.usenash.com/v1/order/ord_1234567890/autodispatch \
  --header 'Authorization: Bearer $NASH_API_KEY'
When an order is dispatched, it becomes a job (the fulfillment attempt). The response contains the job, and within its job configurations you’ll find two objects worth noting. The winnerQuote object on the job’s task has the selected quote’s ID.
autodispatch response - winner quote
"winnerQuote": {
  "id": "qot_coBkLwCrgvtbAewhUGehf3",
  "priceCents": 650
}
The delivery object indicates the delivery is active.
autodispatch response - delivery object
"delivery": {
  "id": "dlv_01234567890",
  "status": "CREATED"
}

​
5. Tracking the delivery

After dispatching the order, Nash provides live updates on the delivery status via webhooks. Use these webhooks to keep customers like Sammy informed about their order’s progress, such as when the driver is en route or when the delivery is complete.

​
Conclusion

That’s the whole loop: a Dispatch Strategy, an automation, an order, an autodispatch, and webhooks. Sammy gets his donuts; you get a delivery pipeline that runs the same way on every order.