# Shipment purchased

> Sent when a shipment is booked.

`eventType` is `shipment.purchased`.

Mothership sends one `shipment.purchased` per shipment, seconds after the purchase completes. `data` is read then, so a stop or price that changed in those seconds goes out changed.

To follow the shipment from here, subscribe to [`shipment.status.updated`](https://docs.mothership.com/reference/shipment-status-updated) too. Its first event, `Unallocated`, comes about the same time as this one. Don't rely on which arrives first.

## Subscribing

Add `shipment.purchased` to a configuration's `subscribedEvents`. It needs no extra permission.

## Event data

- `createdAt` (string): When the shipment was created, as an ISO 8601 string in UTC.
- `delivery` (object): The delivery stop.
  - `accessorials` (array of strings): Services the stop needs, such as `liftgate`. Includes `alcohol`, `hazmat` and `tobacco` when any freight item is marked with them. Empty when there are none.
  - `city` (string): The city.
  - `closeTime` (string): When the stop closes, as `HHmm` in its local time, such as `1700`. The string `Invalid date` when the stop has no closing time.
  - `coordinates` (object): Where the stop is.
    - `latitude` (number): Latitude in degrees.
    - `longitude` (number): Longitude in degrees.
  - `emails` (array of strings): Contact emails for the stop, split from one contact field, so trim each before you use it. Empty when there are none.
  - `name` (string): The location's name, or an empty string.
  - `openTime` (string): When the stop opens, as `HHmm` in its local time, such as `0900`. The string `Invalid date` when the stop has no opening time.
  - `phoneNumber` (string): The contact phone number, such as `+13103329380`.
  - `placeId` (string): The location's place ID, or an empty string.
  - `state` (string): The state, such as `CA`.
  - `street` (string): The first street line.
  - `subStreet` (string, can be missing): The second street line. Missing when the stop has none.
  - `zip` (string): The ZIP code.
- `earliestPickupDate` (string): The start of the pickup window, as an ISO 8601 string in the pickup's time zone with its offset and no milliseconds, such as `2026-10-09T08:00:00-07:00`. A zero offset is written `Z`.
- `estimatedDeliveryDate` (string): The end of the delivery window, in the delivery stop's time zone, written the same way as `earliestPickupDate`.
- `freight` (array of objects): The freight, one entry per line item.
  - `description` (string): What the freight is, or an empty string.
  - `height` (number): Height of each item, in inches.
  - `length` (number): Length of each item, in inches.
  - `quantity` (integer): How many items the line has.
  - `type` (string): The packaging, such as `Pallet`.
  - `weight` (number): Weight of each item, in pounds.
  - `width` (number): Width of each item, in inches.
- `pickup` (object): The pickup stop.
  - `accessorials` (array of strings): Services the stop needs, such as `liftgate`. Includes `alcohol`, `hazmat` and `tobacco` when any freight item is marked with them. Empty when there are none.
  - `city` (string): The city.
  - `closeTime` (string): When the stop closes, as `HHmm` in its local time, such as `1700`. The string `Invalid date` when the stop has no closing time.
  - `coordinates` (object): Where the stop is.
    - `latitude` (number): Latitude in degrees.
    - `longitude` (number): Longitude in degrees.
  - `emails` (array of strings): Contact emails for the stop, split from one contact field, so trim each before you use it. Empty when there are none.
  - `name` (string): The location's name, or an empty string.
  - `openTime` (string): An opening time as `HHmm`. On `pickup` this holds the delivery stop's opening time, as it always has, so read the pickup's hours from Get shipment details. The string `Invalid date` when there is none.
  - `phoneNumber` (string): The contact phone number, such as `+13103329380`.
  - `placeId` (string): The location's place ID, or an empty string.
  - `state` (string): The state, such as `CA`.
  - `street` (string): The first street line.
  - `subStreet` (string, can be missing): The second street line. Missing when the stop has none.
  - `zip` (string): The ZIP code.
- `price` (number): What the shipment costs you, in dollars, such as `312.48`. Rebill and invoice events send amounts in cents.
- `shipmentId` (string): The shipment's reference number, such as `MS123456`. Pass it to Get shipment details.
- `status` (string): The shipment's status when Mothership built the event, seconds after the purchase. Usually `Unallocated`, but a shipment that moved on in those seconds sends its newer status. One of: `Unallocated`, `FindingDriver`, `DriverAllocated`, `EnrouteToPickup`, `ArrivedAtPickup`, `EnrouteToDelivery`, `ArrivedAtDelivery`, `Completed`, `Cancelled`.

## Envelope

Mothership sends a `POST` with this JSON body. The envelope is the same on every event, and `data` holds the keys above.

- `eventType` (string): The event. Always `shipment.purchased` here. Route on it, and answer `2xx` to types you don't handle.
- `sentAt` (string): When Mothership queued the event to send, as an ISO 8601 string in UTC. Every retry and resend carries the same value, so it does not say when this attempt went out.
- `deliveryAttempt` (integer): Which send of this event this is, starting at `1`. Resends from the dashboard count too.
- `pendingRetries` (integer): How many automatic attempts are left if this one fails. `0` on the last one.

## Example request

```json Example body
{
  "eventType": "shipment.purchased",
  "data": {
    "createdAt": "2026-10-08T15:03:12.481Z",
    "delivery": {
      "accessorials": [],
      "city": "Los Angeles",
      "closeTime": "1700",
      "coordinates": {
        "latitude": 34.0136514,
        "longitude": -118.3738708
      },
      "emails": [
        "receiving@example.com"
      ],
      "name": "Delivery Company Name",
      "openTime": "0900",
      "phoneNumber": "+13103329380",
      "placeId": "ChIJ8ZzvEBy6woARqY2BXgf4C2c",
      "state": "CA",
      "street": "3900 S La Cienega Blvd",
      "subStreet": "Suite A",
      "zip": "90056"
    },
    "earliestPickupDate": "2026-10-09T08:00:00-07:00",
    "estimatedDeliveryDate": "2026-10-09T17:00:00-07:00",
    "freight": [
      {
        "description": "Boxed auto parts",
        "height": 60,
        "length": 48,
        "quantity": 2,
        "type": "Pallet",
        "weight": 450,
        "width": 40
      }
    ],
    "pickup": {
      "accessorials": [
        "liftgate"
      ],
      "city": "Los Angeles",
      "closeTime": "1900",
      "coordinates": {
        "latitude": 34.0615517,
        "longitude": -118.3536391
      },
      "emails": [],
      "name": "Pickup Company Name",
      "openTime": "0900",
      "phoneNumber": "+12133293311",
      "placeId": "ChIJr8ZJ4C-5woARC5xDOyEHvzQ",
      "state": "CA",
      "street": "5600 Wilshire Blvd",
      "zip": "90036"
    },
    "price": 312.48,
    "shipmentId": "MS123456",
    "status": "Unallocated"
  },
  "sentAt": "2026-10-08T15:04:05.000Z",
  "deliveryAttempt": 1,
  "pendingRetries": 16
}
```