BigBlue Track & Trace

Overview

Fetches tracking records for a given Bigblue order. Used in WISMO flows to retrieve carrier, tracking URL, current delivery status, and the full event history for a shipment.

Built for the Fussy 3PL migration (Spring EU / Whistl UK via Bigblue).

Endpoint

POST https://api.bigblue.co/bigblue.storeapi.v1.PublicAPI/ListTrackings

Auth: Authorization: Bearer <api_key>

Inputs

Only one lookup method is needed. For WISMO flows, prefer external_order + store_id since the Shopify order ID is already available from the OMS extraction step.

Lookup Methods

By tracking number

input_type = "tracking_number"
identifier = "JD0003600003800041874"

By Bigblue order ID

input_type = "order_id"
identifier = "FUSSS1FZ2609"  # 12-char alphanumeric

By Shopify order ID (preferred for WISMO)

input_type = "external_order"
identifier = "3052609"       # Shopify order ID
store_id   = "<fussy_store_id>"

Response Structure

{
  "trackings": [
    {
      "carrier": "whistl",
      "tracking_url": "https://...",
      "update_time": "2026-05-20T14:32:00Z",
      "status": {
        "code": "IN_TRANSIT",
        "message": "In Transit"
      },
      "events": [
        {
          "status_code": "IN_TRANSIT",
          "message": "Parcel collected by carrier",
          "timestamp": "2026-05-20T10:00:00Z"
        }
      ]
    }
  ]
}

Status codes

Retry Logic

The handler retries automatically on transient failures:

• 429 Rate limited — respects Retry-After header if present, otherwise backs off by 2 × attempt seconds
• 5xx Server error — exponential backoff (2^attempt seconds)
• Connection error / timeout — exponential backoff

Does not retry on 4xx client errors (400, 401, 404) — these indicate a bad request or bad auth and won't resolve on retry.

Raises RuntimeError with full response details after all retries exhausted, so failures are visible in flow logs.

Error Responses