Sign in
freight

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.

post/v1/freight/shipments

Request body

shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

offer_idstring required

The offer_id of the quoted offer being booked. Resolves server-side to the provider connection, the carrier, and the expiration.

pickup_instructionsstring nullable

Instructions for the driver at the origin.

delivery_instructionsstring nullable

Instructions for the driver at the destination.

handling_instructionsstring nullable

Instructions for handling the freight in transit.

Example request

{
  "shipment_id": "se-28529731",
  "offer_id": "0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68",
  "ship_from": {
    "name": "Marcus Bell",
    "company_name": "Northgate Distribution",
    "address_line1": "4200 Industrial Pkwy",
    "address_line2": "Dock 12",
    "city_locality": "Grand Rapids",
    "state_province": "MI",
    "postal_code": "49512",
    "country_code": "US",
    "phone": "+1 616 555 0142",
    "email": "dock@northgate-dist.example",
    "location_type": "commercial"
  },
  "ship_to": {
    "name": "Marcus Bell",
    "company_name": "Northgate Distribution",
    "address_line1": "4200 Industrial Pkwy",
    "address_line2": "Dock 12",
    "city_locality": "Grand Rapids",
    "state_province": "MI",
    "postal_code": "49512",
    "country_code": "US",
    "phone": "+1 616 555 0142",
    "email": "dock@northgate-dist.example",
    "location_type": "commercial"
  },
  "handling_units": [
    {
      "type": "pallet",
      "quantity": 2,
      "length": 48,
      "width": 40,
      "height": 52,
      "commodities": [
        {
          "description": "Assembled oak dining chairs",
          "quantity": 24,
          "weight": 310,
          "value": 4800,
          "packaging_type": "carton",
          "freight_class": "125",
          "nmfc_code": "80700-2",
          "hazardous_materials": {
            "identification_number_type": "un",
            "identification_number": "UN1263",
            "proper_shipping_name": "Paint",
            "hazard_class": "3",
            "subsidiary_hazard_classes": [
              "8"
            ],
            "packing_group": "iii",
            "emergency_contact_name": "Chemtrec",
            "emergency_contact_phone": "+1 800 424 9300",
            "emergency_response_reference": "CCN12345",
            "flashpoint_temperature": 73,
            "additional_details": "Keep upright. Do not stack."
          }
        }
      ]
    }
  ],
  "pickup_details": {
    "pickup_date": "2026-04-17T00:00:00Z",
    "ready_time": "09:00",
    "close_time": "16:30",
    "location_type": "commercial"
  },
  "references": [
    {
      "type": "purchase_order",
      "value": "PO-84213"
    }
  ],
  "pickup_instructions": "Check in with the guard at gate 3 before backing into dock 12.",
  "delivery_instructions": "Delivery appointments accepted between 08:00 and 11:00 only.",
  "handling_instructions": "Do not double stack. Load with forks from the long side."
}

Response

The request was a success.

freight_shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

freight_provider_account_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

freight_provider_codestring

The code of the freight provider the shipment was booked through.

status'pending' | 'quoted' | 'booked' | 'in_transit' | 'delivered' | 'cancelled' | 'exception'

The lifecycle status of a freight shipment. exception is also returned when the status cannot be determined.

bol_numberstring nullable

The Bill of Lading number assigned to the shipment.

pro_numberstring nullable

The carrier's PRO number for the shipment. Carriers often assign this after pickup, so it is usually null immediately after booking.

confirmation_numberstring nullable

The carrier's pickup confirmation number. null when the carrier did not return one.

Example response

{
  "freight_shipment_id": "se-28529731",
  "freight_provider_account_id": "se-28529731",
  "freight_provider_code": "UNISHIPPERS",
  "status": "booked",
  "bol_number": "BOL-20260417-4821",
  "pro_number": "072-51293847",
  "confirmation_number": "FXFE-PU-884215",
  "documents": [
    {
      "type": "BILL_OF_LADING",
      "url": "https://api.shipengine.com/v2/downloads/p1/a1b2c3d4e5f6/bill_of_lading.pdf"
    }
  ]
}

Changes