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 thepending_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.
idempotencyKey so a network retry can’t accidentally create two orders — a repeat call with the same key returns the original order.
{ order } — the wrapped order object. Read the id from order.id.
listOrders
Lists your orders, newest first. Page withlimit (1–100, default 50) and offset; the response’s pagination block tells you whether more pages exist and the next_offset to request.
{ 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.updateOrder
Edits an order’s reference, delivery method, recipient, or items.{ order } — the updated, wrapped order object.
cancelOrder
Cancels an order. Provide an optionalreason for your records and reporting.
{ order_id, status }.
fulfilOrder
Turns a pending order into a live courier shipment using a rate quote fromclient.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.{ 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.{ tiers: [{ tier, eligible, reason?, fare?, eta_min? }] }.
fulfilOrderOnDemand
Dispatches the order to nearby independent riders for same-city delivery. Pick atier from onDemandQuote, or omit it to use the default tier.
{ order_id, shipment_id, tracking_number, tracking_url, ... }. Once dispatched, follow the rider live with client.tracking.trackShipment.
