API Tutorial Example Workflow - Nom Nom Goods

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 is eager to leverage Nash for orchestrating deliveries.

The Typical Customer Experience

Here’s what Sammy’s experience looks like in the Nom Nom app:

🍩 Sammy adds items to his cart and selects a nearby store location.
🧾 At checkout, he chooses to have his order delivered immediately.
🚚 Nash is integrated into the checkout flow to provide delivery quotes and manage the delivery process.
👍 Sammy receives his orders 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:

Build the Dispatch Strategy: Configure how Nash selects the best delivery provider for each order.
Set up Automations: Automatically apply the appropriate Dispatch Strategy based on predefined rules.
Create an Order: When Sammy completes checkout, create a new order in Nash for delivery coverage and pricing.
Autodispatch the Order: After Sammy places his order, Use Nash’s autodispatch feature.
Track the Delivery: Use live updates from Nash to keep Sammy informed about his order status.

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 $TOKEN' \
  --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

{
  # pickup
  "pickupAddress": "185 University Ave, Palo Alto, CA 94301",
  "pickupBusinessName": "Yummy Donuts",
  "pickupPhoneNumber": "+172012345678",
  "pickupInstructions": "Pickup 10 boxes of glazed for Sammy. Order Number 1234",

  # dropoff
  "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!",

  # package info
  "deliveryMode": "now",
  "description": "10 boxes of donuts",
  "valueCents": 100,
  "taxAmountCents": 9.3,
  "tipAmountCents": 10.0,
  "currency": "USD",
  "itemsCount": 10,

  # dispatch strategy
  "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 elapsed because Sammy was lingering on checkout (deciding whether to add an 11th box of Donuts!) As a result, the quotes have expired!! We can do a simple quote refresh for the order:

refresh order quotes

curl --request POST \
  --url https://api.sandbox.usenash.com/v1/order/refresh_quotes \
  --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 leverage 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.usenash.com/v1/order/ord_1234567890/autodispatch \
  --header 'Authorization: Bearer $TOKEN'

When an Order gets dispatched, it becomes a Job. In the response, you’ll get several objects. A winnerQuote object has the quote ID.

autodispatch response - winner quote

"winnerQuote": {
  "id": "qot_5yb6yrMtvTvxQnDaEZymDp",
  "price_cents": 100
}

The delivery object indicates the delivery is active.

autodispatch response - delivery object

"delivery": {
  "id": "dlv_01234567890",
  "type": "<string>",
  "status": "CREATED",
}

5. Tracking the Delivery

After dispatching the order, Nash provides live updates on the delivery status via webhooks. Leverage 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. This transparency enhances the customer experience throughout the delivery process.

Conclusion

That’s it! Sammy received his donuts and is a happy customer. 🎉🍩

Guides

​Introduction

​The Typical Customer Experience

​Integration with Nash on Checkout

​1. Building the Dispatch Strategy

​2. Setting Up Automations

​3. Creating an Order

​4. Autodispatching the Order

​5. Tracking the Delivery

​Conclusion