Request a Spot Quote

This API endpoint allows you to obtain a spot price quote for a 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.

Carrier IDs

Each of your LTL carriers has a unique carrier_id in ShipEngine. You can use this id for many ShipEngine endpoints to indicate which account to use and it can be found on the List Connected Carriers endpoint page. You will need to pass the carrier_id in the request URL to create a spot-quote from a single carrier.

Request Body

ShipEngine requires requests be made in the JSON format. To see a sample of a full request, see the Example Request section below.

Name	Type	Required	Description
`shipment`	Shipment Object	✔	This object wraps shipment information requried by the carrier to generate a quote.
`shipment_measurements`	Shipment Measurements Object	✔	The dimensions and weight consumed by the shipment once loaded in the trailer.

Shipment Object

When you create a quote or spot-quote, the request is wrapped in a shipment object. Shipments are the gatekeeper to more advanced functionality inside ShipEngine.

The following table lists the parameters required inside of the shipment object for this endpoint.

Name	Type	Required	Description
`pickup_date`	string	✔	The shipment date of the quote. Date Format: YYYY-MM-DD
`packages[]`	Package Object	✔	An array of objects containing information about the physical freight being sent.
`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.

Package 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 / Width / 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 and Ship To Object

This object represents the address and contact information needed for the Ship From and Ship To properties.

Name	Type	Required	Description
`account`	string		Optional account number may be included.
`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.

Response Body

The response will return an array of quotes, one for each connected carrier. Each quote will include the information in the following table. To see a sample of a full response, see the Example Response section below.

Name	Type	Required	Description
`quotes`	Quotes Object	✔	This optional field contains a warning code and message if provided by the carrier.
`warning[]`	Warning Object	✔	This is an array of warning codes and messages if provided by the carrier.

Quotes Object

Name	Type	Required	Description
`carrier_message`	string		This optional field contains contains a message about the quote if provided by the carrier.
`charges[]`	Charge Object	✔	An array of objects containing an itemized breakdown of the charges for the quote.
`effective_date`	string		The date that the quote becomes active. This is provided if supported by the carrier. Format: YYYY-MM-DD.
`estimated_delivery_days`	number		This number represents the estimated number of days between pickup and delivery if provided by the carrier.
`expiration_date`	string		Quote expiration information if supported by the carrier in format YYYY-MM-DD
`pickup_date`	string	✔	This is the scheduled date of the pickup. Format: YYYY-MM-DD.
`quote_id`	string	✔	This quote ID is generated and attached to this quote. This ID can be used to schedule a pickup based on this quote.
`quote_type`	string		When generating a spot-quote, `spot` is the string returned. For contract quotes, `contract` is the string returned.
`service`	Service Object	✔	This object contains service level information provided by the carrier and will include `carrier_description` and `code`.
`shipment`	Shipment Object	✔	ShipEngine creates this object to encompass all of the information provided for this shipment.

Charges Object

This object represents an individual item in the quote. It includes the type and amount for a charge, and may optionally include a description if provided by the carrier.

Name	Type	Required	Description
`amount`	Amount Object	✔	This object represents the monetary amount of the associated charge.
`description`	string		This is a description of the item that is provided by the carrier.
`type`	string	✔	This represents the type of the charge and witll return `total`, `discount`, `accessorial`, `container`, or `uncategorized`

Amount Object

This object includes the currency type and amount for a line item in the quote.

Name	Type	Required	Description
`currency`	string	✔	Three letter currency code.
`value`	string	✔	The amount of this value, represented as a string to avoid floating point rounding issues.

Service Object

This object contains service level information provided by the carrier.

Name	Type	Required	Description
`carrier_description`	string	✔	The description of the shipment provided by the carrier.
`code`	string	✔	This service code provided by the carrier.

Shipment Object

ShipEngine creates this shipment object to encompass the information provided for the quote.

Name	Type	Required	Description
`service_code`	string	✔	The service level requested for this quote.
`bill_to`	Bill To Object		`account`, `address`, `contact`, `payment_terms`, and `type` associated with the billing contact.
`delivery_date`	string		The date that the quote is scheduled to be delivered. Format: YYYY-MM-DD.
`options[]`	Options Object[]	✔	The accessorial services associated with this shipment.
`packages[]`	Packages Object[]	✔	An array of objects containing information about the physical freight being sent for this shipment.
`pickup_date`	string	✔	This is the scheduled date of the pickup. Format: YYYY-MM-DD.
`requested_by`	Requested By Object	✔	This object contains service level information provided by the carrier and will include `carrier_description` and `code`.
`service_code`	string	✔	This quote ID is generated and attached to this quote. This ID can be used to schedule a pickup based on this quote.
`ship_from`	Ship From Object	✔	ShipEngine creates this object to encompass all of the information provided for this shipment.
`ship_to`	Ship To Object	✔	The address and contact details for the location where the freight will be sent for this shipment.
`shipment_id`	string		The ID associated with this shipment. Currently this ID is only used for internal purposes.

Warning Object

This object represents any warnings returned by the error when the quote was created.

Name	Type	Required	Description
`external_code`	string		A code provided by the carrier associated with the message.
`message`	string		A description of the error provided by the carrier.

Example Request

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
POST /v-beta/ltl/spot-quotes/aed2a8c0-7998-4fef-9a82-2cab5f527dc2" HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipment": {
        "service_code": "stnd",
        "pickup_date": "2021-10-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
            }
        ],
        "options": [
            {
            "code": "LFTP"
            },
            {
            "code": "HAZ",
            "attributes": {
                "name": "Contact Person",
                "phone": "7704865900"
            }
            }
        ],
        "ship_from": {
            "account": "123456",
            "contact": {
                "name": "John Doe",
                "phone_number": "1111111111",
                "email": "[email protected]"
            },
            "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",
            "contact": {
                "name": "John Doe",
                "phone_number": "1111111111",
                "email": "[email protected]"
            },
            "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": "1111111111",
                "email": "[email protected]"
            }
        },
        "requested_by": {
            "company_name": "Example Corp.",
            "contact": {
            "name": "John Doe",
            "phone_number": "1111111111",
            "email": "[email protected]"
            }
        }
    },
    "shipment_measurements": {
        "total_linear_length": {
        "value": 48,
        "unit": "inches"
        },
        "total_width": {
        "value": 48,
        "unit": "inches"
        },
        "total_height": {
        "value": 48,
        "unit": "inches"
        },
        "total_weight": {
        "value": 10,
        "unit": "pounds"
        }
    }
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
{
    "quotes": [
        {
            "carrier_message": null,
            "charges": [
                {
                    "amount": {
                        "currency": "USD",
                        "value": "50.00"
                    },
                    "description": "Inside delivery",
                    "type": "accessorial"
                },
                {
                    "amount": {
                        "currency": "USD",
                        "value": "50.00"
                    },
                    "description": "Inside pickup",
                    "type": "accessorial"
                },
                {
                    "amount": {
                        "currency": "USD",
                        "value": "50.00"
                    },
                    "description": "Lift gate required at delivery",
                    "type": "accessorial"
                },
                {
                    "amount": {
                        "currency": "USD",
                        "value": "70.88"
                    },
                    "description": "Fuel Surcharge",
                    "type": "accessorial"
                },
                {
                    "amount": {
                        "currency": "USD",
                        "value": "895.92"
                    },
                    "description": "The freight charge including accessorials and/or discounts",
                    "type": "total"
                }
            ],
            "effective_date": null,
            "estimated_delivery_days": 6,
            "expiration_date": null,
            "pickup_date": "2021-12-31",
            "quote_id": "c26b6938-7c82-4648-b476-18f729a940f8",
            "quote_type": null,
            "service": {
                "carrier_description": "Standard Volume",
                "code": null
            },
            "shipment": {
                "bill_to": {
                    "account": "123456",
                    "address": {
                        "address_line1": "4009 Marathon Blvd",
                        "address_line2": null,
                        "address_line3": null,
                        "city_locality": "Austin",
                        "company_name": "Example Corp.",
                        "country_code": "US",
                        "postal_code": "78756",
                        "state_province": "TX"
                    },
                    "contact": {
                        "email": "[email protected]",
                        "name": "John Doe",
                        "phone_number": "1111111111"
                    },
                    "payment_terms": "prepaid",
                    "type": "third_party"
                },
                "delivery_date": null,
                "options": [
                    {
                        "attributes": null,
                        "code": "LFTP"
                    },
                    {
                        "attributes": {
                            "name": "Contact Person",
                            "phone": "7704865900"
                        },
                        "code": "HAZ"
                    }
                ],
                "packages": [
                    {
                        "code": "PKG",
                        "description": "Paperback books",
                        "dimensions": {
                            "height": 40,
                            "length": 48,
                            "unit": "inches",
                            "width": 40
                        },
                        "freight_class": 60,
                        "hazardous_materials": false,
                        "nmfc_code": "161630",
                        "quantity": 3,
                        "stackable": false,
                        "weight": {
                            "unit": "pounds",
                            "value": 1500
                        }
                    }
                ],
                "pickup_date": "2021-10-01",
                "requested_by": {
                    "company_name": "Example Corp.",
                    "contact": {
                        "email": "[email protected]",
                        "name": "John Doe",
                        "phone_number": "1111111111"
                    }
                },
                "service_code": null,
                "ship_from": {
                    "account": "123456",
                    "address": {
                        "address_line1": "4009 Marathon Blvd",
                        "address_line2": null,
                        "address_line3": null,
                        "city_locality": "Austin",
                        "company_name": "Example Corp.",
                        "country_code": "US",
                        "postal_code": "78756",
                        "state_province": "TX"
                    },
                    "contact": {
                        "email": "[email protected]",
                        "name": "John Doe",
                        "phone_number": "1111111111"
                    }
                },
                "ship_to": {
                    "account": "123456",
                    "address": {
                        "address_line1": "525 S Winchester Blvd",
                        "address_line2": null,
                        "address_line3": null,
                        "city_locality": "San Jose",
                        "company_name": "Widget Company",
                        "country_code": "US",
                        "postal_code": "95128",
                        "state_province": "CA"
                    },
                    "contact": {
                        "email": "[email protected]",
                        "name": "John Doe",
                        "phone_number": "1111111111"
                    }
                },
                "shipment_id": "44d282e0-2ea8-45bc-950b-0043acd8ac92"
            }
        }
    ],
    "warnings":[
    {
        "external_code":"10000008",
        "message":"Some of the accessorials submitted are not supported by the carrier and were not used. Unsupported code(s): APTD"
    }
]
}