--- title: "Book a freight shipment" method: POST path: "/v2/freight/shipments" tags: ["freight"] --- # Book a freight shipment `POST /v2/freight/shipments` Book one of the offers returned by [Get freight quotes](#operation/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](#operation/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. ## Request body - BookFreightShipmentRequestBody — A request to book a freight offer returned by a quote. Copy `quote_request_id`, `offer_id`, `carrier_scac`, and `quote_expiration_date` from the offer being booked. - `freight_provider_account_id` string, required — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc. - `shipment_id` string — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc. - `quote_request_id` string, required — The `quote_request_id` of the offer being booked. - `offer_id` string, required — The `offer_id` of the offer being booked. - `quote_expiration_date` string, 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_scac` string, required — The `carrier_scac` of the offer being booked. - `ship_from` FreightAddress — An origin or destination address for a freight shipment. LTL carriers require a contact name, company name, and phone number at both ends of the shipment so the driver can arrange pickup and delivery. - `name` string, required — The name of the contact person at this location. - `company_name` string, required — The name of the business at this location. - `address_line1` string, required — The first line of the street address. - `address_line2` string, nullable — The second line of the street address, such as a dock or suite number. - `city_locality` string, required — The city or locality. - `state_province` string, required — The state or province. - `postal_code` string, required — The postal code. - `country_code` string, required — The two-letter ISO 3166-1 alpha-2 country code. - `phone` string, required — The phone number of the contact person. Carriers call this number to arrange pickup or delivery. - `email` string, nullable — The email address of the contact person. - `location_type` 'airport' | 'carrier_terminal' | 'commercial' | 'construction' | 'container_freight_station' | 'distribution_center' | 'government_facility' | 'limited_access' | 'pier_port_wharf' | 'residential' | 'secured_access' | 'trade_show' | 'null', nullable — 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`. - `ship_to` FreightAddress — An origin or destination address for a freight shipment. LTL carriers require a contact name, company name, and phone number at both ends of the shipment so the driver can arrange pickup and delivery. - `name` string, required — The name of the contact person at this location. - `company_name` string, required — The name of the business at this location. - `address_line1` string, required — The first line of the street address. - `address_line2` string, nullable — The second line of the street address, such as a dock or suite number. - `city_locality` string, required — The city or locality. - `state_province` string, required — The state or province. - `postal_code` string, required — The postal code. - `country_code` string, required — The two-letter ISO 3166-1 alpha-2 country code. - `phone` string, required — The phone number of the contact person. Carriers call this number to arrange pickup or delivery. - `email` string, nullable — The email address of the contact person. - `location_type` 'airport' | 'carrier_terminal' | 'commercial' | 'construction' | 'container_freight_station' | 'distribution_center' | 'government_facility' | 'limited_access' | 'pier_port_wharf' | 'residential' | 'secured_access' | 'trade_show' | 'null', nullable — 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`. - `handling_units` FreightHandlingUnit[] — The handling units being shipped. Required when `shipment_id` is omitted, and must not be provided when `shipment_id` is present. - `type` 'bag' | 'bale' | 'box' | 'bundle' | 'carton' | 'case' | 'crate' | 'cylinder' | 'drum' | 'pail' | 'pallet' | 'pieces' | 'reel' | 'roll' | 'skid' | 'tank' | 'tote' | 'trailer' | 'tube' | 'null', nullable — The kind of handling unit. Defaults to `pallet`. Unrecognized values are ignored rather than rejected. - `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. - `length` number, double, required — The length of a single handling unit, in the unit specified by `dimension_unit`. - `width` number, double, required — The width of a single handling unit, in the unit specified by `dimension_unit`. - `height` number, double, required — The height of a single handling unit, in the unit specified by `dimension_unit`. - `dimension_unit` 'inch' | 'centimeter', required — The dimension units that are supported by ShipStation . - `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. - `commodities` FreightCommodity[], required — The goods inside a single handling unit. At least one commodity is required. - `description` string, nullable — A description of the goods. Carriers print this on the Bill of Lading. - `quantity` integer, required — The number of pieces of this commodity inside a single handling unit. - `weight` number, double, required — The total weight of this commodity line inside a single handling unit. - `weight_unit` 'pound' | 'ounce' | 'gram' | 'kilogram', required — The possible weight unit values - `value` number, double, nullable — 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. - `packaging_type` 'bag' | 'bale' | 'box' | 'bundle' | 'carton' | 'case' | 'crate' | 'cylinder' | 'drum' | 'pail' | 'pallet' | 'pieces' | 'reel' | 'roll' | 'skid' | 'tank' | 'tote' | 'trailer' | 'tube' | 'null', nullable — How this commodity is packaged inside the handling unit. Unrecognized values are ignored rather than rejected. - `freight_class` '50' | '55' | '60' | '65' | '70' | '77.5' | '85' | '92.5' | '100' | '110' | '125' | '150' | '175' | '200' | '250' | '300' | '400' | '500', 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. - `nmfc_code` string, nullable — The NMFC item and sub number for the goods. - `hazardous_materials` FreightHazardousMaterials — Hazardous materials (hazmat) details for a commodity. Providing this object flags the commodity as hazmat, which the carrier prints on the Bill of Lading. All fields other than `subsidiary_hazard_classes`, `emergency_response_reference`, `flashpoint_temperature`, and `additional_details` are required. - `identification_number_type` 'un' | 'na', required — The authority that issued the identification number: `un` for a United Nations number or `na` for a North America number. - `identification_number` string, required — The UN or NA number identifying the hazardous material. - `proper_shipping_name` string, required — The proper shipping name of the hazardous material, as published in the hazardous materials table. - `hazard_class` '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', required — The primary hazard class or division of the material. - `subsidiary_hazard_classes` string[] — Any subsidiary hazard classes, using the same values as `hazard_class`. Values must be unique and must not repeat the primary `hazard_class`. - `packing_group` 'i' | 'ii' | 'iii' | 'none', required — The packing group assigned to the material, or `none` when the material has no packing group. - `emergency_contact_name` string, required — The name of the 24-hour emergency response contact. - `emergency_contact_phone` string, required — The phone number of the 24-hour emergency response contact. - `emergency_response_reference` string, nullable — The emergency response registration or contract number, such as a CHEMTREC contract number. - `flashpoint_temperature` number, double, nullable — The flashpoint of the material in degrees Fahrenheit, when it has one. - `additional_details` string, nullable — Any additional hazmat information the carrier should print on the Bill of Lading. - `pickup_details` FreightPickupDetails, required — When the carrier can collect the freight. The ready and close times define the pickup window at the origin, and the carrier needs a window wide enough for a driver to arrive. - `pickup_date` string, date-time, required — The date the freight is ready to be collected. - `ready_time` string, required — The earliest time the freight can be collected, in 24-hour `HH:mm` format and local to the origin. - `close_time` string, required — The time the origin closes, in 24-hour `HH:mm` format and local to the origin. - `is_self_scheduled` boolean — Whether you arrange the pickup with the carrier yourself. When `true`, ShipStation does not request a pickup on your behalf. - `location_type` 'airport' | 'carrier_terminal' | 'commercial' | 'construction' | 'container_freight_station' | 'distribution_center' | 'government_facility' | 'limited_access' | 'pier_port_wharf' | 'residential' | 'secured_access' | 'trade_show' | 'null', nullable — How the carrier should classify the pickup location. An unrecognized value is rejected with a `400 Bad Request`. - `references` FreightReference[] — Reference numbers for the carrier to print on the Bill of Lading. - `type` string, nullable — 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. - `value` string, nullable — 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. - `pickup_instructions` string, nullable — Instructions for the driver at the origin. - `delivery_instructions` string, nullable — Instructions for the driver at the destination. - `handling_instructions` string, nullable — Instructions for handling the freight in transit. ## Response `200` The request was a success. - BookFreightShipmentResponseBody — The freight shipment created by a booking. - `freight_shipment_id` string — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc. - `freight_provider_account_id` string — A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc. - `freight_provider_name` string — 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_id` string, nullable — The provider's identifier for the booked shipment. - `pickup_transaction_id` string, nullable — The provider's identifier for the pickup request. `null` when no pickup was requested. - `bol_number` string, nullable — The Bill of Lading number assigned to the shipment. - `pro_number` string, nullable — The carrier's PRO number for the shipment. Carriers often assign this after pickup, so it is usually `null` immediately after booking. - `confirmation_number` string, nullable — The carrier's pickup confirmation number. `null` when the carrier did not return one. - `documents` FreightBookedDocument[], nullable — The documents the carrier generated for the booking. `null` when the provider reported none. - `document_id` integer, nullable — Always `null` on a booking response. Reserved for future use. - `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. - `url` string, nullable — Always `null` on a booking response. Use [List freight shipment documents](#operation/list_freight_shipment_documents) to get a download path. ## Other responses - `400` — The request contained errors, the quote has expired, the freight provider connection is not active for the account, the linked shipment has no freight configuration or a cancelled one, or the provider rejected the booking. - `404` — The `shipment_id` does not identify a shipment on this account. - `500` — The request was successful. --- [API](https://skmtc.net/shipstation/apis/shipstation-api-v2.md) · [All operations](https://skmtc.net/shipstation/apis/shipstation-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipstation/shipstation-api-v2/revisions/d3d8c21cd227/schema)