Sign in
latestOpenAPI 3.0.0Proprietary2026-08-22131410675.6 KB

8d8a7cf79204

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.

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.

post/v1/freight/shipments

Request body

freight_provider_account_idstring required

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

shipment_idstring

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

quote_request_idstring required

The quote_request_id of the offer being booked.

offer_idstring required

The offer_id of the offer being booked.

quote_expiration_datestring date-time required

The quote_expiration_date of the offer being booked. A date in the past is rejected with a 400 Bad Request.

carrier_scacstring required

The carrier_scac of the offer being booked.

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

{
  "freight_provider_account_id": "se-28529731",
  "shipment_id": "se-28529731",
  "quote_request_id": "7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10",
  "offer_id": "0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68",
  "quote_expiration_date": "2026-04-16T23:59:59Z",
  "carrier_scac": "FXFE",
  "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_namestring

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.

product_transaction_idstring nullable

The provider's identifier for the booked shipment.

pickup_transaction_idstring nullable

The provider's identifier for the pickup request. null when no pickup was requested.

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_name": "UNISHIPPERS",
  "status": "booked",
  "product_transaction_id": "7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10",
  "pickup_transaction_id": "3ac81f60-92b7-4de1-8f04-5b9a7c2e6d13",
  "bol_number": "BOL-20260417-4821",
  "pro_number": "072-51293847",
  "confirmation_number": "FXFE-PU-884215",
  "documents": [
    {
      "type": "BILL_OF_LADING"
    }
  ]
}