Skip to main content
A Booking turns an Open Shipment — a Shipment created with the information a carrier needs, but no tracking number yet — into a confirmed carrier booking. On success you receive the carrier-generated tracking number, the shipping label document(s), and, for PUDO deliveries, the confirmed location. Full field specs: API reference.
Booking requires account enablement — contact your account team. The carrier configuration you book with must be set up for outbound or return booking.

​
The flow

1

Create the Open Shipment

Use Create Shipment with the data the carrier requires — typically full to/from addresses (name, line1, postal code, city, country, phone), weight, and line items. Don’t set a tracking number; the booking assigns it.
2

Book it

Identify the Shipment by shipment_uuid or shipment_id, and name the carrier configuration:
carrier_reference selects the carrier configuration to book with (from Settings > Carriers; it must support booking). It’s optional when the Open Shipment already has a carrier — the booking then uses the Shipment’s own carrier_reference. When you provide one, the request’s value is used for the carrier booking — so either omit it or keep it consistent with the Shipment’s carrier; don’t send a conflicting value. Never send it as null or an empty string — omit it entirely instead.For a pickup/drop-off delivery, add pudo_location_uuid from the PUDO locations endpoint; the label is then routed to that location and the response echoes the confirmed location details.
3

Use the result

A successful booking returns booking_uuid, the carrier tracking_number, the booking status (booked, or return_initiated for returns), type_of_shipment (outbound/return), and the label(s) under documents — each with a download_url (1-hour expiry) and base64_content. Some carriers issue no label; documents is then an empty array.

​
Labels that arrive late (HTTP 299)

Some carriers generate labels asynchronously. The booking still succeeds — tracking number assigned, status booked — but the response is HTTP 299 and download_url / base64_content inside documents are null, with warnings telling you so. Fetch the label later: Never rebook to “retry” a 299 — the booking exists.

​
Booking validation errors

Booking uses its own error envelope: errors sits inside data next to the Shipment identifiers, and each entry carries a standard_error_message:
Errors for fields inside objects nest one level deeper (for example from_address.postal_code). Most booking errors mean the Open Shipment is missing something the carrier requires — fix it with Update Shipment and book again. Carrier-side failures surface as 500/503/504.
Carriers enforce their own field limits at booking — commonly ~35 characters per address line — stricter than what Create Shipment accepts. If a booking fails on address fields that passed creation, shorten them.