> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tybritelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate shipping rates

> Returns quotes from every courier serving the route, sorted by price then
courier tier. The platform commission is already included in
`total_price`. Each `quote_id` is valid for 2 minutes and is required to
create a shipment.

**Precise pricing by location.** For each endpoint you may pass `zone` (a named
pricing area), exact `lat`/`lng` coordinates, or a free-form `place` string —
coordinates take precedence, then a place name is resolved to coordinates
automatically. When coordinates are supplied, each courier's price is matched to
the bounded service area the point falls in (more accurate than a city name alone).
`city` is always required as the coarse filter.

**Door-delivery distance charge.** When `delivery_method` is `last_mile` (door
delivery) and the destination lies beyond a courier's service area, the quote may
include a `distance_overage` — a courier-set surcharge for distance past the area,
shown in `breakdown.distance_overage`. Pickup-station deliveries are never charged
this surcharge.




## OpenAPI

````yaml /tldp/openapi.yaml post /v1/rates/calculate
openapi: 3.1.0
info:
  title: TLDP API
  version: 1.0.0
  description: >
    # Tybrite Logistics Developer Platform (TLDP) API


    The unified logistics API — one integration aggregates many courier

    services (rates, shipment creation, real-time tracking, proof of delivery,

    webhooks). "Stripe for logistics."


    ## Authentication

    All requests use API-key bearer auth. Keys are dual-key:

    - **Secret** (`tybrite_sk_live_*` / `tybrite_sk_test_*`) — full read/write.

    - **Publishable** (`tybrite_pk_live_*` / `tybrite_pk_test_*`) — read-only.


    ```

    Authorization: Bearer tybrite_sk_live_...

    ```


    `_live_` keys hit production; `_test_` keys hit the sandbox.


    ## Rate limits

    Authenticated endpoints are limited **per API key** (the `/v1` API is
    server-to-server —

    your backend holds the key — so the key is the identity). Fixed 60-second
    window:

    - **Production: 120 requests / minute / key**

    - **Sandbox: 30 requests / minute / key** (throttled harder for testing)


    The public tracking endpoint (no key) is limited **per IP** (60 / minute /
    IP).


    Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and

    `X-RateLimit-Reset` (unix epoch seconds). Exceeding the window returns

    **429** `rate_limit_exceeded`.


    ## Status code conventions

    - **201 Created** — a POST that creates a new resource (`POST /v1/orders`,
      `/v1/shipments`, `…/fulfil`, `…/fulfil-on-demand`, `POST /v1/webhooks`).
    - **200 OK** — reads, and POSTs that mutate without creating (`…/cancel`),
    or an
      **idempotent replay** (e.g. `POST /v1/shipments` with a reused `Idempotency-Key`
      returns the original shipment as 200, not a duplicate).
    - **202 Accepted** — work queued asynchronously (`POST
    /v1/webhooks/{id}/test`).


    ## Idempotency

    Write endpoints accept an `Idempotency-Key` header; retrying with the same
    key

    returns the original result instead of creating a duplicate.


    ## Caching

    Read endpoints whose body is the same for everyone — **public tracking**
    (~15s) and

    **coverage zones** (~5min) — are edge-cached and ETag-validated. Each
    returns `ETag`,

    `Cache-Control`, and `X-Cache` (`HIT`/`MISS`). Send the `ETag` back as
    `If-None-Match` to

    get a **304 Not Modified** (empty body) when the resource is unchanged —
    cheaper for you and

    for us. Per-tenant/authed data is never edge-cached.


    ## Webhook events — two layers, decoupled on purpose

    Subscribe at `POST /v1/webhooks`. Events live at **two distinct layers**
    that answer

    different questions — subscribe to whichever you need:


    - **`order.*` = business / commitment state** (one event per transition). An
    order is the
      thing your buyer placed; these tell you where it is in *your* fulfilment workflow.
      - `order.created` — an order was pushed/placed.
      - `order.fulfilled` — the merchant committed the order to delivery and **a shipment now
        exists for it**. Fires **once**. Use this to mark your order "shipping" and stop allowing
        buyer edits.
      - `order.cancelled` — the order was cancelled (and any not-yet-picked-up shipment with it).
      - *(returns)* `return.requested`, `return.approved`, `return.rejected`, `return.received`,
        `return.refunded`, `return.exchanged` — the reverse-logistics lifecycle.

    - **`shipment.*` = physical-delivery telemetry** (many events as the parcel
    moves). This is
      the play-by-play emitted as the rider advances status: `shipment.created`,
      `shipment.payment_confirmed`, `shipment.assigned`, `shipment.picked_up`,
      `shipment.in_transit`, `shipment.out_for_delivery`, `shipment.delivered`,
      `shipment.failed`, `shipment.cancelled`. Subscribe for live tracking / proof of delivery.

    - **`payment.*`**: `payment.pending_settlement`, `payment.settled`.


    **Relationship:** an order has exactly **one** `order.fulfilled`, but
    **many** `shipment.*`

    updates underneath it. They are deliberately decoupled: if you only track
    order state,

    subscribe to `order.*`; if you want live movement, subscribe to
    `shipment.*`. Note that

    **order-less direct shipments** (created via `POST /v1/shipments` with no
    order) emit

    `shipment.*` only — never `order.*`. Conversely an order that hasn't been
    fulfilled yet has

    `order.*` but no `shipment.*`.


    Every delivery is HMAC-signed (`TLDP-Signature: t=…,v1=…`, HMAC-SHA256 of
    `${t}.${body}`

    with your endpoint's `signing_secret`). Respond `2xx` to acknowledge.


    ## Errors

    Errors return `{ "error": { "code", "message", "details?" } }` with a
    conventional

    HTTP status. Common codes: `invalid_request` (400), `unauthorized` /

    `invalid_api_key` (401), `forbidden` / `account_inactive` (403), `not_found`
    (404),

    `cannot_fulfil` / `cannot_cancel` / `cannot_edit` (409),
    `rate_limit_exceeded` (429),

    `server_error` (500).
  contact:
    name: TLDP Developer Support
    email: developers@tybritelabs.com
  license:
    name: Proprietary
    url: https://tybritelabs.com/terms
servers:
  - url: https://api.tybritelabs.com/logistics
    description: Production (use _live_ keys) and Sandbox (use _test_ keys)
security:
  - BearerAuth: []
tags:
  - name: Rates
    description: Calculate shipping rates across couriers and list coverage zones.
  - name: Orders
    description: Push customer orders from your store and fulfil them with shipments.
  - name: Returns
    description: >-
      Returns & exchanges — request, approve, receive, and resolve
      (refund/exchange).
  - name: Shipments
    description: Create, retrieve, and cancel shipments.
  - name: Tracking
    description: Public and authenticated shipment tracking.
  - name: Proof of Delivery
    description: Retrieve proof of delivery for delivered shipments.
  - name: Webhooks
    description: Manage webhook endpoints and test deliveries.
  - name: System
    description: Health and service metadata.
externalDocs:
  description: TLDP Documentation
  url: https://docs.tybritelabs.com/tldp
paths:
  /v1/rates/calculate:
    post:
      tags:
        - Rates
      summary: Calculate shipping rates
      description: >
        Returns quotes from every courier serving the route, sorted by price
        then

        courier tier. The platform commission is already included in

        `total_price`. Each `quote_id` is valid for 2 minutes and is required to

        create a shipment.


        **Precise pricing by location.** For each endpoint you may pass `zone`
        (a named

        pricing area), exact `lat`/`lng` coordinates, or a free-form `place`
        string —

        coordinates take precedence, then a place name is resolved to
        coordinates

        automatically. When coordinates are supplied, each courier's price is
        matched to

        the bounded service area the point falls in (more accurate than a city
        name alone).

        `city` is always required as the coarse filter.


        **Door-delivery distance charge.** When `delivery_method` is `last_mile`
        (door

        delivery) and the destination lies beyond a courier's service area, the
        quote may

        include a `distance_overage` — a courier-set surcharge for distance past
        the area,

        shown in `breakdown.distance_overage`. Pickup-station deliveries are
        never charged

        this surcharge.
      operationId: calculateRates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - origin
                - destination
                - weight_kg
              properties:
                origin:
                  type: object
                  required:
                    - city
                  properties:
                    city:
                      type: string
                    zone:
                      type: string
                      description: Named pricing area within the city.
                    place:
                      type: string
                      description: Free-form place/area, resolved to coordinates.
                    lat:
                      type: number
                      description: >-
                        Latitude; takes precedence over place/zone for area
                        matching.
                    lng:
                      type: number
                      description: >-
                        Longitude; takes precedence over place/zone for area
                        matching.
                destination:
                  type: object
                  required:
                    - city
                  properties:
                    city:
                      type: string
                    zone:
                      type: string
                      description: Named pricing area within the city.
                    place:
                      type: string
                      description: Free-form place/area, resolved to coordinates.
                    lat:
                      type: number
                      description: >-
                        Latitude; takes precedence over place/zone for area
                        matching.
                    lng:
                      type: number
                      description: >-
                        Longitude; takes precedence over place/zone for area
                        matching.
                weight_kg:
                  type: number
                  example: 5
                declared_value:
                  type: number
                service_level:
                  $ref: '#/components/schemas/ServiceLevel'
                delivery_method:
                  type: string
                  enum:
                    - last_mile
                    - pickup
                  default: last_mile
                  description: >-
                    `last_mile` = delivered to the recipient's door (may incur a
                    distance charge); `pickup` = collected at a pickup station
                    (no distance charge).
                special_flags:
                  type: array
                  items:
                    type: string
                    example: fragile
      responses:
        '200':
          description: Available quotes.
          headers:
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            Tybrite-Environment:
              $ref: '#/components/headers/Tybrite-Environment'
          content:
            application/json:
              schema:
                type: object
                properties:
                  quotes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                      count:
                        type: integer
              example:
                quotes:
                  - quote_id: quote_1c80aeaced2846beb4d6a02ecd08ce19
                    courier_id: 6a2d4db2-c385-47ba-a146-a96856f6b199
                    courier_name: Sendy
                    courier_tier: gold
                    service_level: standard
                    total_price: 291.5
                    currency: KES
                    estimated_delivery_hours: 24
                    estimated_delivery_date: '2026-08-25T08:51:56.474317+00:00'
                    breakdown:
                      base_rate: 220
                      weight_surcharge: 45
                      zone_addon: 0
                      service_multiplier: 1
                      special_surcharges: '[]'
                      distance_overage: 0
                      courier_subtotal: 265
                      platform_fee: 26.5
                    valid_until: '2026-08-24T08:53:56.474317+00:00'
                  - quote_id: quote_0008992ff6114ec8b5a5c9e888cc3377
                    courier_id: 6a2d4db2-c385-47ba-a146-a96856f6b199
                    courier_name: Sendy
                    courier_tier: gold
                    service_level: same_day
                    total_price: 772.2
                    currency: KES
                    estimated_delivery_hours: 6
                    estimated_delivery_date: '2026-08-24T14:51:56.474317+00:00'
                    breakdown:
                      base_rate: 300
                      weight_surcharge: 100
                      zone_addon: 50
                      service_multiplier: 1.2
                      special_surcharges: '[]'
                      distance_overage: 0
                      courier_subtotal: 702
                      platform_fee: 70.2
                    valid_until: '2026-08-24T08:53:56.474317+00:00'
                  - quote_id: quote_59e736831904450cbd29408a511d83b3
                    courier_id: 180f9109-0cd9-439d-8cba-9c7442515455
                    courier_name: G4S
                    courier_tier: gold
                    service_level: express
                    total_price: 676.5
                    currency: KES
                    estimated_delivery_hours: 8
                    estimated_delivery_date: '2026-08-24T16:51:56.474317+00:00'
                    breakdown:
                      base_rate: 350
                      weight_surcharge: 60
                      zone_addon: 0
                      service_multiplier: 1.5
                      special_surcharges: '[]'
                      distance_overage: 0
                      courier_subtotal: 615
                      platform_fee: 61.5
                    valid_until: '2026-08-24T08:53:56.474317+00:00'
                  - quote_id: quote_008dcc973c5744539c9b6608022f7477
                    courier_id: 180f9109-0cd9-439d-8cba-9c7442515455
                    courier_name: G4S
                    courier_tier: gold
                    service_level: standard
                    total_price: 264
                    currency: KES
                    estimated_delivery_hours: 24
                    estimated_delivery_date: '2026-08-25T08:51:56.474317+00:00'
                    breakdown:
                      base_rate: 200
                      weight_surcharge: 40
                      zone_addon: 0
                      service_multiplier: 1
                      special_surcharges: '[]'
                      distance_overage: 0
                      courier_subtotal: 240
                      platform_fee: 24
                    valid_until: '2026-08-24T08:53:56.474317+00:00'
                meta:
                  request_id: req_e7e41a955ae2417a82c5053c
                  count: 4
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    ServiceLevel:
      type: string
      enum:
        - economy
        - standard
        - express
        - same_day
        - overnight
    Quote:
      type: object
      properties:
        quote_id:
          type: string
          example: quote_abc123
        courier_id:
          type: string
          format: uuid
        courier_name:
          type: string
          example: G4S
        courier_tier:
          type: string
          enum:
            - bronze
            - silver
            - gold
        service_level:
          $ref: '#/components/schemas/ServiceLevel'
        total_price:
          type: number
          example: 462
        currency:
          type: string
          example: KES
        estimated_delivery_hours:
          type: integer
        estimated_delivery_date:
          type: string
          format: date-time
        breakdown:
          $ref: '#/components/schemas/RateBreakdown'
        valid_until:
          type: string
          format: date-time
          description: Quote expires 2 minutes after creation.
    RateBreakdown:
      type: object
      properties:
        base_rate:
          type: number
        weight_surcharge:
          type: number
        zone_addon:
          type: number
        service_multiplier:
          type: number
        special_surcharges:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              amount:
                type: number
        distance_overage:
          type: number
          description: >-
            Door-delivery surcharge for distance beyond the courier's service
            area (0 for pickup or within the area).
        courier_subtotal:
          type: number
        platform_fee:
          type: number
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
            details:
              type: object
              additionalProperties: true
            request_id:
              type: string
          required:
            - code
            - message
      required:
        - error
  headers:
    X-RateLimit-Remaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
    Tybrite-Environment:
      description: The environment the key resolved to (production | sandbox).
      schema:
        type: string
        enum:
          - production
          - sandbox
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix epoch (seconds) when the window resets.
      schema:
        type: integer
  responses:
    BadRequest:
      description: Invalid request — missing or malformed parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_request:
              summary: Missing required field
              value:
                error:
                  code: invalid_request
                  message: recipient {name,phone,address,city} required
            no_coverage:
              summary: No courier covers this route
              value:
                error:
                  code: no_coverage
                  message: No courier serves the requested origin/destination.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              summary: No Authorization header
              value:
                error:
                  code: unauthorized
                  message: Missing or invalid Authorization header
            invalid_api_key:
              summary: Key revoked or wrong environment
              value:
                error:
                  code: invalid_api_key
                  message: API key is invalid or revoked
    Forbidden:
      description: The key lacks the required scope, or the account is inactive.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              summary: Publishable key used on a write endpoint
              value:
                error:
                  code: forbidden
                  message: This endpoint requires a secret (sk_) key with write scope.
            account_inactive:
              summary: Company account disabled
              value:
                error:
                  code: account_inactive
                  message: Company account is inactive
    NotFound:
      description: The requested resource does not exist (or isn't yours).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Order not found
    RateLimited:
      description: Rate limit exceeded for the current window.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limit_exceeded
              message: Too many requests. Retry after the window resets.
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: server_error
              message: An unexpected error occurred. Try again or contact support.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tybrite_sk_live_* or tybrite_pk_live_*
      description: >
        API key as a bearer token. Secret keys (sk_) allow writes; publishable
        keys (pk_) are read-only. live = production, test = sandbox.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.