# Book a freight shipment

Book one of the offers returned by Get freight quotes. Booking dispatches the shipment with the LTL carrier and generates the shipment's documents, such as the Bill of Lading.

As with quoting, there are two ways to book:

- Linked to an existing shipment. Provide shipment_id. The shipment must already have a freight quote — call Get freight quotes for it first. The origin, destination, and handling units all come from the shipment and its saved freight configuration, so ship_from, ship_to, and handling_units must be omitted.
- Inline. Omit shipment_id and provide ship_from, ship_to, and handling_units. A shipment record is created for the booking and marked as shipped.

Pass the offer_id from the offer you are booking. The provider connection, carrier, and expiration are resolved server-side from the stored offer.

Endpoint: POST /v1/freight/shipments
Version: 1.1.202604070904
Security: api_key

## Request fields (application/json):

  - `shipment_id` (string)
    The shipment the offer was quoted for. When provided, the shipment must already have a freight quote, and ship_from and ship_to must be omitted — the origin, destination, and handling units all come from the shipment and its saved freight configuration.
    Example: "se-28529731"

  - `offer_id` (string, required)
    The offer_id of the quoted offer being booked. Resolves server-side to the provider connection, the carrier, and the expiration.
    Example: "0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68"

  - `ship_from` (object)
    The origin address. Required when shipment_id is omitted, and must not be provided when shipment_id is present.

  - `ship_from.name` (string, required)
    The name of the contact person at this location.
    Example: "Marcus Bell"

  - `ship_from.company_name` (string, required)
    The name of the business at this location.
    Example: "Northgate Distribution"

  - `ship_from.address_line1` (string, required)
    The first line of the street address.
    Example: "4200 Industrial Pkwy"

  - `ship_from.address_line2` (string,null)
    The second line of the street address, such as a dock or suite number.
    Example: "Dock 12"

  - `ship_from.city_locality` (string, required)
    The city or locality.
    Example: "Grand Rapids"

  - `ship_from.state_province` (string, required)
    The state or province.
    Example: "MI"

  - `ship_from.postal_code` (string, required)
    The postal code.
    Example: "49512"

  - `ship_from.country_code` (string, required)
    The two-letter ISO 3166-1 alpha-2 country code.
    Example: "US"

  - `ship_from.phone` (string, required)
    The phone number of the contact person. Carriers call this number to arrange pickup or delivery.
    Example: "+1 616 555 0142"

  - `ship_from.email` (string,null)
    The email address of the contact person.
    Example: "dock@northgate-dist.example"

  - `ship_from.location_type` (string,null)
    How the carrier should classify this location. Location type affects accessorial charges — for example, residential and limited-access locations usually carry a surcharge. An unrecognized value is rejected with a 400 Bad Request.
    Enum: "airport", "carrier_terminal", "commercial", "construction", "container_freight_station", "distribution_center", "government_facility", "limited_access", "pier_port_wharf", "residential", "secured_access", "trade_show", null

  - `ship_to` (object)
    The destination address. Required when shipment_id is omitted, and must not be provided when shipment_id is present.

  - `ship_to.name` (string, required)
    The name of the contact person at this location.
    Example: "Marcus Bell"

  - `ship_to.company_name` (string, required)
    The name of the business at this location.
    Example: "Northgate Distribution"

  - `ship_to.address_line1` (string, required)
    The first line of the street address.
    Example: "4200 Industrial Pkwy"

  - `ship_to.address_line2` (string,null)
    The second line of the street address, such as a dock or suite number.
    Example: "Dock 12"

  - `ship_to.city_locality` (string, required)
    The city or locality.
    Example: "Grand Rapids"

  - `ship_to.state_province` (string, required)
    The state or province.
    Example: "MI"

  - `ship_to.postal_code` (string, required)
    The postal code.
    Example: "49512"

  - `ship_to.country_code` (string, required)
    The two-letter ISO 3166-1 alpha-2 country code.
    Example: "US"

  - `ship_to.phone` (string, required)
    The phone number of the contact person. Carriers call this number to arrange pickup or delivery.
    Example: "+1 616 555 0142"

  - `ship_to.email` (string,null)
    The email address of the contact person.
    Example: "dock@northgate-dist.example"

  - `ship_to.location_type` (string,null)
    How the carrier should classify this location. Location type affects accessorial charges — for example, residential and limited-access locations usually carry a surcharge. An unrecognized value is rejected with a 400 Bad Request.
    Enum: "airport", "carrier_terminal", "commercial", "construction", "container_freight_station", "distribution_center", "government_facility", "limited_access", "pier_port_wharf", "residential", "secured_access", "trade_show", null

  - `pickup_details` (object, required)
    When the carrier can collect the freight. Always required.

  - `pickup_details.pickup_date` (string, required)
    The calendar date at the pickup location when the freight is ready to be collected. Pass a plain date (YYYY-MM-DD); any time or UTC offset is accepted but discarded, so 2026-04-17T23:00:00-07:00 and 2026-04-17 both schedule the 17th.
    Example: "2026-04-17"

  - `pickup_details.ready_time` (string, required)
    The earliest time the freight can be collected, in 24-hour HH:mm format and local to the origin.
    Example: "09:00"

  - `pickup_details.close_time` (string, required)
    The time the origin closes, in 24-hour HH:mm format and local to the origin.
    Example: "16:30"

  - `pickup_details.is_self_scheduled` (boolean)
    Whether you arrange the pickup with the carrier yourself. When true, ShipEngine does not request a pickup on your behalf.

  - `pickup_details.location_type` (string,null)
    How the carrier should classify the pickup location. An unrecognized value is rejected with a 400 Bad Request.
    Enum: "airport", "carrier_terminal", "commercial", "construction", "container_freight_station", "distribution_center", "government_facility", "limited_access", "pier_port_wharf", "residential", "secured_access", "trade_show", null

  - `references` (array)
    Reference numbers for the carrier to print on the Bill of Lading.

  - `references.type` (string,null)
    A free-form label for the reference, such as purchase_order, sales_order, or reference_1. The values a carrier can print vary by carrier.
    Example: "purchase_order"

  - `references.value` (string,null)
    The reference value. Not length-validated by the API, but keep it short — carriers commonly truncate reference values to around 35 characters on the Bill of Lading.
    Example: "PO-84213"

  - `pickup_instructions` (string,null)
    Instructions for the driver at the origin.
    Example: "Check in with the guard at gate 3 before backing into dock 12."

  - `delivery_instructions` (string,null)
    Instructions for the driver at the destination.
    Example: "Delivery appointments accepted between 08:00 and 11:00 only."

  - `handling_instructions` (string,null)
    Instructions for handling the freight in transit.
    Example: "Do not double stack. Load with forks from the long side."

## Response 200 fields (application/json):

  - `freight_shipment_id` (string)
    The identifier of the freight shipment. Use it to retrieve, track, or cancel the shipment.
    Example: "se-28529731"

  - `shipment_id` (string,null)
    The identifier of the ShipStation shipment linked to this freight booking, if any.
    Example: "se-28529731"

  - `freight_provider_account_id` (string)
    The freight provider account the shipment was booked through.
    Example: "se-28529731"

  - `freight_provider_code` (string)
    The code of the freight provider the shipment was booked through.
    Example: "UNISHIPPERS"

  - `status` (string)
    The status of the shipment. A successful booking returns booked.
    Enum: "pending", "quoted", "booked", "in_transit", "delivered", "cancelled", "exception"

  - `bol_number` (string,null)
    The Bill of Lading number assigned to the shipment.
    Example: "BOL-20260417-4821"

  - `pro_number` (string,null)
    The carrier's PRO number for the shipment. Carriers often assign this after pickup, so it is usually null immediately after booking.
    Example: "072-51293847"

  - `confirmation_number` (string,null)
    The carrier's pickup confirmation number. null when the carrier did not return one.
    Example: "FXFE-PU-884215"

  - `created_at` (string)
    The date and time the freight shipment was created, in UTC.
    Example: "2026-09-18T14:54:44Z"

  - `documents` (array,null)
    The documents the carrier generated for the booking. null when the provider reported none.

  - `documents.type` (string)
    The type of document, as reported by the freight provider — for example BILL_OF_LADING, PALLET_LABEL, or BOL_PALLET_LABEL_COMBINED. Unlike the lowercase values returned by [List freight shipment documents](#operation/list_freight_shipment_documents), this is the provider's raw value.
    Example: "BILL_OF_LADING"

  - `documents.url` (string,null)
    The path to download the document as a PDF.
    Example: "https://api.shipengine.com/v2/downloads/p1/a1b2c3d4e5f6/bill_of_lading.pdf"

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error", "freight_connection_inactive", "freight_provider_id_required", "freight_provider_already_connected", "freight_shipment_not_found", "freight_tracking_not_available", "freight_tracking_not_found", "freight_shipment_not_batchable"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"