Skip to content
MothershipDevelopers

API referenceQuotes

Create a quote

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.

POST/quotes
Environment
https://sandbox.api.mothership.com/beta
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"
  }
}'
Reads your token from $MOTHERSHIP_API_TOKEN
Response
{
: {
: "-LawNN52lCcvj6T5qiEp",
: "2019-03-26T23:51:40.485Z",
: [
{
: "VDWLA0",
: 0,
: "2019-03-26T23:45:40.000Z",
: "2019-03-28T05:00:40.000Z",
: 79,
: "mothership",
: "mhpg",
: [],
: ,2 keys
: [],
: 0,
: 0
},
{
: "G6EMET",
: 0,
: "2019-03-26T23:45:40.000Z",
: "2019-03-27T05:00:40.000Z",
: 108,
: "mothership",
: "mhpg",
: ,1 item
: ,2 keys
: [],
: 0,
: 0
}
],
: [
{
: 2,
: "Pallet",
: 50,
: 48,
: 42,
: 46,
: "T-shirts"
}
],
: {
: "ChIJywjU6WG_woAR3NrWwrEH_3M",
: "Griffith Observatory",
: "2800 East Observatory Road",
: "Los Angeles",
: "CA",
: "90027",
: "America/Los_Angeles",
: [
"liftgate"
],
: "+15555555555",
: "1000",
: "2200",
: [
"logistics@mothership.com"
]
},
: {
: "ChIJsXqcyjy5woARNz6sOh0ZmwA",
: "LACMA",
: "5905 Wilshire Boulevard",
: "Los Angeles",
: "CA",
: "90036",
: "America/Los_Angeles",
: [
"liftgate",
"residential"
],
: "+15555555555",
: "1100",
: "1700",
: [
"logistics@mothership.com"
]
},
: {
: true,
: [],
: [],
: []
}
}
}

Hover a key to see what it means. Click it to jump to the field.

Build a quote request

Change the shipment and the code samples, Try it and the spec check update as you type.

Pickup
Accessorials
Liftgate
Delivery
Accessorials
LiftgateResidential

Freight

QtyTypeLb eachL × W × H, inchesDescriptionRemove

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 along with the quote's id. See Rate services for the values in services and 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.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Request body

application/json · required
  • pickupobjectRequired

    The pickup (shipper) location. Must include an address object.

  • deliveryobjectRequired

    The delivery (consignee) location. Must include an address object.

  • freightarray of objectsRequired

    The freight, one array element per line item.

    min items 1
  • pickupReadyDatestring<date-time> or objectRequired

    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"}

  • rateResponseTimeoutMsnumber

    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).

    Defaults to 25000min 5000
  • applyAvailableCreditsboolean

    Set to false to keep the shipper account's available credits off this quote.

    Defaults to true
  • declaredFreightValueinteger

    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.

    min 101max 250000

Responses

    • dataobjectRequired
      • idstringRequired

        Quote ID to use with Create a shipment.

      • expiresAtstring<date-time>Required

        When this quote expires and can no longer be used with Create a shipment, as an ISO 8601 date-time.

      • ratesarray of objectsRequired

        Rates available to purchase. Pass the one you want, with the quote ID, to Create a shipment.

        min items 1
      • freightarray of objectsRequired

        The freight, one array element per line item.

        min items 1
      • pickupobjectRequired
      • deliveryobjectRequired
      • metadataobjectRequired

What's next

POSTCreate a shipment

Book one of the rates: send data.id as quoteId and that rate’s id as rateId.

Providers

See which carrier each rate’s provider and providerScac name.