freight

Book a freight shipment

Changed on Oct 22, 2026

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

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/freight/shipments
Auth: API key in header API-Key

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"
  },
  "pickup_details": {
    "pickup_date": "2026-04-17",
    "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.",
  "notifications": [
    {
      "events": [
        "booked",
        "in_transit"
      ],
      "email_addresses": [
        "logistics@example.com"
      ]
    }
  ]
}

Response

The request was a success.

freight_shipment_idstring

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.

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.

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.

created_atstring date-time

The date and time the freight shipment was created, in UTC.

Example response

{
  "freight_shipment_id": "se-28529731",
  "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",
  "created_at": "2026-09-18T14:54:44Z",
  "documents": [
    {
      "type": "BILL_OF_LADING",
      "url": "https://api.shipengine.com/v2/downloads/p1/a1b2c3d4e5f6/bill_of_lading.pdf"
    }
  ],
  "notifications": [
    {
      "events": [
        "booked",
        "in_transit"
      ],
      "email_addresses": [
        "logistics@example.com"
      ]
    }
  ]
}

Changes

Oct 22, 2026e998dffc42be Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (9 revisions)