# Create a quote

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

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

Creates a quote from the shipment details you send. The response lists the available rates with their prices, and a quote ID to use with Create a shipment.

## Purchasable metadata

In the response, there is a `metadata` field that indicates if the given quote is purchasable or if it is missing any required fields.

We require minimal information for creating quotes (such as only providing zip codes for locations or leaving out contact phone numbers). However, in order to actually book a shipment, we must have a specific location, a description of the freight, and valid contact information for both the pickup and delivery locations. `metadata.invalidFieldsRequiredForPurchase` lists each missing or invalid field with an `errorMessage`.

## Rates

Each rate has an `id` to pass to [Create a shipment](https://developers.mothership.com/reference/createshipment) along with the quote's `id`. See [Rate services](https://developers.mothership.com/reference/rate-services) for the values in `services` and [Providers](https://developers.mothership.com/reference/providers) for `provider` and `providerScac`. The quote stops being purchasable at `expiresAt`.

Carriers respond at different speeds. `rateResponseTimeoutMs` sets how long to wait for rates, 25 seconds by default. A shorter wait can return fewer rates.

> [!NOTE] Rate limit
> Quote creation has its own limit: 100 per minute until your organization has created 500 quotes, then 10 per minute until four hours after the first of them. See [Rate limiting](https://developers.mothership.com/reference/rate-limiting).

## Authorization

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

## Request body

- `pickup` (object, required): The pickup (shipper) location. Must include an `address` object.
  - `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, min length 2): Business or company name.
  - `accessorials` (array of strings, optional, 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`.
  - `phoneNumber` (string, optional): Contact phone number at this location, in E.164 format. For example: +17148130000.
  - `emails` (array of strings, optional, default [], unique items): Email addresses that receive notification emails.
  - `referenceNumber` (string, optional): Reference number for this location.
  - `notes` (string, optional): Notes for this location.
  - `address` (object, optional): Address of this location.
    - `zip` (string, required): ZIP code.
    - `street` (string, optional): Street address.
    - `subStreet` (string, optional): Second address line, such as a suite number or letter.
    - `city` (string, optional): City.
    - `state` (string, optional): Two-letter state abbreviation.
- `delivery` (object, required): The delivery (consignee) location. Must include an `address` object.
  - `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, min length 2): Business or company name.
  - `accessorials` (array of strings, optional, 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`.
  - `phoneNumber` (string, optional): Contact phone number at this location, in E.164 format. For example: +17148130000.
  - `emails` (array of strings, optional, default [], unique items): Email addresses that receive notification emails.
  - `referenceNumber` (string, optional): Reference number for this location.
  - `notes` (string, optional): Notes for this location.
  - `address` (object, optional): Address of this location.
    - `zip` (string, required): ZIP code.
    - `street` (string, optional): Street address.
    - `subStreet` (string, optional): Second address line, such as a suite number or letter.
    - `city` (string, optional): City.
    - `state` (string, optional): Two-letter state abbreviation.
  - `appointmentContact` (object, optional): Another contact to schedule delivery with, when the consignee is not the one scheduling it. Only used with the `scheduledDelivery` accessorial.
    - `email` (string, required): Contact email to receive consignee scheduling notifications.
    - `phoneNumber` (string, required): Contact phone number in E.164 format. For example: +17148130000.
- `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`.
- `pickupReadyDate` (string<date-time> or object, required): When the shipment will be ready for pickup: an object with `date` as "YYYY-MM-DD" and `time` in 24-hour format, such as "0900". For example: {"date": "2024-01-30", "time": "0900"}.
- `rateResponseTimeoutMs` (number, optional, default 25000, min 5000): How long to wait for rates, in milliseconds. Defaults to 25000. Some carriers take longer than others to return rates, so a lower value can return fewer rates. Platforms with strict timeouts, such as Shopify, may need a lower value. Use with caution. - If you are unsure, leave this field out. - If rates are missing, try a higher value. - This is the time spent retrieving rates. If you have a hard limit on how long to wait for a response, set a timeout on the request itself. If set, the minimum is 5000 (5 seconds).
- `applyAvailableCredits` (boolean, optional, default true): Set to false to keep the shipper account's available credits off this quote.
- `declaredFreightValue` (integer, optional, min 101, max 250000): Declared freight value in USD. Setting it adds Freight Protect to your quote. Leave it out to rely on the carrier's default insurance coverage.

## Responses

### 201

The created quote, inside `data`.

- `data` (object, required)
  - `id` (string, required): Quote ID to use with Create a shipment.
  - `expiresAt` (string<date-time>, required): When this quote expires and can no longer be used with Create a shipment, as an ISO 8601 date-time.
  - `rates` (array of objects, required, min items 1): Rates available to purchase. Pass the one you want, with the quote ID, to Create a shipment.
    - `id` (string, required)
    - `price` (number, required): Price of the rate in USD.
    - `transitDays` (object, required): Range of transit days.
      - `minimum` (number, required, min 0)
      - `maximum` (number, required, min 0)
    - `estimatedPickupDate` (string<date-time>, required): Estimated 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.
    - `provider` (string, required): The shipping provider for this rate. One of: `mothership`, `abf`, `centralTransport`, `customCompanies`, `daylight`, `echoGlobalLogistics`, `forwardAir`, `frontline`, `oldDominion`, `roadrunner`, `saia`, `southeastern`, `tforce`, `ups`, `ward`, `xpo`, `conway`, `partner`.
    - `providerScac` (string, required): The shipping provider for this rate. One of: `mhpg`, `abfs`, `ctii`, `ctbv`, `dylt`, `echs`, `fwdn`, `fcsy`, `odfl`, `rdfs`, `saia`, `sefl`, `tfin`, `upgf`, `ward`, `xpol`, `cnwy`, `partner`.
    - `services` (array of strings, required, default []): Services included in this rate. One of: `dedicated`, `teamDrive`, `custom`, `standard`, `guaranteed`, `guaranteed08`, `guaranteed09`, `guaranteed10`, `guaranteed11`, `guaranteed12`, `guaranteed14`, `guaranteed15`, `guaranteed1530`, `expedited`, `expedited12`, `expedited17`, `accelerated`, `guaranteedWithinWindow`, `guaranteedMultiHourWindow`, `guaranteedSingleHourWindow`, `capacityLoad`, `unknown`.
    - `warnings` (array of strings, required, default []): Warnings for this rate. One of: `consolidator`.
    - `creditsApplied` (number, required): Credit applied to this rate, in USD.
    - `coveragePrice` (number, required): Price of the insurance coverage in USD.
    - `coveredValue` (integer, required): Freight's value covered by insurance in USD.
    - `truck` (object, optional, deprecated): Deprecated. The truck equipment and specialty for this rate. It is often unknown at purchase time, so ignore it.
      - `equipment` (string, required) One of: `any`, `straightTruck`, `tractor`.
      - `specialty` (string, required) One of: `reefer`, `flatbed`, `dryVan`.
    - `serviceType` (string, optional, deprecated): Service type is deprecated in favor of services. Please use those instead. This will often be returned as "other". One of: `nextDay`, `sameDay`, `customRate`, `limitedAccessRegional`, `lowest`, `bestValue`, `fastest`, `flatbed`, `reefer`, `other`.
  - `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)
    - `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.
    - `city` (string, optional): City.
    - `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.
    - `timezone` (string, optional): IANA timezone of the location, such as America/Los_Angeles. Use it to convert the location's open and close times to local time.
  - `delivery` (object, required)
    - `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.
    - `city` (string, optional): City.
    - `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.
    - `timezone` (string, optional): IANA timezone of the location, such as America/Los_Angeles. Use it to convert the location's open and close times to local time.
  - `metadata` (object, required)
    - `purchasable` (boolean, required): If true, the quote ID can be used with Create a shipment. If false, this Create a quote call needs the properties listed in `invalidFieldsRequiredForPurchase` before its quote ID can be used.
    - `invalidFieldsRequiredForPurchase` (array of objects, required, default []): Fields this call still needs before its quote ID can be used with Create a shipment.
      - `errorMessage` (string, required)
      - `field` (string, optional)
    - `pickupLocationSuggestedAccessorials` (array of strings, required, default [], unique items): Accessorials suggested for the pickup location. One of: `alcohol`, `appointment`, `cfs`, `crossDock`, `hazmat`, `homeDelivery`, `inside`, `liftgate`, `limitedAccess`, `localInsideDelivery`, `notifyBeforeArrival`, `residential`, `scheduledDelivery`, `sortSeg`, `tobacco`, `tradeshow`, `twicRequired`.
    - `deliveryLocationSuggestedAccessorials` (array of strings, required, default [], unique items): Accessorials suggested for the delivery location. One of: `alcohol`, `appointment`, `cfs`, `crossDock`, `hazmat`, `homeDelivery`, `inside`, `liftgate`, `limitedAccess`, `localInsideDelivery`, `notifyBeforeArrival`, `residential`, `scheduledDelivery`, `sortSeg`, `tobacco`, `tradeshow`, `twicRequired`.

### 429

You've created too many quotes 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/quotes' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "freight": [
    {
      "quantity": 2,
      "type": "Pallet",
      "weight": 50,
      "length": 48,
      "width": 42,
      "height": 46,
      "description": "T-shirts"
    }
  ],
  "pickup": {
    "name": "Griffith Observatory",
    "address": {
      "street": "2800 E Observatory Rd",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90027"
    },
    "accessorials": [
      "liftgate"
    ],
    "phoneNumber": "+15555555555",
    "emails": [
      "logistics@mothership.com"
    ],
    "openTime": "1000",
    "closeTime": "2200"
  },
  "delivery": {
    "name": "LACMA",
    "address": {
      "street": "5905 Wilshire Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90036"
    },
    "accessorials": [
      "liftgate",
      "residential"
    ],
    "phoneNumber": "+15555555555",
    "emails": [
      "logistics@mothership.com"
    ],
    "openTime": "1100",
    "closeTime": "1700"
  },
  "pickupReadyDate": {
    "date": "2024-10-15",
    "time": "1000"
  }
}'
```

## Example response (201)

```json
{
  "data": {
    "id": "-LawNN52lCcvj6T5qiEp",
    "expiresAt": "2019-03-26T23:51:40.485Z",
    "rates": [
      {
        "id": "VDWLA0",
        "creditsApplied": 0,
        "estimatedPickupDate": "2019-03-26T23:45:40.000Z",
        "estimatedDeliveryDate": "2019-03-28T05:00:40.000Z",
        "price": 79,
        "provider": "mothership",
        "providerScac": "mhpg",
        "services": [],
        "transitDays": {
          "minimum": 1,
          "maximum": 1
        },
        "warnings": [],
        "coveragePrice": 0,
        "coveredValue": 0
      },
      {
        "id": "G6EMET",
        "creditsApplied": 0,
        "estimatedPickupDate": "2019-03-26T23:45:40.000Z",
        "estimatedDeliveryDate": "2019-03-27T05:00:40.000Z",
        "price": 108,
        "provider": "mothership",
        "providerScac": "mhpg",
        "services": ["guaranteed"],
        "transitDays": {
          "minimum": 0,
          "maximum": 0
        },
        "warnings": [],
        "coveragePrice": 0,
        "coveredValue": 0
      }
    ],
    "freight": [
      {
        "quantity": 2,
        "type": "Pallet",
        "weight": 50,
        "length": 48,
        "width": 42,
        "height": 46,
        "description": "T-shirts"
      }
    ],
    "pickup": {
      "placeId": "ChIJywjU6WG_woAR3NrWwrEH_3M",
      "name": "Griffith Observatory",
      "street": "2800 East Observatory Road",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90027",
      "timezone": "America/Los_Angeles",
      "accessorials": ["liftgate"],
      "phoneNumber": "+15555555555",
      "openTime": "1000",
      "closeTime": "2200",
      "emails": ["logistics@mothership.com"]
    },
    "delivery": {
      "placeId": "ChIJsXqcyjy5woARNz6sOh0ZmwA",
      "name": "LACMA",
      "street": "5905 Wilshire Boulevard",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90036",
      "timezone": "America/Los_Angeles",
      "accessorials": ["liftgate", "residential"],
      "phoneNumber": "+15555555555",
      "openTime": "1100",
      "closeTime": "1700",
      "emails": ["logistics@mothership.com"]
    },
    "metadata": {
      "purchasable": true,
      "invalidFieldsRequiredForPurchase": [],
      "pickupLocationSuggestedAccessorials": [],
      "deliveryLocationSuggestedAccessorials": []
    }
  }
}
```