# Book a freight shipment

Products
            Plans
          
        
        
          
            
              
              Formerly ShipEngine
            
            
              Free
              Advanced
              Enterprise
            
          
          
            
              
            
            
              Free
              Starter
              Standard
              Premium
            
          
        
      
      
        
          Learn about products and plans
          
        
      
    

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.

quote_request_id, offer_id, carrier_scac, and quote_expiration_date must be copied from the offer you are booking. Quotes are short-lived: booking an offer whose quote_expiration_date has passed returns a 400 Bad Request, and you need to request new quotes.

Endpoint: POST /v2/freight/shipments
Version: 2.0.0
Security: api_keys

## Request fields (application/json):

  - `freight_provider_account_id` (string, required)
    The freight provider account the offer was quoted through.
    Example: "se-28529731"

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

  - `quote_request_id` (string, required)
    The quote_request_id of the offer being booked.
    Example: "7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10"

  - `offer_id` (string, required)
    The offer_id of the offer being booked.
    Example: "0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68"

  - `quote_expiration_date` (string, required)
    The quote_expiration_date of the offer being booked. A date in the past is rejected with a 400 Bad Request.
    Example: "2026-04-16T23:59:59Z"

  - `carrier_scac` (string, required)
    The carrier_scac of the offer being booked.
    Example: "FXFE"

  - `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

  - `handling_units` (array)
    The handling units being shipped. Required when shipment_id is omitted, and must not be provided when shipment_id is present.

  - `handling_units.type` (string,null)
    The kind of handling unit. Defaults to pallet. Unrecognized values are ignored rather than rejected.
    Enum: "bag", "bale", "box", "bundle", "carton", "case", "crate", "cylinder", "drum", "pail", "pallet", "pieces", "reel", "roll", "skid", "tank", "tote", "trailer", "tube", null

  - `handling_units.quantity` (integer, required)
    The number of identical handling units being shipped. The dimensions, weight, and commodities describe one of them; the carrier multiplies them out.
    Example: 2

  - `handling_units.length` (number, required)
    The length of a single handling unit, in the unit specified by dimension_unit.
    Example: 48

  - `handling_units.width` (number, required)
    The width of a single handling unit, in the unit specified by dimension_unit.
    Example: 40

  - `handling_units.height` (number, required)
    The height of a single handling unit, in the unit specified by dimension_unit.
    Example: 52

  - `handling_units.dimension_unit` (string, required)
    The unit of measure for length, width, and height.
    Enum: "inch", "centimeter"

  - `handling_units.stackable` (boolean)
    Whether the carrier may stack other freight on top of this handling unit. Non-stackable freight consumes more trailer space and can cost more.

  - `handling_units.commodities` (array, required)
    The goods inside a single handling unit. At least one commodity is required.

  - `handling_units.commodities.description` (string,null)
    A description of the goods. Carriers print this on the Bill of Lading.
    Example: "Assembled oak dining chairs"

  - `handling_units.commodities.quantity` (integer, required)
    The number of pieces of this commodity inside a single handling unit.
    Example: 24

  - `handling_units.commodities.weight` (number, required)
    The total weight of this commodity line inside a single handling unit.
    Example: 310

  - `handling_units.commodities.weight_unit` (string, required)
    The unit of measure for weight.
    Enum: "pound", "ounce", "gram", "kilogram"

  - `handling_units.commodities.packaging_type` (string,null)
    How this commodity is packaged inside the handling unit. Unrecognized values are ignored rather than rejected.
    Enum: "bag", "bale", "box", "bundle", "carton", "case", "crate", "cylinder", "drum", "pail", "pallet", "pieces", "reel", "roll", "skid", "tank", "tote", "trailer", "tube", null

  - `handling_units.commodities.freight_class` (string, required)
    The National Motor Freight Traffic Association (NMFTA) [freight class](https://nmfta.org/nmfc/) of the goods. Freight class is derived from density, stowability, handling, and liability, and is one of the largest factors in the price of an LTL shipment.
    Enum: "50", "55", "60", "65", "70", "77.5", "85", "92.5", "100", "110", "125", "150", "175", "200", "250", "300", "400", "500"

  - `handling_units.commodities.nmfc_code` (string,null)
    The NMFC item and sub number for the goods.
    Example: "80700-2"

  - `handling_units.commodities.hazardous_materials` (object)
    Hazmat details. Provide this object only for hazardous commodities.

  - `handling_units.commodities.hazardous_materials.identification_number_type` (string, required)
    The authority that issued the identification number: un for a United Nations number or na for a North America number.
    Enum: "un", "na"

  - `handling_units.commodities.hazardous_materials.identification_number` (string, required)
    The UN or NA number identifying the hazardous material.
    Example: "UN1263"

  - `handling_units.commodities.hazardous_materials.proper_shipping_name` (string, required)
    The proper shipping name of the hazardous material, as published in the hazardous materials table.
    Example: "Paint"

  - `handling_units.commodities.hazardous_materials.hazard_class` (string, required)
    The primary hazard class or division of the material.
    Enum: "1.1A", "1.1B", "1.1C", "1.1D", "1.1E", "1.1F", "1.1G", "1.1J", "1.1L", "1.2B", "1.2C", "1.2D", "1.2E", "1.2F", "1.2G", "1.2H", "1.2J", "1.2K", "1.2L", "1.3C", "1.3G", "1.3H", "1.3J", "1.3K", "1.3L", "1.4B", "1.4C", "1.4D", "1.4E", "1.4F", "1.4G", "1.4S", "1.5D", "1.6N", "2.1", "2.2", "2.3", "3", "4.1", "4.2", "4.3", "5.1", "5.2", "6.1", "6.2", "7", "8", "9"

  - `handling_units.commodities.hazardous_materials.subsidiary_hazard_classes` (array)
    Any subsidiary hazard classes, using the same values as hazard_class. Values must be unique and must not repeat the primary hazard_class.
    Example: ["8"]

  - `handling_units.commodities.hazardous_materials.packing_group` (string, required)
    The packing group assigned to the material, or none when the material has no packing group.
    Enum: "i", "ii", "iii", "none"

  - `handling_units.commodities.hazardous_materials.emergency_contact_name` (string, required)
    The name of the 24-hour emergency response contact.
    Example: "Chemtrec"

  - `handling_units.commodities.hazardous_materials.emergency_contact_phone` (string, required)
    The phone number of the 24-hour emergency response contact.
    Example: "+1 800 424 9300"

  - `handling_units.commodities.hazardous_materials.emergency_response_reference` (string,null)
    The emergency response registration or contract number, such as a CHEMTREC contract number.
    Example: "CCN12345"

  - `handling_units.commodities.hazardous_materials.flashpoint_temperature` (number,null)
    The flashpoint of the material in degrees Fahrenheit, when it has one.
    Example: 73

  - `handling_units.commodities.hazardous_materials.additional_details` (string,null)
    Any additional hazmat information the carrier should print on the Bill of Lading.
    Example: "Keep upright. Do not stack."

  - `handling_units.commodities.value` (number,null)
    Accepted but ignored. This field is not sent to the carrier and is not stored. To declare a value for cargo insurance, use insurance.insured_value on the quote request instead.
    Example: 4800

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

  - `pickup_details.pickup_date` (string, required)
    The date the freight is ready to be collected.
    Example: "2026-04-17T00:00:00Z"

  - `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, ShipStation 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"

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

  - `freight_provider_name` (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"

  - `product_transaction_id` (string,null)
    The provider's identifier for the booked shipment.
    Example: "7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10"

  - `pickup_transaction_id` (string,null)
    The provider's identifier for the pickup request. null when no pickup was requested.
    Example: "3ac81f60-92b7-4de1-8f04-5b9a7c2e6d13"

  - `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"

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

  - `documents.document_id` (integer,null)
    Always null on a booking response. Reserved for future use.

  - `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)
    Always null on a booking response. Use [List freight shipment documents](#operation/list_freight_shipment_documents) to get a download path.

## 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, the ShipStation API itself, or the underlying ShipEngine platform.
    Enum: "carrier", "order_source", "ShipStation", "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", "freight_connection_inactive", "freight_provider_id_required", "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.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"