Orders and Shipments: TLDP Data Model Explained

In TLDP, orders and shipments are distinct resources that model two different stages of a delivery workflow. An order captures the commercial intent — what needs to be delivered, to whom, and at what price — while a shipment is the physical manifestation of that intent, complete with a tracking number and an assigned courier. Understanding the boundary between the two lets you build flexible fulfilment flows, whether you want the full order lifecycle or a direct shipment creation path.

The Order-to-Shipment Flow

Creating an order does not immediately dispatch a courier. Fulfilment is a deliberate second step, giving you time to validate, quote, and confirm before committing to a delivery.

Create an order

Call POST /v1/orders (or client.orders.createOrder) with the recipient details, item description, and delivery method. The order enters the pending_fulfilment state.

Get a rate quote

Call POST /v1/rates/calculate to retrieve competitive quotes for the order’s route, weight, and service level. Select the quote that best fits your cost and speed requirements. Save the quote_id from the response.

Fulfil the order

Call POST /v1/orders/{id}/fulfil with your chosen rate_quote_id. TLDP creates a shipment, assigns a courier, and returns a tracking number. The order moves to the fulfilled state.

Track the shipment

Use the returned tracking_number to monitor delivery progress through the tracking endpoints or webhooks.

Order States

State	Description
`pending_fulfilment`	The order has been recorded but not yet fulfilled. No courier is assigned.
`fulfilled`	A shipment has been created from the order. A tracking number exists.
`cancelled`	The order was cancelled before or after fulfilment. Any associated shipment that has not yet been picked up is also cancelled.

Delivery Methods

When creating an order, you specify a delivery_method that determines how the recipient receives their parcel.

last_mile

A courier collects the parcel from your origin and delivers it directly to the recipient’s door address. Use this when your customer expects home or office delivery without travelling to collect.

station_pickup

The parcel is transported to the nearest TLDP-affiliated pickup station. The recipient receives a notification and collects at their convenience. Typically lower cost and suitable when door delivery isn’t practical.

On-Demand Fulfilment

For time-sensitive flows, use on-demand fulfilment to dispatch directly to nearby independent drivers without a separate rates call. TLDP offers four on-demand tiers:

Tier	Description
`express`	Dedicate a trip now (same-city only, highest fare).
`on_the_way`	A driver already heading in the right direction carries it — cheapest option.
`scheduled`	Flexible window; the parcel rides along a trip. Default tier.
`driver_rate_card`	Use a specific driver’s own posted rate.

Two-step (recommended)
On-demand (one step)

import { TLDP } from '@tybrite-labs/tldp-sdk';

const client = new TLDP({ apiKey: 'tybrite_sk_live_…' });

// Step 1 — Get a quote
const { quotes } = await client.rates.calculateRates({
  requestBody: {
    origin: { city: 'Nairobi' },
    destination: { city: 'Mombasa' },
    weight_kg: 2.5,
    service_level: 'standard',
  },
});

const bestQuote = quotes[0]; // pick the quote that fits your criteria

// Step 2 — Fulfil the order with the chosen quote
const { shipment_id, tracking_number } = await client.orders.fulfilOrder({
  orderId: 'ord_abc123',
  requestBody: {
    rate_quote_id: bestQuote.quote_id,
  },
});

import { TLDP } from '@tybrite-labs/tldp-sdk';

const client = new TLDP({ apiKey: 'tybrite_sk_live_…' });

// Dispatch directly to nearby on-demand drivers
const { tracking_number, tier, fare } = await client.orders.fulfilOrderOnDemand({
  orderId: 'ord_abc123',
  requestBody: {
    tier: 'express',
  },
});

console.log(tracking_number); // ready immediately
console.log(`${tier} tier — fare: ${fare}`);

On-demand fulfilment broadcasts an offer to matching online drivers at the chosen tier — the first driver to accept picks it up. The price is locked in atomically, so you will never see a quote expire between selection and fulfilment.

TypeScript Examples

Creating an order

import { TLDP } from '@tybrite-labs/tldp-sdk';

const client = new TLDP({ apiKey: 'tybrite_sk_live_…' });

const { order } = await client.orders.createOrder({
  requestBody: {
    reference: 'ORDER-1042',
    delivery_method: 'last_mile',
    recipient: {
      name: 'Amina N.',
      phone: '+254700000000',
      address: '14 Mama Ngina St',
      city: 'Mombasa',
    },
    item: {
      description: 'Books',
      weight_kg: 2.5,
    },
  },
});

console.log(order.id);     // ord_…
console.log(order.status); // pending_fulfilment

Creating a shipment directly

import { TLDP } from '@tybrite-labs/tldp-sdk';

const client = new TLDP({ apiKey: 'tybrite_sk_live_…' });

const { shipment } = await client.shipments.createShipment({
  requestBody: {
    rate_quote_id: 'quote_abc123',
    recipient: {
      name: 'Amina N.',
      phone: '+254700000000',
      address: '14 Mama Ngina St',
      city: 'Mombasa',
    },
    parcel: {
      description: 'Books',
      weight_kg: 2.5,
    },
  },
});

console.log(shipment.tracking_number); // TLDP-…
console.log(shipment.status);          // pending

Order Flow vs. Direct Shipment Creation

Use the right path for your integration needs:

When to use the order flow

Choose the order flow (POST /v1/orders → fulfil) when:

Your platform has a commerce layer and you want to record the buyer’s intent before committing to a courier
You need to present rate options to the sender or customer before confirming
You want order-level state tracking (pending_fulfilment, fulfilled, cancelled) alongside shipment tracking
You may need to cancel before fulfilment without having dispatched a courier

When to create a shipment directly

Use POST /v1/shipments directly when:

You already have a pre-selected rate quote and want to minimise round-trips
You are building a backend automation that doesn’t need order-level state — for example, bulk label generation
You are migrating from another logistics API and mapping directly to shipment objects fits your existing data model

Get Started

Core Concepts

Guides

TypeScript SDK

Orders and Shipments: TLDP Data Model Explained

The Order-to-Shipment Flow

Order States

Delivery Methods

last_mile

station_pickup

On-Demand Fulfilment

TypeScript Examples

Creating an order

Creating a shipment directly

Order Flow vs. Direct Shipment Creation

​The Order-to-Shipment Flow

​Order States

​Delivery Methods

last_mile

station_pickup

​On-Demand Fulfilment

​TypeScript Examples

​Creating an order

​Creating a shipment directly

​Order Flow vs. Direct Shipment Creation

The Order-to-Shipment Flow

Order States

Delivery Methods

On-Demand Fulfilment

TypeScript Examples

Creating an order

Creating a shipment directly

Order Flow vs. Direct Shipment Creation