Request a Spot Quote

This API endpoint allows to obtain a spot price quote for a freight shipment. Spot quotes are typically discounted rates based on excess carrier capacity vs contractual rates. The carrier will return the service level they are able to offer as opposed to specifying the desired service level in the request.

The quote_id returned by the carrier must be supplied when scheduling a pickup for your shipment. The quote ID will be included on the BOL you give to the carrier at the time of pickup, allowing them to match the shipment to the original quote and invoice it correctly.

Info

Note about Spot Quotes

Spot quotes can expire. If the quote has expired at the time of pickup a new spot quote will need to be created.

Carrier IDs

Each of your LTL carriers has a unique carrier_id in ShipEngine. You can use this carrier_id for many ShipEngine endpoints to indicate which account to use. You can find carrier_ids from the List Connected Carriers endpoint. You will need to pass the carrier_id to create a spot quote from a single carrier.

Request Body

The following table lists the parameters required for this endpoint.

Name Type Required Description
pickup Pickup Object The shipment date of the quote.
packages Packages Object Information about the physical freight being sent.
shipment_measurements Shipment Measurements Object The dimensions and weight consumed by the shipment once loaded in the trailer.
options Options Object The accessorial services required for pickup.
ship_from Ship From Object The address and contact details for the location where freight will be picked up.
ship_to Ship to Object The address and contact details for the location where the freight will be sent.
bill_to Bill To Object The address and contact details for the billing contact.
requested_by Requested By Object The name and contact details for the company making the request.

Info

Parameter Objects

The following tables describe the objects and properties listed above.


Pickup Object

This object represents the shipment date for the quote.

Name Type Required Description Format
date string The shipment date represented in the quote. Date Format: YYYY-MM-DD

Packages Object

This object represents the physical freight that you are shipping. LTL shipments are typically packed in containers such as pallets, skids, or oversized boxes. Your LTL carrier will typically refer to these as container types. These special container types are referred to as packages in ShipEngine API to streamline the terminology used across different types of shipping carriers.

Name Type Required Description
code string The code for this package type.
freight_class number The NMFC freight class for your freight.
nmfc_code string The NMFC commodity code / item number.
description string The description of the item(s) in this container.
dimensions Dimensions Object The dimensions of the package.
weight Weight Object The weight of the package.
quantity number The number of packages of this type.
stackable boolean Indicates whether or not this package can be safely stacked.
hazardous_materials boolean Indicates whether or not the package contains hazardous materials.

Dimensions Object

This object represents the physical dimensions of the package.

Name Type Required Description
width number The value of the width of the package.
height number The value of the height of the package.
length number The value of the length of the package.
unit string The unit of measure for the dimensions. Valid values include inches and centimeters

Weight Object

This object represents the weight of the package.

Name Type Required Description
value number The value of the weight of the package.
unit string The unit of measure of the weight. Valid values include grams, kilograms, ounces, and pounds.

Shipment Measurements Object

This object represents the dimensions and weight consumed by the shipment once loaded in the trailer

Name Type Required Description
total_linear_length Total Linear Length Object The total linear length of the shipment as it will be loaded into the trailer, calculated based on the length of an individual container, factoring in whether containers can be stacked and/or fit widthwise in the trailer.
total_width Total Width Object The total width of the shipment configuration as it will be loaded into the trailer.
total_height Total Height Object The total height of the shipment configuration as it will be loaded into the trailer.
total_weight Total Weight Object The total weight of the shipment configuration as it will be loaded into the trailer.

Total Linear Length / Total Width / Total Height Object

These objects represent the linear length, width, and height of the shipment once loaded in the trailer.
Name Type Required Description
value number The value of the linear length of the shipment.
unit string The unit of measure of the linear length. Valid values include inches, and centimeters.

Total Weight Object

This object represents the weight of the shipment once loaded in the trailer.

Name Type Required Description
value number The value of the weight of the shipment.
unit string The unit of measure of the weight. Valid values include grams, kilograms, ounces, and pounds.

Options Object

This object represents the optional accessorial services you require for this pickup. For example, does this pickup require a lift gate on the trailer? These extra services are referred to as options in ShipEngine API to streamline the terminology used across different types of shipping carriers. Refer to the accessorial services for the carrier to get the required attributes for your selected service.

Name Type Required Description
code string The carrier's code for this service option.
attributes object Optional attributes required by the carrier for this service.

Ship From / Ship To Object

This object represents the address and contact information needed for the Ship From and Ship To properties.
Name Type Required Description
address Address Object The address of the location.
contact Contact Object The information for the contact person.

Bill To Object

This object represents the billing information for this pickup.

Name Type Required Description
type string The type of billing. Valid values include consignee, shipper, or third_party.
payment_terms string The payment terms. Valid values include collect, prepaid, or third_party.
account string The account number to bill for this pickup.
address Address Object The address of the location.
contact Contact Object The information for the contact person.

Requested By Object

This object represents the requester of this pickup.

Name Type Required Description
company_name string Name of the company making the pickup request.
contact Contact Object The information for the contact person.

Address and Contact Objects

This object represents Address and Contact information.

Address Object

name type Required Description
company_name string The name of the company associated with this address.
address_line1 string The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
address_line2 string The second line of the street address. For some addresses, this line may not be needed.
address_line3 string The third line of the street address. For some addresses, this line may not be needed.
city_locality string The city or locality of the shipment address.
state_province string The state or province of the shipment address.
postal_code string The postal code of the shipment address.
country_code string The two letter ISO 3166-1 alpha-2 country code.
residential boolean Indicates whether or not this is a residential address. Defaults to false.

Contact Object

name type Required Description
name string The name of the contact.
phone_number string The phone number of the contact.
email string The email address of the contact.

Example Request

POST /v-beta/ltl/spot-quotes/:carrier_id

POST /v-beta/ltl/spot-quotes/car_NJuhsfkKkuxChJNtX6X5kJKKY7" HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "pickup": {
    "date": "2021-06-01"
  },
  "packages": [
    {
      "code": "PKG",
      "freight_class": 60,
      "nmfc_code": "161630",
      "description": "Paperback books",
      "dimensions": {
        "width": 40,
        "height": 40,
        "length": 48,
        "unit": "inches"
      },
      "weight": {
        "value": 1500,
        "unit": "pounds"
      },
      "quantity": 3,
      "stackable": false,
      "hazardous_materials": false
    }
  ],
  "shipment_measurements": {
    "total_linear_length": {
      "value": 48,
      "unit": "inches"
    },
    "total_width": {
      "value": 48,
      "unit": "inches"
    },
    "total_height": {
      "value": 48,
      "unit": "inches"
    }
  },
  "options": [
    {
      "code": "LFTP"
    },
    {
      "code": "HAZ",
      "attributes": {
        "name": "Contact Person",
        "phone": "7704865900"
      }
    }
  ],
  "ship_from": {
    "account": "123456",
    "address": {
      "company_name": "Example Corp.",
      "address_line1": "4009 Marathon Blvd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US"
    }
  },
  "ship_to": {
    "account": "123456",
    "address": {
      "company_name": "Widget Company",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US"
    }
  },
  "bill_to": {
    "type": "third_party",
    "payment_terms": "prepaid",
    "account": "123456",
    "address": {
      "company_name": "Example Corp.",
      "address_line1": "4009 Marathon Blvd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US"
    },
    "contact": {
      "name": "John Doe",
      "phone_number": "111-111-1111",
      "email": "[email protected]"
    }
  },
  "requested_by": {
    "company_name": "Example Corp.",
    "contact": {
      "name": "John Doe",
      "phone_number": "111-111-1111",
      "email": "[email protected]"
    }
  }
}

Example Response

{
  "quotes": [
    {
      "quote_id": "qte_EMonWSbhSVkkGryX4d1JN4KYrR5w5s",
      "effective": {
        "date": "2021-12-31"
      },
      "expiration": {
        "date": "2022-01-07"
      },
      "service": {
        "carrier_description": "Standard Volume"
      },
      "pickup": {
        "date": "2021-12-31"
      },
      "delivery": {
        "estimated": {
          "days": 6
        }
      },
      "charges": [
        {
          "type": "accessorial",
          "description": "Inside delivery",
          "amount": {
            "value": "50.00",
            "currency": "USD"
          }
        },
        {
          "type": "accessorial",
          "description": "Inside pickup",
          "amount": {
            "value": "50.00",
            "currency": "USD"
          }
        },
        {
          "type": "accessorial",
          "description": "Lift gate required at delivery",
          "amount": {
            "value": "50.00",
            "currency": "USD"
          }
        },
        {
          "type": "accessorial",
          "description": "Fuel Surcharge",
          "amount": {
            "value": "70.88",
            "currency": "USD"
          }
        },
        {
          "type": "total",
          "description": "The freight charge including accessorials and/or discounts",
          "amount": {
            "value": "895.92",
            "currency": "USD"
          }
        }
      ]
    }
  ]
}