Site Logo

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 Object✔This object wraps shipment information requried by the carrier to generate a quote.
shipment_measurementsShipment 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.

NameTypeRequiredDescription
pickup_datestring✔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.
optionsOptions ObjectThe accessorial services required for pickup.
ship_fromShip From Object✔The address and contact details for the location where freight will be picked up.
ship_toShip to Object✔The address and contact details for the location where the freight will be sent.
bill_toBill To Object✔The address and contact details for the billing contact.
requested_byRequested 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.

NameTypeRequiredDescription
codestring✔The code for this package type.
freight_classnumber✔The NMFC freight class for your freight.
nmfc_codestringThe NMFC commodity code / item number.
descriptionstring✔The description of the item(s) in this container.
dimensionsDimensions Object✔The dimensions of the package.
weightWeight Object✔The weight of the package.
quantitynumber✔The number of packages of this type.
stackableboolean✔Indicates whether or not this package can be safely stacked.
hazardous_materialsboolean✔Indicates whether or not the package contains hazardous materials.

Dimensions Object

This object represents the physical dimensions of the package.

NameTypeRequiredDescription
widthnumber✔The value of the width of the package.
heightnumber✔The value of the height of the package.
lengthnumber✔The value of the length of the package.
unitstring✔The unit of measure for the dimensions. Valid values include inches and centimeters

Weight Object

This object represents the weight of the package.

NameTypeRequiredDescription
valuenumber✔The value of the weight of the package.
unitstring✔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

NameTypeRequiredDescription
total_linear_lengthTotal 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_widthTotal Width Object✔The 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
valuenumber✔The value of the linear length of the shipment.
unitstring✔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.

NameTypeRequiredDescription
valuenumber✔The value of the weight of the shipment.
unitstring✔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.

NameTypeRequiredDescription
codestring✔The 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 Object✔The address of the location.
contactContact Object✔The information for the contact person.

Bill To Object

This object represents the billing information for this pickup.

NameTypeRequiredDescription
typestring✔The type of billing. Valid values include consignee, shipper, or third_party.
payment_termsstring✔The 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 Object✔The information for the contact person.

Requested By Object

This object represents the requester of this pickup.

NameTypeRequiredDescription
company_namestring✔Name of the company making the pickup request.
contactContact Object✔The information for the contact person.

Address and Contact Objects

This object represents Address and Contact information.

Address Object

nametypeRequiredDescription
company_namestring✔The name of the company associated with this address.
address_line1string✔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_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_localitystring✔The city or locality of the shipment address.
state_provincestring✔The state or province of the shipment address.
postal_codestring✔The postal code of the shipment address.
country_codestring✔The two letter ISO 3166-1 alpha-2 country code.
residentialbooleanIndicates whether or not this is a residential address. Defaults to false.

Contact Object

nametypeRequiredDescription
namestring✔The name of the contact.
phone_numberstring✔The phone number of the contact.
emailstring✔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.

NameTypeRequiredDescription
quotesQuotes 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

NameTypeRequiredDescription
carrier_messagestringThis 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_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_datestring✔This is the scheduled date of the pickup. Format: YYYY-MM-DD.
quote_idstring✔This 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 Object✔This object contains service level information provided by the carrier and will include carrier_description and code.
shipmentShipment 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.

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

NameTypeRequiredDescription
currencystring✔Three letter currency code.
valuestring✔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.

NameTypeRequiredDescription
carrier_descriptionstring✔The description of the shipment provided by the carrier.
codestring✔This service code provided by the carrier.

Shipment Object

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

NameTypeRequiredDescription
service_codestring✔The 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_datestring✔This is the scheduled date of the pickup. Format: YYYY-MM-DD.
requested_byRequested By Object✔This object contains service level information provided by the carrier and will include carrier_description and code.
service_codestring✔This 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 Object✔ShipEngine creates this object to encompass all of the information provided for this shipment.
ship_toShip To Object✔The 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"
}
]
}