External API and webhooks

Calculate a shipment quote

Price a shipment for an active customer account before creating it. Quotes are calculations, not bookings: RouteHut does not create a shipment or address-book record.

curl https://api.routehut.example.com/api/v1/external/quotes \
  -X POST \
  -H "Authorization: Bearer opk_your_credential" \
  -H "Content-Type: application/json" \
  --data '{
    "quote": {
      "customer_account_code": "ACME-RETAIL",
      "collection_address": { "line1": "1 Dock Road", "city": "Cape Town", "country_code": "ZA", "coordinates": { "latitude": -33.9249, "longitude": 18.4241 } },
      "delivery_address": { "line1": "2 Loop Street", "city": "Johannesburg", "country_code": "ZA" },
      "parcels": [{ "weight_kg": "2.5", "length_cm": "20", "width_cm": "15", "height_cm": "10" }]
    }
  }'

Create a shipment

Create a draft shipment using the customer’s stable `customer_account_code`. Collection and delivery addresses become address-book records for that customer. Internal RouteHut IDs are never accepted.

curl https://api.routehut.example.com/api/v1/external/shipments \
  -X POST \
  -H "Authorization: Bearer opk_your_credential" \
  -H "Idempotency-Key: order-100045" \
  -H "Content-Type: application/json" \
  --data '{
    "shipment": {
      "customer_account_code": "ACME-RETAIL",
      "shipment_number": "ACME-100045",
      "collection_address": { "line1": "1 Dock Road", "city": "Cape Town", "country_code": "ZA" },
      "delivery_address": { "line1": "2 Loop Street", "city": "Johannesburg", "country_code": "ZA" },
      "parcels": [{ "barcode": "ACME-100045-1", "weight_kg": "2.5" }]
    }
  }'

Synchronize shipments

Use the keyset-paginated feed for an initial synchronization, then poll with `updated_since`. Follow `meta.next_cursor` until it is null. The feed is ordered by update time and shipment number.

curl "https://api.routehut.example.com/api/v1/external/shipments?limit=50&updated_since=2026-07-19T08:00:00Z" \
  -H "Authorization: Bearer opk_your_credential"

Read one shipment

Retrieve the current operational shipment record when an integration already knows its shipment number. The response includes the customer account code, collection and delivery addresses, and parcels for that tenant only.

Cancel before operational handoff

Draft and untouched booked shipments can be cancelled through the external API. RouteHut voids pending charges, returns prepaid funds through auditable wallet credits, and records one cancellation event. Invoiced, assigned, routed, manifested, or held shipments require an operational exception workflow.

Read customer-safe tracking

Retrieve the current status and tracking timeline without exposing the public tracking token. This is the integration-friendly counterpart to the customer tracking page.

Proof of delivery

Read POD metadata, then request a short-lived attachment URL from the matching endpoint when evidence is attached. URL issuance is audit recorded.

List supported webhook events

Discover the versioned event names available to RouteHut subscriptions. This endpoint does not create, update, or reveal subscriptions, signing secrets, or delivery payloads.

List subscription configuration with opaque identifiers and an opaque keyset cursor. Signing secrets and delivery attempts are never included.

Retrieve one tenant-scoped subscription by its opaque identifier. Signing secrets are never returned by this read endpoint.

Pause, resume, or adjust subscription configuration with webhooks:write and an Idempotency-Key. Signing secrets remain unchanged and are never returned.

Queue a signed webhook.test.v1 delivery with webhooks:write and an Idempotency-Key. It is available only while the subscription is active.

Rotate a signing secret with webhooks:write and an Idempotency-Key. Store the returned replacement immediately; it is not available from future read requests.

Inspect delivery status through an opaque-cursor history feed with webhooks:read. It excludes target URLs, request headers, request bodies, and internal identifiers.

Replay an exhausted delivery with webhooks:write and an Idempotency-Key. The subscription must be active; the replay receives a new opaque delivery identifier.

Create a subscription with webhooks:write and an Idempotency-Key. The creation response returns its signing secret once; later reads never reveal it.

curl https://api.routehut.example.com/api/v1/external/webhooks/events \
  -H "Authorization: Bearer opk_your_credential"

Synchronize the address book

Read customer-owned address-book entries by opaque address ID. Filter by customer_account_code when synchronizing one account, and follow meta.next_cursor for the next page.

Retrieve one customer-owned address-book entry when a synchronized opaque address ID needs to be refreshed. Internal staff IDs and unowned operational addresses are never exposed.

Create a customer-owned address-book entry with addresses:write and an Idempotency-Key. The customer account must be active in the credential tenant.

Update an unused address-book entry with addresses:write and an Idempotency-Key. Addresses referenced by shipment history cannot be changed; create a replacement instead.

Synchronize customers and contacts

Use opaque customer and contact IDs for tenant-scoped synchronization. Customer reads and contact reads require customers:read; creates and operational updates require customers:write plus an Idempotency-Key.

Create a customer with its partner account code. Account codes and billing modes are not externally mutable.

Update the customer name or operational status without changing financial configuration.

Follow meta.next_cursor through the bounded contact feed; the maximum page is 100.

Tracking notifications require an email address. Contacts and consent state are never returned from the public tracking surface.

Submit bulk shipment imports

Queue a bounded JSON batch with shipments:write and an Idempotency-Key. Each partner row has a unique row_key; processing records independent row outcomes.

Poll import status and counters with shipments:read, then follow the row outcome feed with its opaque cursor. Submitted shipment data is never returned.

Book a draft shipment

Use shipments:write and an Idempotency-Key to confirm an existing draft. Booking applies the tenant's credit or prepaid funding rules and cannot be repeated outside idempotent replay.

Synchronize invoices

Use the billing feed for issued, paid, and voided invoice updates. It uses the same opaque-cursor pattern as shipment synchronization; filter with updated_since and follow meta.next_cursor.

curl "https://api.routehut.example.com/api/v1/external/invoices?limit=50&updated_since=2026-07-19T08:00:00Z" \
  -H "Authorization: Bearer opk_your_credential"

Retrieve /external/invoices/{invoice_number} when you need its line-level shipment references and charges. Internal IDs, contacts, addresses, and payment-provider data remain private.