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.

NameTypeRequiredDescription
shipmentShipment ObjectThis object wraps shipment information requried by the carrier to generate a quote.
shipment_measurementsShipment Measurements ObjectThe 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.

NameTypeRequiredDescription
pickup_datestringThe shipment date of the quote. Date Format: YYYY-MM-DD
packages[]Package ObjectAn array of objects containing information about the physical freight being sent.
optionsOptions ObjectThe accessorial services required for pickup.
ship_fromShip From ObjectThe address and contact details for the location where freight will be picked up.
ship_toShip to ObjectThe address and contact details for the location where the freight will be sent.
bill_toBill To ObjectThe address and contact details for the billing contact.
requested_byRequested By ObjectThe 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.

NameTypeRequiredDescription
codestringThe code for this package type.
freight_classnumberThe NMFC freight class for your freight.
nmfc_codestringThe NMFC commodity code / item number.
descriptionstringThe description of the item(s) in this container.
dimensionsDimensions ObjectThe dimensions of the package.
weightWeight ObjectThe weight of the package.
quantitynumberThe number of packages of this type.
stackablebooleanIndicates whether or not this package can be safely stacked.
hazardous_materialsbooleanIndicates whether or not the package contains hazardous materials.

Dimensions Object

This object represents the physical dimensions of the package.

NameTypeRequiredDescription
widthnumberThe value of the width of the package.
heightnumberThe value of the height of the package.
lengthnumberThe value of the length of the package.
unitstringThe unit of measure for the dimensions. Valid values include inches and centimeters

Weight Object

This object represents the weight of the package.

NameTypeRequiredDescription
valuenumberThe value of the weight of the package.
unitstringThe 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

NameTypeRequiredDescription
total_linear_lengthTotal Linear Length ObjectThe 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_widthTotal Width ObjectThe total width of the shipment configuration as it will be loaded into the trailer.
total_heightTotal Height ObjectThe total height of the shipment configuration as it will be loaded into the trailer.
total_weightTotal Weight ObjectThe 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.

NameTypeRequiredDescription
valuenumberThe value of the linear length of the shipment.
unitstringThe 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.

NameTypeRequiredDescription
valuenumberThe value of the weight of the shipment.
unitstringThe 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.

NameTypeRequiredDescription
codestringThe carrier's code for this service option.
attributesobjectOptional 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.

NameTypeRequiredDescription
accountstringOptional account number may be included.
addressAddress ObjectThe address of the location.
contactContact ObjectThe information for the contact person.

Bill To Object

This object represents the billing information for this pickup.

NameTypeRequiredDescription
typestringThe type of billing. Valid values include consignee, shipper, or third_party.
payment_termsstringThe payment terms. Valid values include collect, prepaid, or third_party.
accountstringThe account number to bill for this pickup.
addressAddress ObjectThe address of the location.
contactContact ObjectThe information for the contact person.

Requested By Object

This object represents the requester of this pickup.

NameTypeRequiredDescription
company_namestringName of the company making the pickup request.
contactContact ObjectThe information for the contact person.

Address and Contact Objects

This object represents Address and Contact information.

Address Object

nametypeRequiredDescription
company_namestringThe name of the company associated with this address.
address_line1stringThe first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
address_line2stringThe second line of the street address. For some addresses, this line may not be needed.
address_line3stringThe third line of the street address. For some addresses, this line may not be needed.
city_localitystringThe city or locality of the shipment address.
state_provincestringThe state or province of the shipment address.
postal_codestringThe postal code of the shipment address.
country_codestringThe two letter ISO 3166-1 alpha-2 country code.
residentialbooleanIndicates whether or not this is a residential address. Defaults to false.

Contact Object

nametypeRequiredDescription
namestringThe name of the contact.
phone_numberstringThe phone number of the contact.
emailstringThe 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.

NameTypeRequiredDescription
quotesQuotes ObjectThis optional field contains a warning code and message if provided by the carrier.
warning[]Warning ObjectThis is an array of warning codes and messages if provided by the carrier.

Quotes Object

NameTypeRequiredDescription
carrier_messagestringThis optional field contains contains a message about the quote if provided by the carrier.
charges[]Charge ObjectAn array of objects containing an itemized breakdown of the charges for the quote.
effective_datestringThe date that the quote becomes active. This is provided if supported by the carrier. Format: YYYY-MM-DD.
estimated_delivery_daysnumberThis number represents the estimated number of days between pickup and delivery if provided by the carrier.
expiration_datestringQuote expiration information if supported by the carrier in format YYYY-MM-DD
pickup_datestringThis is the scheduled date of the pickup. Format: YYYY-MM-DD.
quote_idstringThis quote ID is generated and attached to this quote. This ID can be used to schedule a pickup based on this quote.
quote_typestringWhen generating a spot-quote, spot is the string returned. For contract quotes, contract is the string returned.
serviceService ObjectThis object contains service level information provided by the carrier and will include carrier_description and code.
shipmentShipment ObjectShipEngine 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.

NameTypeRequiredDescription
amountAmount ObjectThis object represents the monetary amount of the associated charge.
descriptionstringThis is a description of the item that is provided by the carrier.
typestringThis 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.

NameTypeRequiredDescription
currencystringThree letter currency code.
valuestringThe 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.

NameTypeRequiredDescription
carrier_descriptionstringThe description of the shipment provided by the carrier.
codestringThis service code provided by the carrier.

Shipment Object

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

NameTypeRequiredDescription
service_codestringThe service level requested for this quote.
bill_toBill To Objectaccount, address, contact, payment_terms, and type associated with the billing contact.
delivery_date stringThe 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_datestringThis is the scheduled date of the pickup. Format: YYYY-MM-DD.
requested_byRequested By ObjectThis object contains service level information provided by the carrier and will include carrier_description and code.
service_codestringThis quote ID is generated and attached to this quote. This ID can be used to schedule a pickup based on this quote.
ship_fromShip From ObjectShipEngine creates this object to encompass all of the information provided for this shipment.
ship_toShip To ObjectThe address and contact details for the location where the freight will be sent for this shipment.
shipment_idstringThe 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.

NameTypeRequiredDescription
external_codestringA code provided by the carrier associated with the message.
messagestringA 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"
}
]
}