# Create a shipment

`POST https://api.mothership.com/beta/shipments`

Sandbox: `https://sandbox.api.mothership.com/beta/shipments`

Purchases a quoted rate and creates the shipment under your shipper account.

Purchasing a shipment will use the default payment source that the user's organization has on file. The payment source can be changed by logging in to the customer dashboard and updating the payment information in the organization's settings.

If the quote is missing details needed for purchase, the request fails with `QUOTE_NOT_PURCHASABLE` and `metadata.invalidFieldsRequiredForPurchase` lists them. A payment problem fails with `402 PAYMENT_FAILED`. See [Error handling](https://developers.mothership.com/reference/error-handling).

> [!NOTE] Rate limit
> Shipment creation is limited to 100 requests per minute. See [Rate limiting](https://developers.mothership.com/reference/rate-limiting).

## Authorization

Send your API token as a Bearer token: `Authorization: Bearer <token>`.

## Request body

- `quoteId` (string, required): ID of the quote to purchase and turn into a shipment, from Create a quote.
- `rateId` (string, required): ID of the rate to purchase. It must be one of the rates returned in the quote for `quoteId`.

## Responses

### 201

The created shipment, inside `data`.

- `data` (object, required)
  - `id` (string, required): ID of the created shipment.
  - `createdAt` (string<date-time>, required): When the shipment was created, as an ISO 8601 date-time.
  - `price` (number, required): Price paid, in USD, for the shipment.
  - `earliestPickupDate` (string<date-time>, required): Earliest pickup time for this shipment, as an ISO 8601 date-time.
  - `estimatedDeliveryDate` (string<date-time>, required): Estimated latest delivery time for this shipment, as an ISO 8601 date-time.
  - `freight` (array of objects, required, min items 1): The freight, one array element per line item.
    - `quantity` (number, required): Quantity of this cargo line item.
    - `type` (string, required): Type of this cargo. Can be: Bag, Bale, Box, Bucket, Bundle, Can, Carton, Case, Coil, Crate, Cylinder, Drum, Pail, Pallet, Pieces, Reel, Roll, Skid, Tote, or Tube. LooseItem has been deprecated in favor of Pieces. One of: `Bag`, `Bale`, `Box`, `Bucket`, `Bundle`, `Can`, `Carton`, `Case`, `Coil`, `Crate`, `Cylinder`, `Drum`, `Pail`, `Pallet`, `Pieces`, `Reel`, `Roll`, `Skid`, `Tote`, `Tube`.
    - `weight` (integer, required, min 1): Weight of each item in this line item, in pounds. For example, a 1,600 lb shipment of 4 pallets at 400 lb each has a `weight` of 400.
    - `length` (integer, required, min 1): Length of each item in this line item, in inches.
    - `width` (integer, required, min 1): Width of each item in this line item, in inches.
    - `height` (integer, required, min 1): Height of each item in this line item, in inches.
    - `description` (string, optional): Cargo description of this line item.
    - `nmfcCode` (string, optional, pattern ^\d{3,10}(?:-\d{1,3})?$): NMFC code for this line item, as a 3-10 digit article number with an optional 1-3 digit sub-item suffix. For example: 156600 or 156600-03.
    - `freightClass` (string, optional): Freight class for this line item. When provided, this is the class used to rate the shipment -- it overrides our density-based classification, so you are responsible for its accuracy and the carrier may reclassify and adjust charges if it is incorrect. Omit this field to have the freight class calculated from the dimensions and weight you supply. One of: `50`, `55`, `60`, `65`, `70`, `77.5`, `85`, `92.5`, `100`, `110`, `125`, `150`, `175`, `200`, `250`, `300`, `400`, `500`.
    - `pieceCount` (integer, optional, min 1): Number of pieces in each handling unit, printed on the bill of lading. For example, for 4 pallets of 5 cartons each, set `pieceCount` to 5 and `quantity` to 4.
    - `pieceType` (string, optional): Packaging of the pieces inside each handling unit. Can be: Bag, Barrel, Bolt, Box, Canister, Carton, Case, Container, Crate, Cylinder, Pieces, Roll, or Tube. This is usually different from the cargo type: 4 pallets each holding 5 cartons is type Pallet, quantity 4, pieceType Carton, pieceCount 5. One of: `Bag`, `Barrel`, `Bolt`, `Box`, `Canister`, `Carton`, `Case`, `Container`, `Crate`, `Cylinder`, `Pieces`, `Roll`, `Tube`.
  - `pickup` (object, required): Pickup location of the shipment.
    - `city` (string, required): City.
    - `state` (string, required): Two-letter state abbreviation.
    - `zip` (string, required): ZIP code.
    - `placeId` (string, required, deprecated): Deprecated: use the `address` parameter instead. A place ID from the Fetch Places endpoint.
    - `accessorials` (array of strings, required, default [], unique items): Accessorials required at this location. One of: `alcohol`, `appointment`, `cfs`, `crossDock`, `hazmat`, `homeDelivery`, `inside`, `liftgate`, `limitedAccess`, `localInsideDelivery`, `notifyBeforeArrival`, `residential`, `scheduledDelivery`, `sortSeg`, `tobacco`, `tradeshow`, `twicRequired`.
    - `emails` (array of strings, required, default [], unique items): Email addresses that receive notification emails.
    - `openTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location opens, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 0900 for 9:00am local time.
    - `closeTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location closes, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 2200 for 10:00pm local time.
    - `name` (string, optional): Business or company name.
    - `street` (string, optional): Street address.
    - `subStreet` (string, optional, deprecated): Second address line, such as a suite number or letter. Deprecated: send it in the `address` field instead.
    - `timezone` (string, optional): IANA timezone of the location, such as America/Los_Angeles. Use it to convert the location's open and close times, and the shipment's UTC timestamps, to local time.
    - `phoneNumber` (string, optional): Contact phone number at this location, in E.164 format. For example: +17148130000.
    - `referenceNumber` (string, optional): Reference number for this location.
    - `notes` (string, optional): Notes for this location.
  - `delivery` (object, required): Delivery location of the shipment.
    - `city` (string, required): City.
    - `state` (string, required): Two-letter state abbreviation.
    - `zip` (string, required): ZIP code.
    - `placeId` (string, required, deprecated): Deprecated: use the `address` parameter instead. A place ID from the Fetch Places endpoint.
    - `accessorials` (array of strings, required, default [], unique items): Accessorials required at this location. One of: `alcohol`, `appointment`, `cfs`, `crossDock`, `hazmat`, `homeDelivery`, `inside`, `liftgate`, `limitedAccess`, `localInsideDelivery`, `notifyBeforeArrival`, `residential`, `scheduledDelivery`, `sortSeg`, `tobacco`, `tradeshow`, `twicRequired`.
    - `emails` (array of strings, required, default [], unique items): Email addresses that receive notification emails.
    - `openTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location opens, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 0900 for 9:00am local time.
    - `closeTime` (string, required, 4 characters, pattern ^[0-9]{4}$): When this location closes, as 4-digit 24-hour time (HHmm) in the location's timezone. Whole hours, with no minutes, are recommended. For example: 2200 for 10:00pm local time.
    - `name` (string, optional): Business or company name.
    - `street` (string, optional): Street address.
    - `subStreet` (string, optional, deprecated): Second address line, such as a suite number or letter. Deprecated: send it in the `address` field instead.
    - `timezone` (string, optional): IANA timezone of the location, such as America/Los_Angeles. Use it to convert the location's open and close times, and the shipment's UTC timestamps, to local time.
    - `phoneNumber` (string, optional): Contact phone number at this location, in E.164 format. For example: +17148130000.
    - `referenceNumber` (string, optional): Reference number for this location.
    - `notes` (string, optional): Notes for this location.
  - `status` (string, optional): Current status of the shipment.
  - `trackingUrl` (string, optional): Tracking URL for the shipment.

### 429

You've created too many shipments in a short period of time.

- `code` (number, required) One of: `100`, `101`, `200`, `201`, `202`, `203`, `204`, `205`, `206`, `300`, `301`, `302`, `303`, `304`, `305`, `307`, `400`, `401`, `402`, `403`, `404`, `405`, `406`, `407`, `408`, `409`, `410`, `411`, `412`, `413`, `414`, `415`, `416`, `417`, `422`, `429`, `500`, `501`, `502`, `503`, `504`, `505`.
- `type` (string, required) One of: `UNKNOWN`, `NOT_FOUND`, `SERVER_ERROR`, `UNAUTHENTICATED`, `MISSING_PERMISSION`, `INVALID_REQUEST`, `RATE_LIMIT_EXCEEDED`, `CARGO_TOO_LARGE`, `NO_RATES_FOUND`, `QUOTE_NOT_PURCHASABLE`, `PAYMENT_REQUIRED`, `PAYMENT_FAILED`.
- `message` (string, required)
- `metadata` (object, optional)

## Example request

```bash
curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/shipments' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "quoteId": "-LaLqLBycik7COnRuq5P",
  "rateId": "G6EMET"
}'
```

## Example response (201)

```json
{
  "data": {
    "id": "MS5016101",
    "createdAt": "2025-01-28T23:09:53.149Z",
    "trackingUrl": "https://dashboard.mothership.com/track/MS5016101",
    "status": "Unallocated",
    "price": 87.67,
    "earliestPickupDate": "2025-01-29T16:00:00.000Z",
    "estimatedDeliveryDate": "2025-01-30T01:00:00.000Z",
    "freight": [
      {
        "quantity": 2,
        "type": "Pallet",
        "weight": 50,
        "length": 48,
        "width": 42,
        "height": 46,
        "description": "T-shirts"
      }
    ],
    "pickup": {
      "placeId": "a3039151-6857-4659-bd8b-c0fce5e30a36",
      "name": "Griffith Observatory",
      "street": "2800 East Observatory Road",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90027",
      "timezone": "America/Los_Angeles",
      "accessorials": ["liftgate"],
      "phoneNumber": "+15555555555",
      "openTime": "0800",
      "closeTime": "1700",
      "emails": ["logistics@mothership.com"]
    },
    "delivery": {
      "placeId": "1dfbde69-bf4e-48e0-9c4b-5699f8f35646",
      "name": "LACMA",
      "street": "5905 Wilshire Boulevard",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90036",
      "timezone": "America/Los_Angeles",
      "accessorials": ["liftgate", "residential"],
      "phoneNumber": "+15555555555",
      "openTime": "1000",
      "closeTime": "2200",
      "emails": []
    }
  }
}
```