Schedule an LTL Pickup
This API endpoint is used to schedule a pickup directly with a carrier using a carrier_id
without first creating a quote.
This combines creating a quote and scheduling a pickup into one API call,
and it is intended for people who do not need to review a quote before scheduling a pickup.
This endpoint will create a bill of lading and schedule a pickup with the carrier. Not all carriers support electronic pickup requests. For these carriers you will need to call and schedule the pickup with the carrier directly.
Once you have used this endpoint to create a bill of lading, you will need to print it and give it to the carrier at pickup.
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_id
s from the List Connected Carriers endpoint.
Request Body
The following table lists the parameters required for this endpoint. To see a sample of a full request, see the Example Request section below.
Name | Type | Required | Description |
---|---|---|---|
carrier | Carrier Object | Any additional instructions to the carrier. | |
options[] | Options Object | The accessorial services required for this pickup. | |
reference_identifiers[] | Reference Identifiers Object | You may optionally send the carrier an associated quote_id or pro number for their reference. | |
shipment | Shipment Object | ✔ | Delivery and billing details used to schedule the pickup. |
Carrier Object
This object represents optional instructions for the carrier.
Name | Type | Required | Description |
---|---|---|---|
instructions | string | Optional instructions for the carrier. | |
test | boolean | Indicates whether or not this is a test call. |
Options Object
This object represents the optional accessorial services you require for this shipment or 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. |
Reference Identifiers Object
You may optionally send the carrier associated documents created outside of ShipEngine for their reference. Some carriers may refer to previous quotes and pickups when determing rates for a new pickup.
Name | Type | Required | Description |
---|---|---|---|
type | string | ✔ | Paramaters that may be passed are bill_of_lading , pro , quote , purchase_order , or other . |
value | string | ✔ | The corresponding provided by the carrier. |
Shipment Object
ShipEngine creates this shipment object to encompass the information provided for the quote.
Name | Type | Required | Description |
---|---|---|---|
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 | ✔ | The scheduled date of the pickup. Format: YYYY-MM-DD. |
pickup_window | Pickup Window Object | ✔ | When a quote is created during a pickup, this will return an object representing the pickup window. Otherwise, this will return null |
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 | ✔ | The carrier service requested for 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. |
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. |
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 . |
Pickup Window Object
This object represents information about the pickup window.
Name | Type | Required | Description | Format |
---|---|---|---|---|
start_at | string | ✔ | The earliest time that the freight will be ready for pickup. | 24 Hour Format: HH:MM:SS, HH:MM:SSZ, HH:MM:SS+/-HH:MM |
end_at | string | ✔ | The latest desired pickup time. | 24 Hour Format: HH:MM:SS, HH:MM:SSZ, HH:MM:SS+/-HH:MM |
closing_at | string | ✔ | The time that the pickup facility closes for business. | 24 Hour Format: HH:MM:SS, HH:MM:SSZ, HH:MM:SS+/-HH:MM |
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. |
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. |
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 object returned from sucessful requests to this endpoint will contain the parameters listed in the table below. To see a sample of a full response, see the Example Response section below.
Name | Type | Required | Description |
---|---|---|---|
confirmation_number | string | ✔ | A number returned by the carrier to indicate the request was received. |
documents[] | object | ✔ | An array of document objects. For pickup requests this documents array will only include the Bill of Lading. |
documents.type | string | ✔ | The type will always be bill_of_lading in the pickup response. |
documents.image | string | ✔ | The base64-encoded bill of lading document. |
documents.format | string | ✔ | The format of the document which will always be pdf for pickup responses. The base64-encoded image string will be in this format once decoded. |
message | string | ✔ | This optional message includes notes about the pickup if provided by the carrier. |
pickup_id | string | ✔ | A unique ID used to identify this scheduled pickup. This may be used to create a BOL. |
pro_number | string | ✔ | The PRO number for the pickup assigned by the carrier. If a number is not returned here the carrier will issue one at the time of pickup. |
quote_id | string | ✔ | A unique ID used to identify the quote created to schedule this pickup. This may be used to create a BOL. |
shipment_id | string | ✔ | A unique ID used by ShipEngine to reference this pickup. |
warnings | object | ✔ | This object represents any warnings returned by the carrier when the pickup was scheduled. |
warnings.external_code | string | ✔ | The code associated with the warning if provided by the carrier. |
warnings.message | string | ✔ | A warning about the pickup if provided by the carrier. |
Bill of Lading
A Bill of Lading, or BOL, is a document that can be given to the carrier at pickup to acknowledge receipt for shipment. A BOL will automatically generated and returned when you schedule a pickup.
Example Request
POST /v-beta/ltl/pickups/:carrier_id