Drayage Book

Endpoint: POST /v1/drayage/book

Create a drayage booking for a container movement using a rate selected from a previous drayage quote. You must supply the quoteNumber and rateNumber returned by the quote endpoint, along with full load, terminal, shipper/consignee, and container details.

Authentication required All requests to this endpoint require a valid bearer token. See Authentication.

Prerequisites

Before booking, gather:

quoteNumber from POST /v1/drayage/quote
rateNumber from the selected rate in the quote response
Terminal information from GET /v1/tools/drayage/terminals
HS code and commodity from GET /v1/tools/drayage/hs
SSL code from GET /v1/tools/drayage/ssl

Request Body

Field	Type	Required	Description
`operationType`	string	Yes	`"Import"` or `"Export"`
`uom`	string	No	Unit of measure matching the quote. Accepts `"US"` or `"METRIC"`. Defaults to `"US"` if omitted or `null`
`bookingUserEmail`	string	Yes	Email of the user submitting the booking
`quoteNumber`	integer	Yes	From the drayage quote response
`rateNumber`	integer	Yes	Selected rate ID from the quote response
`customerNumber`	integer	Yes	Business identifier for your customer. Retrieve from `GET /v1/customers`
`customerBsn`	integer	Yes	Must match the value used during the quote
`load`	object	Yes	Container and cargo details
`terminal`	object	Yes	Port or rail terminal details
`shipperConsignee`	object	Yes	Pickup or delivery location (depends on `operationType`)
`container`	object	Yes	Steamship Line and booking number

Field Reference

operationType

Value	Description
`"Import"`	Container moving inbound from port to warehouse
`"Export"`	Container moving outbound from warehouse to port

uom

Value	Description
`"US"`	Weight in pounds (lb) — default
`"METRIC"`	Weight in metric units

If omitted or null, the API defaults to "US".
The uom used here must match the value used in the corresponding Quote request. A mismatch will cause a validation error because the shipment measurements no longer match the original quote.

UOM mismatch error — returned if the booking UOM differs from the quote UOM:

{
  "data": null,
  "errors": {
    "type": "https://httpstatuses.com/400",
    "title": "connect_validation_error",
    "status": 400,
    "detail": "Booking Request differ from Quote Request, mismatched values:\n- load.weight",
    "code": "connect_validation_error"
  }
}

load

All values must match exactly what was used during the quote.

Field	Description
`containerType`	Must match the container type from the quote
`containerLength`	Must match the container length from the quote
`hsCode`	HS code from `GET /v1/tools/drayage/hs` — use the `hsCode` field
`commodity`	Commodity description from `GET /v1/tools/drayage/hs` — use the `description` field
`weight`	Total container weight — must match the quote
`pieces`	Number of pieces the container holds

"load": {
  "containerType": "Container",
  "containerLength": 20,
  "hsCode": "101",
  "commodity": "Horses, asses, mules and hinnies; live",
  "weight": 1032,
  "pieces": 1
}

terminal

Retrieve terminal data from GET /v1/tools/drayage/terminals?marketZipCode={zipcode}.

Booking Field	Terminal Endpoint Field
`name`	`name`
`addressLine1`	`address1`
`city`	`city`
`state`	`state`
`zipCode`	`zipCode`
`country`	Hardcode `"US"`
`contactPhone`	`contactPhone`
`contactName`	`contactName`
`etaetd`	Estimated arrival/departure datetime (provided by customer)

"terminal": {
  "name": "Seagirt Marine Terminal",
  "addressLine1": "2600 BROENING HWY",
  "city": "BALTIMORE",
  "state": "MD",
  "zipCode": "21224",
  "country": "US",
  "contactPhone": "(410) 288-8602",
  "contactName": "Customer Service",
  "etaetd": "2026-05-12T05:00:00.000Z"
}

shipperConsignee

The shipperConsignee object represents different locations depending on operationType:

Import → delivery (consignee) location
Export → pickup (shipper) location

Field	Description
`name`	Name of the shipper or consignee
`addressLine1`	Full street address
`city`	City
`state`	State code (e.g., `"PA"`)
`zipCode`	Postal code
`country`	Country code
`contactName`	Contact person name
`contactPhone`	Contact phone number
`contactEmail`	Contact email address
`schedule`	`"Pickup Window"` or `"Appointment Required"`
`timeFrom`	string (nullable) — Start of the pickup window, e.g. `"09:00"`. Only applicable when `schedule` is `"Pickup Window"`
`timeTo`	string (nullable) — End of the pickup window, e.g. `"15:00"`. Only applicable when `schedule` is `"Pickup Window"`
`date`	datetime (nullable) — Pickup window date in ISO 8601 format. Only applicable when `schedule` is `"Pickup Window"`

note

timeFrom, timeTo, and date are only applicable when schedule is set to "Pickup Window". All three fields are nullable.

container

Field	Description
`ssl`	Steamship Line code — use the `code` value from `GET /v1/tools/drayage/ssl`
`bookingNumber`	Booking/reference number provided by the carrier or SSL

"container": {
  "ssl": "Alaska Marine Lines",
  "bookingNumber": "1234"
}

Request Example

{
  "operationType": "Import",
  "uom": "US",
  "bookingUserEmail": "example@email.com",
  "quoteNumber": 8917403,
  "rateNumber": 1,
  "customerNumber": "YOUR_CUSTOMER_NUMBER",
  "customerBsn": "YOUR_CUSTOMER_BSN",
  "load": {
    "containerType": "Container",
    "containerLength": 20,
    "hsCode": "101",
    "commodity": "Horses, asses, mules and hinnies; live",
    "weight": 1032,
    "pieces": 1
  },
  "terminal": {
    "name": "Seagirt Marine Terminal",
    "addressLine1": "2600 BROENING HWY",
    "city": "BALTIMORE",
    "state": "MD",
    "zipCode": "21224",
    "country": "US",
    "contactPhone": "(410) 288-8602",
    "contactName": "Customer Service",
    "etaetd": "2026-05-12T05:00:00.000Z"
  },
  "shipperConsignee": {
    "name": "Customer A",
    "addressLine1": "Warehouse 22, PA",
    "city": "HOUSTON",
    "state": "PA",
    "zipCode": "15342",
    "country": "US",
    "contactName": "Customer B",
    "contactPhone": "(410) 398-8602",
    "contactEmail": "customer@example.com",
    "schedule": "Pickup Window",
    "timeFrom": "09:00",
    "timeTo": "15:00",
    "date": "2026-06-23T05:00:00.000Z"
  },
  "container": {
    "ssl": "Alaska Marine Lines",
    "bookingNumber": "1234"
  }
}

Response

{
  "data": {
    "orderNumber": 20021859,
    "bolNumber": "46118",
    "documents": [
      {
        "docType": "BillOfLading",
        "url": "https://shipprimus.com/Documents/BOL_46118.pdf",
        "fileName": "BOL_46118.pdf",
        "extension": ".pdf",
        "contentType": "application/x-download"
      },
      {
        "docType": "ShippingLabel",
        "url": "https://shipprimus.com/Documents/LABEL_46118.pdf",
        "fileName": "LABEL_46118.pdf",
        "extension": ".pdf",
        "contentType": "application/x-download"
      }
    ]
  },
  "errors": null
}

Key Response Fields

Field	Description
`orderNumber`	Unique identifier for the created booking order
`bolNumber`	Bill of Lading number
`documents`	Generated shipping documents
`documents[].docType`	`"BillOfLading"` or `"ShippingLabel"`
`documents[].url`	URL to access or download the document

Next Steps

OTR Quote → — Explore Over The Road quoting
Tools → — Reference endpoints used in drayage workflows

Prerequisites​

Request Body​

Field Reference​

operationType​

uom​

load​

terminal​

shipperConsignee​

container​

Request Example​

Response​

Key Response Fields​

Next Steps​