Skip to main content
The ShipmentsService class (accessed via client.shipments) lets you create a shipment directly from a rate quote, skipping the separate order step. This is the fast path when you already know exactly what you’re sending and just want it picked up and delivered. For tracking a live shipment, see client.tracking.
Sandbox: a tybrite_sk_test_* key creates sandbox shipments — fully isolated from live data, with no real money or real courier pickups.

createShipment

Books a shipment in one call using a quote from client.rates.calculateRates. Use this when you don’t need a separate order record — the shipment is the unit of work.
Naming gotcha to remember: each rate quote exposes its id as quote_id, but createShipment expects that value under the key rate_quote_id. So you read quote.quote_id and pass it as rate_quote_id.
recipient.name, recipient.phone and recipient.address are required — they are stored on the shipment and appear on the label. A request missing any of them is rejected with a 400 naming the fields. The sender’s equivalents are optional and fall back to the quote’s origin. Passing an idempotencyKey makes the call safe to retry: repeating a key returns the shipment the first call created rather than booking a second one.
Always pass an idempotencyKey — on a transient network failure the SDK can retry safely and you’ll get the original shipment back instead of a duplicate booking.
Returns { shipment } — the wrapped shipment object, including its tracking_number and tracking_url.

getShipment

Fetches a shipment you own by id, with its current status, recipient, parcel, and courier assignment.
Returns { shipment } — wrapped.

cancelShipment

Cancels a shipment. Provide an optional reason for your records.
A shipment can only be cancelled before pickup. Once a courier or rider has collected the parcel, it can no longer be cancelled — use Returns to send it back instead.
Returns the cancellation result with the shipment’s new status.