---
name: Nashtechnologies
description: Use when building delivery orchestration integrations, managing orders and dispatch strategies, configuring workflows and automations, setting up webhooks for real-time tracking, or working with the Nash API to create, quote, dispatch, and track deliveries across 80+ providers.
metadata:
    mintlify-proj: nashtechnologies
    version: "1.0"
---

# Nash Technologies Skill

## Product summary

Nash is a delivery orchestration platform that connects businesses to 80+ delivery providers through a single REST API. Agents use Nash to create orders, request quotes from eligible providers, dispatch deliveries with configurable strategies, track shipments in real-time, and automate operational decisions through workflows. The platform normalizes provider APIs into a unified interface, handles failover and reassignment, and provides webhooks for real-time event notifications.

**Key files and endpoints:**
- API base: `https://api.sandbox.usenash.com/v1` (Sandbox) or `https://api.usenash.com/v1` (Production)
- Authentication: Bearer token in `Authorization` header + optional `Nash-Org-Id` header
- Core resources: Orders, Jobs (dispatched deliveries), Dispatch Strategies, Workflows, Webhooks, Store Locations, Zones
- Rate limit: 20 requests/second per organization
- Primary docs: https://docs.usenash.com

## When to use

Reach for this skill when:
- **Creating and managing orders**: Building checkout workflows, importing bulk orders, or updating delivery details
- **Quoting and dispatch**: Requesting provider quotes, selecting providers manually, or setting up auto-dispatch with strategies
- **Configuring automation**: Building workflows that respond to events (order created, delivery status changed) with actions (apply strategy, send notification, call external system)
- **Setting up real-time tracking**: Configuring webhooks to receive delivery status updates, ETA changes, proof of delivery
- **Managing fleet operations**: Creating store locations, defining delivery zones, managing routes and optimization
- **Handling failures**: Setting up reassignment rules, failover strategies, or escalation workflows
- **Integrating with external systems**: Calling custom APIs from workflows, syncing order data, or triggering downstream actions

Do not use for: Portal-only operations (SSO setup, user management), payment processing, or customer-facing tracking pages (use the embedded tracking URL instead).

## Quick reference

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

### Core workflow: Create → Quote → Dispatch → Track
| Step | Endpoint | Purpose |
|------|----------|---------|
| Create | `POST /v1/orders` | Submit delivery details (pickup, dropoff, package info) |
| Quote | Included in Create response | Get provider quotes with prices and ETAs |
| Dispatch | `POST /v1/orders/{id}/autodispatch` or `POST /v1/orders/{id}/select-quote` | Assign to provider |
| Track | `GET /v1/jobs/{id}` or webhooks | Monitor delivery status |

### Order creation fields (required)
- `pickupAddress` or `pickupPlaceId` or componentized address fields
- `dropoffAddress` or `dropoffPlaceId` or componentized address fields
- `packagePickupStartTime`, `packagePickupEndTime`
- `packageDropoffStartTime`, `packageDropoffEndTime`
- `packageValue` (in cents)

### Dispatch strategy selection
| When | Use |
|------|-----|
| Auto-dispatch on creation | Set `dispatchStrategyId` on order + `enableAutoDispatch: true` on strategy |
| Manual selection at checkout | Omit strategy, return quotes to customer, call `POST /v1/orders/{id}/select-quote` with chosen quote ID |
| Rule-based automation | Create automations in Portal or use workflows to apply strategies based on order attributes |

### Webhook event types
- `delivery.*` — delivery status transitions (pickup_complete, dropoff_complete, failed, etc.)
- `task.*` — task-level events (quotes received, provider assigned)
- `courier_location.*` — real-time courier location updates
- `shift.*` — driver shift events

### Common error codes
| Code | Meaning | Action |
|------|---------|--------|
| `VALIDATION_ERRORS` (422) | Order failed validation (bad address, past pickup time, etc.) | Fix fields in `validationErrors` array and retry |
| `MISSING_RESOURCE` (404) | Order/job/strategy not found | Verify ID and organization context |
| `TOO_MANY_REQUESTS` (429) | Rate limit exceeded | Back off exponentially with jitter; use external IDs for idempotency |
| `INVALID_STATE_TRANSITION` (409) | Action not allowed in current state | Check job status; e.g., can't update addresses after dispatch |

### Bulk operations
- **Bulk create/update orders**: `POST /v1/orders/bulk` (async, returns operation ID)
- **Bulk update deliveries**: `POST /v1/deliveries/bulk` (up to 100 per request)
- **Batch jobs**: `POST /v1/jobs/batch` (multiple pickups/dropoffs in one delivery)

### External identifiers (idempotency)
Use `externalId` on orders and `externalIdentifier` on jobs to tie Nash records to your system. Retry the same external ID safely — Nash blocks duplicate creation and returns the existing record.

## Decision guidance

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

| Scenario | Approach | Why |
|----------|----------|-----|
| Fixed-price delivery, no customer choice | Auto-dispatch with strategy | Set it once, Nash handles provider selection |
| Customer chooses delivery option at checkout | Manual selection | Return quotes, let customer pick, then dispatch their choice |
| High-value orders need white-glove service | Separate strategy + automations | Route by order value or tags to different provider pools |
| Mixed order book (routine + urgent) | Dynamic Dispatch strategy | Nash balances cost/reliability per delivery |

### When to use workflows vs. dispatch strategies

| Decision | Workflows | Dispatch Strategies |
|----------|-----------|-------------------|
| Which provider fulfills this delivery? | ✓ (via dispatch_strategy action) | ✓ (direct attachment) |
| When should dispatch happen? | ✓ (time-based triggers) | ✓ (on creation, before pickup, on confirmation) |
| What if a provider fails? | ✓ (reassign action) | ✓ (failover rules) |
| Send a notification? | ✓ (email, SMS, Slack) | ✗ |
| Call an external system? | ✓ (HTTP request action) | ✗ |
| Validate order with custom rules? | ✓ (order.validating trigger) | ✗ |

### Address input: single-line vs. componentized

| Input | When to use | Example |
|-------|------------|---------|
| `pickupAddress` (single string) | Nash geocodes it | `"123 Main St, San Francisco, CA 94102"` |
| `pickupPlaceId` (Google Place ID) | You have a Place ID | `"ChIJIQBpAG2ahYAR_6128GltTLM"` |
| Componentized fields | You have your own geocoding | `pickupAddressFormattedStreet`, `pickupAddressCity`, `pickupLat`, `pickupLng` |

**Never mix**: Don't send both `pickupAddress` and `pickupPlaceId`, or address components with either of those.

## Workflow

### Typical integration task: Build a checkout flow

1. **Understand the order**: Gather pickup location (store ID or address), dropoff address, package details, timing windows.

2. **Check existing content**: Search for existing orders by `externalId` to avoid duplicates. Use `GET /v1/orders/external_identifier/{externalId}` if you've seen this order before.

3. **Create or update the order**: 
   - Call `POST /v1/orders` with delivery details and `quotes_only: true` tag to get quotes without committing to dispatch
   - Or use `POST /v1/orders/external_identifier/{externalId}` to create/update by your ID
   - Response includes `quotes` array with provider options, prices, ETAs

4. **Present quotes to customer**: Show delivery options (provider, price, ETA) from the quotes response. Let customer select one.

5. **Dispatch the selected quote**:
   - Call `POST /v1/orders/{orderId}/select-quote` with the chosen `quoteId`
   - Or if using auto-dispatch, call `POST /v1/orders/{orderId}/autodispatch` to let strategy pick

6. **Set up tracking**:
   - Retrieve `publicTrackingUrl` from the job response for customer-facing tracking
   - Configure webhooks to receive status updates in real-time
   - Poll `GET /v1/jobs/{jobId}` if webhooks aren't available

7. **Handle failures**:
   - Monitor webhook events for `delivery.failed` or `delivery.cancelled`
   - If reassignment is enabled in the strategy, Nash automatically fetches new quotes
   - If manual intervention needed, call `POST /v1/jobs/{jobId}/reassign-task` to trigger reassignment

8. **Verify**: Confirm order status is `active`, delivery is assigned to a provider, and tracking is live.

### Typical automation task: Set up a workflow

1. **Define the trigger**: Choose when the workflow runs (e.g., `order.created`, `delivery.pickup_complete`, time-based like "30 minutes before dropoff window ends")

2. **Add filters**: Branch on order attributes (value, location, tags, distance) to decide what happens next

3. **Add actions**: Apply a dispatch strategy, modify order price, send a notification, call an external system, or hand off to a custom agent

4. **Test before activating**: Use `POST /v1/workflows/{id}/test` with a real order/job ID to dry-run the workflow

5. **Activate**: Set workflow status to `active` and monitor runs in the Portal's Runs tab

6. **Iterate**: Adjust filters and actions based on run results; test again before re-activating

## Common gotchas

- **Address validation fails silently**: If `pickupAddress` doesn't geocode, the order is saved with `status: needs_attention` and `validationErrors` array. Check this field before assuming the order is ready to dispatch.

- **Quotes expire**: Each quote has an `expireTime`. Refresh quotes with `POST /v1/orders/{id}/refresh-quotes` if the customer takes too long to decide.

- **Updating after dispatch breaks quotes**: Once an order is dispatched, you can't change pickup/dropoff addresses or times. Update before dispatch or cancel and create a new order.

- **External IDs are per-organization**: If your API key has access to multiple orgs, the same `externalId` can exist in different orgs. Always send `Nash-Org-Id` header to avoid collisions.

- **Workflows on synchronous runs can't use agents**: If a workflow runs synchronously (during order creation), it can't invoke a custom agent because the order would wait on the agent. Use async triggers or manual runs for agent nodes.

- **Validation workflows can only mark invalid**: The `order.validating` trigger can only run filters and the `Mark order invalid` action. It can't dispatch, modify prices, or send notifications.

- **Rate limit is per-organization, not per-key**: All keys for an org share the 20 req/sec limit. Smooth your traffic with token buckets or concurrency limits rather than bursting and retrying.

- **Reassignment can increase cost**: By default, reassignment can pick a more expensive provider. Set `preventReassignmentPriceIncrease: true` on the strategy to cap cost at the first selected quote.

- **Webhooks are not durable**: Treat webhooks as signals, not a queue. If your endpoint is down, Nash retries per its policy, but doesn't guarantee delivery. Always poll for critical updates.

- **Store location auto-creation**: If you pass `pickupExternalStoreLocationId` and it doesn't exist, Nash may auto-create a store location from the order's pickup details (if enabled). Verify this doesn't create duplicates.

## Verification checklist

Before submitting work:

- [ ] **Authentication**: API key is valid, `Nash-Org-Id` header is set if needed, no credentials in logs
- [ ] **Order validation**: Check `validationErrors` array; address geocodes, pickup time is in the future, dropoff is different from pickup
- [ ] **Quotes received**: Response includes `quotes` array with at least one provider; no `failedQuotes` that indicate coverage gaps
- [ ] **Dispatch method chosen**: Auto-dispatch strategy is set OR manual quote selection is ready; not both undefined
- [ ] **External IDs used**: Orders and jobs have `externalId`/`externalIdentifier` for idempotency and traceability
- [ ] **Webhooks configured**: Endpoint is registered, signed, and tested; not relying solely on polling
- [ ] **Workflow tested**: Dry-run passed; filters match expected orders; actions produce intended results
- [ ] **Rate limit handled**: Backoff logic in place for 429 responses; bulk operations use async endpoints
- [ ] **Error handling**: Code catches `VALIDATION_ERRORS`, `MISSING_RESOURCE`, `INVALID_STATE_TRANSITION`, and retries with exponential backoff
- [ ] **Tracking URL embedded**: Customer-facing tracking uses `publicTrackingUrl` from job response, not custom polling

## Resources

- **Comprehensive navigation**: https://docs.usenash.com/llms.txt — page-by-page listing of all documentation
- **How Nash works**: https://docs.usenash.com/reference/how-nash-works — delivery lifecycle, core concepts, provider network
- **API overview**: https://docs.usenash.com/api-reference/api-overview — authentication, environments, rate limits, available endpoints
- **Dispatch strategies**: https://docs.usenash.com/reference/dispatch-strategies — provider selection rules, failover, cost controls, automations

---

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