> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shift dispatched event

> The shift.dispatched webhook fires when orders from a delivery window (shift) are dispatched in bulk to delivery jobs. Payload structure, scenarios, and error reference.

## Overview

The `shift.dispatched` webhook is sent when a bulk of orders from a delivery window (shift) is dispatched to delivery jobs. This webhook is part of Nash's automated dispatch system for partner delivery workflows and provides real-time updates on the dispatch status of orders grouped by store location and shift name.

**Event Type**: `shift.dispatched`\
**Entity Type**: `shift`\
**Event Name**: `dispatched`

<img src="https://mintcdn.com/nashtechnologies/GWptVUHDAuailYvz/images/shift_dispatched_sequence_diagram.png?fit=max&auto=format&n=GWptVUHDAuailYvz&q=85&s=db8a95ad68b6008d5aba4a8335c72e08" alt="Shift dispatched sequence diagram" width="1920" height="1920" data-path="images/shift_dispatched_sequence_diagram.png" />

***

## When is this webhook triggered?

The webhook is triggered when:

1. **Automatic Dispatch**: The system automatically dispatches orders from delivery windows that have passed their cutoff time
2. **Bulk Processing**: Orders are grouped by organization, store location, pick shift name, and cutoff date
3. **Validation Complete**: All orders in the group pass validation checks before dispatch

***

## Validation rules

Before orders are dispatched, the system validates each order against the following criteria:

### Order-level validations

1. **Delivery Window Status**
   * Delivery window status must be `confirmed`
   * Orders with other statuses (e.g., pending, canceled) are skipped

2. **Cutoff Time**
   * Cutoff time must have passed
   * Orders with future cutoff times are not dispatched

3. **Order Status**
   * Order must not already be in `dispatched` or `archived` status
   * Prevents duplicate dispatches

### Group-level validations

* All orders in a store/shift group must meet the criteria above
* If any order fails validation, it's reported in the `errors` field
* Successful orders still get dispatched; the webhook includes both successes and failures

***

## Webhook payload structure

The webhook payload follows this structure:

```json theme={"dark"}
{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_<activity_id>",
    "created_job_ids": ["job_<id1>", "job_<id2>", "job_<id3>"],
    "errors": {
      "ord_<order_id1>": "Error message describing the failure",
      "job_<job_id2>": "job_autodispatch_failure, Error dispatching to provider"
    }
  }
}
```

### Payload fields

| Field                  | Type   | Description                                               |
| ---------------------- | ------ | --------------------------------------------------------- |
| `type`                 | string | Always `"shift"` for shift-related webhooks               |
| `event`                | string | Always `"dispatched"` for this webhook                    |
| `data.eventSourceId`   | string | Activity ID that triggered the dispatch (format: `act_*`) |
| `data.created_job_ids` | array  | List of successfully created job IDs (format: `job_*`)    |
| `data.errors`          | object | Dictionary mapping order/job IDs to error messages        |

***

## Webhook scenarios

### Scenario 1: complete success

All orders in the shift are successfully dispatched to jobs.

**Example Payload:**

```json theme={"dark"}
{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_7xK9mP2nQ4wL",
    "created_job_ids": [
      "job_8rY3nK7pL2xM",
      "job_5tW9mN3kP8yQ",
      "job_2zX6kL8rM5wN",
      "job_9vT4nM7pQ3xK"
    ],
    "errors": {}
  }
}
```

**Interpretation:**

* 4 orders were successfully dispatched
* No errors occurred
* Each job ID corresponds to one order being delivered
* All orders from the shift are now in the delivery system

***

### Scenario 2: partial success with validation errors

Some orders succeed while others fail validation checks.

**Example Payload:**

```json theme={"dark"}
{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_4mK8pN2wL9xQ",
    "created_job_ids": [
      "job_3nL7mK9pW2xQ",
      "job_6kM2nP8wL5yR"
    ],
    "errors": {
      "ord_5xW9mL3kP7yN": "order_validation_error: Delivery address is incomplete",
      "ord_8nK2pM7wL4xQ": "order_validation_error: Order has validation_errors: Missing customer phone number"
    }
  }
}
```

**Interpretation:**

* 2 orders successfully dispatched (jobs created)
* 2 orders failed validation and were not dispatched
* Failed orders need to be corrected and re-dispatched manually
* The validation error messages provide details on what needs to be fixed

***

### Scenario 3: partial success with provider errors

Orders pass validation but fail when dispatching to the delivery provider.

**Example Payload:**

```json theme={"dark"}
{
  "type": "shift",
  "event": "dispatched",
  "data": {
    "eventSourceId": "act_9pL3nM7kW2xQ",
    "created_job_ids": [
      "job_2kM8nL9pW5xQ",
      "job_7nK3mP2wL8yR"
    ],
    "errors": {
      "job_4xW9mL3kP7yN": "job_autodispatch_failure, Error dispatching to provider",
      "ord_8nK2pM7wL4xQ": "order_validation_error: Order has validation_errors: Missing customer phone number"
    }
  }
}
```

**Interpretation:**

* 2 orders successfully dispatched to the provider
* 1 order failed at the provider dispatch stage (after job creation)
* 1 order failed validation and was not dispatched
* Provider errors may indicate capacity issues, service area restrictions, or provider API problems
* Orders with provider errors may have jobs created but not accepted by the provider

***

## Error types reference

### Order validation errors

Order validation errors come from Nash's order validation. See the full validation rules in [Order validations](/api-reference/order/order-validations).

**Common validation error patterns:**

#### Required fields

| Field                                      | Error Message                                                                                                  |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Any required field                         | `required field`                                                                                               |
| `pickupFirstName` / `pickupBusinessName`   | `required field if pickupBusinessName is not provided` / `required field if pickupFirstName is not provided`   |
| `dropoffFirstName` / `dropoffBusinessName` | `required field if dropoffBusinessName is not provided` / `required field if dropoffFirstName is not provided` |

#### Store location errors

| Error Message                                       | Meaning                                     |
| --------------------------------------------------- | ------------------------------------------- |
| `{store_location_id} does not exist`                | Store location ID not found in organization |
| `{store_location_id} is deleted`                    | Store location has been deleted             |
| `Error creating store {external_store_location_id}` | Failed to auto-create store location        |

#### Address and location errors

| Error Message                                                                                                                          | Meaning                                    |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `Address not found`                                                                                                                    | Address could not be geocoded/parsed       |
| `Pickup and dropoff places must be the different`                                                                                      | Same place\_id used for pickup and dropoff |
| `Pickup and dropoff addresses must be the different`                                                                                   | Identical pickup and dropoff addresses     |
| `Pickup and dropoff countries must be the same`                                                                                        | Cross-border delivery not allowed          |
| `Distance between pickup and dropoff is {distance} miles, which exceeds your organization's maximum delivery distance of {max} miles.` | Distance exceeds org-specific limit        |
| `Distance between pickup and dropoff locations is too large: {distance} miles. Limit is 300 miles.`                                    | Distance exceeds global default limit      |

#### Phone number errors

| Error Message           | Meaning                                     |
| ----------------------- | ------------------------------------------- |
| `Invalid phone number`  | Phone number format invalid for country     |
| Phone validation errors | Various errors from phone number validation |

#### Value and type errors

| Field                                          | Error Message                         | Meaning                                |
| ---------------------------------------------- | ------------------------------------- | -------------------------------------- |
| `valueCents`, `tipAmountCents`, `itemsCount`   | `value must be an integer`            | Non-integer value provided             |
| `weight`, `height`, `width`, `depth`, `volume` | `value must be a decimal number`      | Non-numeric value provided             |
| Numeric fields                                 | `value must be greater than 0`        | Zero or negative value                 |
| `valueCents`                                   | `value must be more than 0`           | Order value is zero or negative        |
| `itemsCount`                                   | `value must be more than 0 or null`   | Items count is zero                    |
| `maxDeliveryFeeCents`                          | `value must be greater than 0`        | Max fee is zero or negative            |
| Name fields                                    | `value must be a string`              | Non-string value provided              |
| Name fields                                    | `value is too long: {length} > {max}` | Name exceeds maximum length (80 chars) |

#### Delivery mode and datetime errors

| Error Message                                  | Meaning                                                        |
| ---------------------------------------------- | -------------------------------------------------------------- |
| `Valid values are {PackageDeliveryModeValues}` | Invalid delivery mode (must be `now` or `scheduled`)           |
| `at least one value is required`               | Scheduled mode requires at least one datetime field            |
| `Time is in the past`                          | Datetime is earlier than current time (when not allowed)       |
| `cannot be later than pickupEndTime`           | `pickupStartTime` is after `pickupEndTime`                     |
| `cannot be later than dropoffEndTime`          | `pickupEndTime` or `pickupStartTime` is after `dropoffEndTime` |
| `cannot be later than dropoffStartTime`        | `pickupStartTime` is after `dropoffStartTime`                  |

#### Currency and requirements errors

| Field                | Error Message                                           | Meaning                     |
| -------------------- | ------------------------------------------------------- | --------------------------- |
| `currency`           | `Supported currencies are {SUPPORTED_CURRENCIES}`       | Invalid currency code       |
| `requirements`       | `Supported values are {SUPPORTED_PACKAGE_REQUIREMENTS}` | Invalid package requirement |
| `minimumVehicleSize` | `Supported values are {VEHICLES_TO_SHOW_USERS}`         | Invalid vehicle size        |

#### External ID errors

| Error Message                                            | Meaning                    |
| -------------------------------------------------------- | -------------------------- |
| `'{external_id}' is used in other order(s): {order_ids}` | External ID already in use |

#### Items errors

| Error Message               | Meaning                                     |
| --------------------------- | ------------------------------------------- |
| `The items data is invalid` | Items array contains invalid data structure |

### Provider dispatch errors

| Error Message                                             | Meaning              | Action Required                                 |
| --------------------------------------------------------- | -------------------- | ----------------------------------------------- |
| `job_autodispatch_failure, Error dispatching to provider` | Provider API failure | Check provider status, retry manually if needed |
| `job_autodispatch_failure, Error dispatching to a job`    | Job creation failed  | Review job configuration and order details      |