Skip to main content
The OrdersService class (accessed via client.orders) is the heart of the delivery lifecycle. An order captures what you want delivered and to whom; fulfilment then turns it into a live shipment with a tracking number. You can fulfil through a courier (using a rate quote) or — for same-city deliveries — dispatch instantly to nearby independent riders.
Sandbox isolation: a tybrite_sk_test_* key runs every call in the sandbox environment — isolated from production, no real money moves, and any webhooks fire with livemode: false. Switch to a tybrite_sk_live_* key to go live.

createOrder

Creates a new order in the pending_fulfilment state. It records the recipient and the item(s) but does not yet dispatch anything — call fulfilOrder or fulfilOrderOnDemand to put it on the road.
Pass an idempotencyKey so a network retry can’t accidentally create two orders — a repeat call with the same key returns the original order.
Returns { order } — the wrapped order object. Read the id from order.id.

listOrders

Lists your orders, newest first. Page with limit (1–100, default 50) and offset; the response’s pagination block tells you whether more pages exist and the next_offset to request.
Returns { orders, pagination } — a page of orders plus { limit, offset, has_more, next_offset }.

getOrder

Fetches a single order by id, including its current status, recipient, items, and (once fulfilled) its linked shipment.
Returns the order object directly (not wrapped).

updateOrder

Edits an order’s reference, delivery method, recipient, or items.
An order can only be updated while it is still pending fulfilment. Once it has been fulfilled and a shipment exists, the order is locked.
Returns { order } — the updated, wrapped order object.

cancelOrder

Cancels an order. Provide an optional reason for your records and reporting.
Returns { order_id, status }.

fulfilOrder

Turns a pending order into a live courier shipment using a rate quote from client.rates.calculateRates.
Naming gotcha to remember: a quote from calculateRates exposes its id as quote_id, but fulfilOrder wants that value back under the key rate_quote_id. Read quote.quote_id, pass it as rate_quote_id.
Pass an idempotencyKey so a network retry can’t accidentally create two shipments for one order — a repeat call returns the original result.
Returns { order_id, shipment_id, tracking_number, tracking_url }.

onDemandQuote

For a same-city order, previews the available on-demand delivery tiers and what each would cost and take. On-demand routes the parcel to nearby independent riders rather than a scheduled courier.
Returns { tiers: [{ tier, eligible, reason?, fare?, eta_min? }] }.

fulfilOrderOnDemand

Dispatches the order to nearby independent riders for same-city delivery. Pick a tier from onDemandQuote, or omit it to use the default tier.
Returns { order_id, shipment_id, tracking_number, tracking_url, ... }. Once dispatched, follow the rider live with client.tracking.trackShipment.