---
name: nashtechnologies
description: Use when building delivery orchestration integrations, managing
  orders and dispatch strategies, configuring webhooks for real-time tracking,
  setting up automations and workflows, or troubleshooting delivery operations
  across multiple providers.
metadata:
  mintlify-proj: nashtechnologies
  version: "1.0"
---

# Nash Technologies Skill

## Product summary

Nash is a delivery orchestration platform that connects your business to 250+ delivery providers through a single API. Use it to create orders, request quotes from eligible providers, dispatch deliveries automatically or manually, track shipments in real-time, and recover failed deliveries. The core workflow is: create an order → get quotes → dispatch to a provider → track via webhooks. Key files and endpoints: API base URLs are `https://api.sandbox.usenash.com` (Sandbox) and `https://api.usenash.com` (Production), both with US and AU variants. Authentication uses Bearer tokens in the `Authorization` header plus an optional `Nash-Org-Id` header. Primary documentation: https://docs.usenash.com

## When to use

Reach for this skill when:

- Building a checkout flow that needs delivery quotes and pricing before payment
- Integrating delivery into an order management system (restaurants, e-commerce, logistics)
- Setting up automatic dispatch rules based on order attributes (value, location, urgency)
- Configuring real-time delivery tracking and status notifications for customers
- Handling delivery failures and automatic reassignments to backup providers
- Managing store locations, delivery zones, and multi-location operations
- Creating workflows that respond to delivery events (status changes, delays, cancellations)
- Troubleshooting why an order failed validation or dispatch
- Implementing internal fleet management alongside third-party providers

## Quick reference

### Authentication headers
```
Authorization: Bearer $NASH_API_KEY
Nash-Org-Id: $NASH_ORG_ID  (required if key has access to multiple orgs)
```

### Core API endpoints

| Task | Endpoint | Method |
|------|----------|--------|
| Create order & get quotes | `POST /v1/order` | POST |
| Get quotes for existing order | `POST /v1/order/{id}/get_quotes` | POST |
| Update order | `PATCH /v1/order/{id}` | PATCH |
| Auto-dispatch with strategy | `POST /v1/order/{id}/autodispatch` | POST |
| Manually select quote | `POST /v1/order/{id}/select_quote` | POST |
| Get job (delivery) status | `GET /v1/job/{id}` | GET |
| List orders/jobs | `GET /v1/order` or `GET /v1/job` | GET |
| Create dispatch strategy | `POST /v1/options_group` | POST |
| Create store location | `POST /v1/store_locations` | POST |
| Create zone | `POST /v1/zones` | POST |
| Create workflow | `POST /v1/workflows` | POST |
| Trigger workflow | `POST /v1/workflows/{id}/trigger` | POST |

### Delivery status lifecycle (lowercase in payloads)
```
created → assigned_driver → pickup_enroute → pickup_arrived → 
pickup_complete → dropoff_enroute → dropoff_arrived → dropoff_complete
```
Terminal states: `dropoff_complete`, `canceled_by_provider`, `canceled_by_customer`, `failed`

### Webhook event types
- `delivery` — status changes (created, assigned_driver, pickup_complete, etc.)
- `task` — task lifecycle (created, running, completed, canceled)
- `courier_location` — driver position updates (every 1-2 minutes)
- `courier_name` — driver change (same provider, different driver)
- `shift` — batch dispatch from delivery windows

### Rate limits
- 20 requests per second per organization
- HTTP 429 response when exceeded
- Implement exponential backoff with jitter on 429

### Address input (pick one approach)
- Single-line string: `pickupAddress: "123 Main St, City, ST 12345"`
- Google Place ID: `pickupPlaceId: "ChIJ..."`
- Address components: `pickupAddressFormattedStreet`, `pickupAddressCity`, etc.
- Store location ID: `pickupStoreLocationId: "stl_..."`

## Decision guidance

### When to use auto-dispatch vs manual selection

| Scenario | Use auto-dispatch | Use manual selection |
|----------|-------------------|----------------------|
| Fixed-price delivery, no customer choice | ✓ | |
| Customer picks provider/price at checkout | | ✓ |
| Lowest-cost routing always | ✓ | |
| Complex business logic for provider choice | | ✓ |
| Dispatch immediately on order creation | ✓ | |
| Show quotes first, dispatch later | | ✓ |

### When to use dispatch strategies vs automations vs workflows

| Use case | Tool | Why |
|----------|------|-----|
| High-value orders → white-glove provider | Automation | Rule-based, no code |
| Order value + location → different strategies | Automation | Multiple IF/ELIF rules |
| Complex logic: value + tags + distance | Workflow | More flexible, can branch |
| Respond to delivery events (late, failed) | Workflow | Event-driven actions |
| Simple provider selection rule | Dispatch strategy | Direct, reusable config |

### When to use store locations vs zones

| Concept | Use for | Example |
|---------|---------|---------|
| Store location | Physical pickup/dropoff points | Restaurant, warehouse, store |
| Zone | Geographic delivery area | "Serves downtown + suburbs" |
| Together | Link store to its service area | Store A serves zones X, Y, Z |

## Workflow

### Typical order-to-delivery flow

1. **Create order with quotes**
   - Call `POST /v1/order` with pickup, dropoff, package details, timing
   - Include `dispatchStrategyId` if auto-dispatching, or omit to get quotes only
   - Response includes order ID, list of quotes, and failedQuotes
   - Store the order ID for later reference

2. **Update order if needed**
   - Call `PATCH /v1/order/{id}` to add missing fields (externalId, instructions, metadata)
   - Refresh quotes if customer changed address: `POST /v1/order/{id}/refresh_quotes`

3. **Dispatch to provider**
   - **Auto-dispatch**: Call `POST /v1/order/{id}/autodispatch` (strategy selects provider)
   - **Manual**: Call `POST /v1/order/{id}/select_quote` with chosen quote ID
   - Response is a job (delivery) with status `created`

4. **Track delivery**
   - Set up webhook endpoint in Portal (Settings → Webhook Management)
   - Listen for `delivery` events: `assigned_driver`, `pickup_complete`, `dropoff_complete`, etc.
   - Or poll `GET /v1/job/{id}` for current status
   - Provide tracking link to customer: `https://track.usenash.com/{jobId}`

5. **Handle failures**
   - If provider cancels, dispatch strategy can auto-reassign (if enabled)
   - Listen for `canceled_by_provider` event and new `task.created` event
   - Or manually reassign: `POST /v1/job/{id}/reassign` with new provider

### Setting up a dispatch strategy

1. Create in Portal (Settings → Dispatch Strategies) or via API: `POST /v1/options_group`
2. Configure:
   - `allowedProviders`: list of provider IDs
   - `providerSelectionStrategy`: `lowest_price` or `preferred_order`
   - `enableAutoDispatch`: true/false
   - `reassignOnFailure`: true/false (auto-reassign if provider cancels)
   - `maxDeliveryFeeCents`: cost cap
3. Attach to orders: set `dispatchStrategyId` when creating order, or use automations

### Setting up webhooks

1. Go to Portal → Settings → Webhook Management
2. Click "Add Endpoint"
3. Enter your endpoint URL (must be HTTPS)
4. Choose event types to receive (or subscribe to all)
5. Copy the signing secret
6. In your code:
   - Verify signature using Svix SDK or manually with `svix-signature` header
   - Return HTTP 2xx within 30 seconds
   - Implement idempotency (same event may arrive multiple times)
   - Handle retries: Svix retries on 5xx, 408, 409, 429 responses

## Common gotchas

- **Address validation fails silently**: Pickup and dropoff must be in the same country and different locations. If you pass identical addresses, the API rejects it. Use `pickupAddress` OR `pickupPlaceId` OR address components — never mix them.

- **Quotes expire**: Every quote has an `expireTime`. If you hold an order too long before dispatching, quotes become stale. Call `refresh_quotes` before dispatch if more than a few minutes have passed.

- **Dispatch strategy not applied**: Automations only apply to orders without a `dispatchStrategyId` already set. If you manually set a strategy, automations are skipped. To release an order back to automations, set `dispatchStrategyId: null`.

- **Webhook signature verification is mandatory**: Don't skip signature verification. Use the Svix SDK for your language; manual verification is error-prone. The signing secret is in Portal → Webhook Management → click endpoint → Signing Secret.

- **429 errors need exponential backoff**: Don't retry immediately on 429. Wait 0.5s, then 1s, 2s, 4s, etc., with random jitter. Retrying too fast makes the problem worse.

- **Multiple tasks on one job**: When a job is reassigned, Nash creates a new task, not an edit. Both tasks stay in the job. Always read `jobConfigurations[].advancedTask` to find the live attempt, not the first task.

- **Store location deletion breaks orders**: Deleting a store location orphans orders that reference it. Archive instead of delete if possible, or update orders to use a different location first.

- **Batch jobs vs single orders**: A batch job carries multiple packages. Webhook payloads differ: batch jobs have a `batch` key; single orders have `"isBatch": false`. Handle both shapes.

- **External IDs for idempotency**: Always send `externalId` on orders and `externalIdentifier` on jobs. If a request times out or returns an error, retry with the same external ID — Nash will return the existing record instead of creating a duplicate.

- **Delivery windows and shifts**: Delivery windows (shifts) are for scheduled, batched dispatch. Orders in a window dispatch together when the cutoff passes. Don't mix on-demand and scheduled orders in the same window.

## Verification checklist

Before submitting work with Nash:

- [ ] API key is set in `Authorization: Bearer` header and not logged or exposed
- [ ] `Nash-Org-Id` header is included if the key has access to multiple organizations
- [ ] Order addresses are valid (different locations, same country, proper format)
- [ ] Dispatch strategy exists and is attached to orders (or automations are configured)
- [ ] Webhook endpoint is HTTPS and returns 2xx within 30 seconds
- [ ] Webhook signature verification is implemented (using Svix SDK)
- [ ] External IDs are set on orders and jobs for idempotency
- [ ] Quotes are refreshed if order was held for more than a few minutes
- [ ] Rate limit backoff is implemented (exponential, with jitter)
- [ ] Webhook payload shape is handled for both batch and single-order jobs
- [ ] Job status is read from `jobConfigurations[].advancedTask` for the live attempt
- [ ] Tested in Sandbox environment before moving to Production

## Resources

- **Full page navigation**: https://docs.usenash.com/llms.txt
- **API Overview**: https://docs.usenash.com/api-reference/api-overview
- **How Nash Works**: https://docs.usenash.com/reference/how-nash-works
- **Webhooks & Real-time Events**: https://docs.usenash.com/reference/webhooks

---

> For additional documentation and navigation, see: https://docs.usenash.com/llms.txt