JBI API — Order Tracking (v3)

Endpoint: POST /customer/v3/tracking/{accountId}
Base URL: https://api.jbi.bike
Version: v3
Content-Type: application/json

Overview

This endpoint returns carrier tracking information for one or more of your orders. A single order can ship from multiple warehouse locations, and each location can produce multiple packages (tracking numbers). Results are grouped by location so you can see exactly what shipped from where.

You may look an order up by your own order number (CustomerOrderNo) or by JBI's order number (OrderId, returned in the response of the v3 Order Submission endpoint).

Optionally, add ?include=items to also receive the items and quantities that shipped from each location.

Authentication

Every request must include your API token in the request header.

Token-key: your-api-token-here

Your accountId and Token-key are provided by JBI. The token is validated per account — using a token that does not match the accountId in the URL will result in a 401 response.

URL Parameters

Example URL:

POST https://api.jbi.bike/customer/v3/tracking/10042

Query Parameters

Omit include and the response is exactly as documented before this option existed — nothing changes for existing integrations.

Example URL with items:

POST https://api.jbi.bike/customer/v3/tracking/10042?include=items

Unrecognised values in include are ignored rather than rejected, so requesting a section this API version does not yet support will not fail your request.

Request Body

The body must be a JSON array of lookup objects. Each object contains exactly one lookup key identifying the order. You may mix both key types in a single request.

[
  { "CustomerOrderNo": "1777255" },
  { "OrderId": "9844" }
]

Request Fields

Each object must contain exactly one of these keys with a non-empty string value.

Tip: Looking up by OrderId is the fastest path. Lookups by CustomerOrderNo are limited to orders placed within roughly the last two weeks.

Responses

Success (HTTP 200)

Returns an array with one entry per matched order. An order is returned once, with its tracking grouped by location. Orders that are not found or have not shipped yet are included with an empty locations array — they are never silently omitted.

{
  "success": true,
  "data": [
    {
      "orderId": "9844",
      "customerOrderNo": "1777255",
      "locations": [
        {
          "locID": 101,
          "packages": [
            { "trackingNumber": "1Z999AA10123456784", "carrierName": "UPS Ground", "shippedDate": "2025-06-01" },
            { "trackingNumber": "770123456789",        "carrierName": "FedEx Home", "shippedDate": "2025-06-02" }
          ]
        },
        {
          "locID": 104,
          "packages": [
            { "trackingNumber": "1Z999AA10199887766", "carrierName": "UPS Ground", "shippedDate": "2025-06-02" }
          ]
        }
      ]
    },
    {
      "orderId": null,
      "customerOrderNo": "1777256",
      "locations": []
    }
  ]
}

Success with ?include=items (HTTP 200)

The same response, with an items array added to each location:

{
  "success": true,
  "data": [
    {
      "orderId": "9844",
      "customerOrderNo": "1777255",
      "locations": [
        {
          "locID": 101,
          "packages": [
            { "trackingNumber": "1Z999AA10123456784", "carrierName": "UPS Ground", "shippedDate": "2025-06-01" },
            { "trackingNumber": "770123456789",        "carrierName": "FedEx Home", "shippedDate": "2025-06-02" }
          ],
          "items": [
            { "itemId": "ABC-123", "quantity": 4 },
            { "itemId": "XYZ-9",   "quantity": 1 }
          ]
        }
      ]
    }
  ]
}

Response Fields

Top-level

Order Tracking Object

Location Object

Package Object

Item Object

Returned only when ?include=items is supplied.

Important: items are reported per location, not per package. We do not track which individual box a given item was placed in, so items sits alongside packages rather than inside it. The quantities describe everything that left that location for this order — across all of its tracking numbers combined.

Error Responses

All errors follow the same envelope structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

HTTP 400 — Bad Request

HTTP 401 — Unauthorized

HTTP 405 — Method Not Allowed

HTTP 422 — Unprocessable Entity

When validation fails the response includes a fields object identifying the offending index:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Each item must be an object with exactly one of: CustomerOrderNo, OrderId",
    "fields": {
      "[1]": "required|object|one-of:CustomerOrderNo,OrderId"
    }
  }
}

HTTP 500 — Server Error

Notes

• An order that has not shipped yet (or is not found) is returned with locations: [] rather than being omitted, so you can poll uniformly.
• The same physical order may be requested by both CustomerOrderNo and OrderId in one call; it is returned only once.
• Lookups by CustomerOrderNo are limited to orders placed within roughly the last two weeks. For older orders, look up by OrderId.
• The items array is opt-in via ?include=items. Without it the response is unchanged, and the extra lookup is not performed — so there is no added latency for callers that do not need item detail.
• Item quantities are aggregated per location: if a location shipped an item on more than one pick ticket, you receive a single line with the combined quantity.

Quick Reference

POST /customer/v3/tracking/{accountId} HTTP/1.1
Host: api.jbi.bike
Token-key: your-api-token-here
Content-Type: application/json

[
  { "CustomerOrderNo": "1777255" },
  { "OrderId": "9844" }
]

With shipped items included:

POST /customer/v3/tracking/{accountId}?include=items HTTP/1.1
Host: api.jbi.bike
Token-key: your-api-token-here
Content-Type: application/json

[
  { "CustomerOrderNo": "1777255" },
  { "OrderId": "9844" }
]

Document version: 1.1 — 2026-09-02 (added the optional ?include=items section)
For questions or to request API access, contact JBI.