Track Shipments and Containers

Create tracking requests for bill of lading, booking, and container numbers in the Terminal49 API and start receiving shipment milestone updates.

In this tutorial, you will create a tracking request. A tracking request tells Terminal49 which shipment or container to monitor.

Each tracking request needs two values:

• A Bill of Lading (BOL), booking number, or container number from the carrier.
• The carrier Standard Carrier Alpha Code (SCAC).

Don’t know the SCAC? Use the Auto-Detect Carrier endpoint to automatically identify the shipping line from your tracking number.

You can see a complete list of supported SCACs in row 2 of the Carrier Data Matrix.

Choose a tracking number

Supported numbers

1. Master Bill of Lading from the carrier (recommended)
2. Booking number from the carrier
3. Container number

• Container number tracking support across ocean carriers is sometimes more limited. Please refer to the Carrier Data Matrix to see which SCACs are compatible with Container number tracking.

Unsupported numbers

• House Bill of Lading (HBOL) numbers
• Customs entry numbers
• Seal numbers
• Internally generated numbers, such as purchase order numbers or customer reference numbers

What happens after you create one

Terminal49 works asynchronously:

1. You send a tracking request with a shipment identifier and SCAC.
2. Terminal49 accepts the request and returns a tracking_request.
3. Terminal49 monitors the carrier and creates shipment/container records as data becomes available.
4. If you have a webhook, Terminal49 sends updates whenever data changes.
5. You can list shipments and containers at any time.

How do you receive tracking request data?

You have two options. First, you can poll for updates.

Poll the GET /tracking_requests/{id} endpoint to check the status of your request. You only need the tracking request ID, which the API returns when you create the request.

The second option is to register a webhook so the API posts updates as they happen. This is more efficient and the preferred approach, but it requires some setup.

A webhook is a callback URL that receives HTTP POST requests from the Terminal49 API whenever tracking data changes.

When the Bill of Lading and SCAC match successfully, Terminal49 creates a shipment and sends the tracking_request.succeeded event to your webhook endpoint with the associated record.

If there is a problem, Terminal49 sends the tracking_request.failed event.

Authentication

The API uses a Token-prefixed API key in the Authorization header.

Sign in to Terminal49 and go to your account API settings to get your API token.

Send the token with each API request in the Authorization header:

Authorization: Token YOUR_API_KEY

How to create a tracking request

Replace YOUR_API_KEY, REQUEST_NUMBER, and SCAC before running this example.

const response = await fetch("https://api.terminal49.com/v2/tracking_requests", {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  },
  body: JSON.stringify({
    data: {
      type: "tracking_request",
      attributes: {
        request_type: "bill_of_lading",
        request_number: "REQUEST_NUMBER",
        scac: "SCAC"
      }
    }
  })
});

console.log(await response.json());

Anatomy of a tracking request response

The response confirms that Terminal49 accepted the request. A new request usually starts with status: "pending" while Terminal49 checks the carrier.

{
  "data": {
    "id": "478cd7c4-a603-4bdf-84d5-3341c37c43a3",
    "type": "tracking_request",
    "attributes": {
      "request_number": "xxxxxx",
      "request_type": "bill_of_lading",
      "scac": "MAEU",
      "ref_numbers": [],
      "created_at": "2020-09-17T16:13:30Z",
      "updated_at": "2020-09-17T17:13:30Z",
      "status": "pending",
      "failed_reason": null,
      "is_retrying": false,
      "retry_count": null
    },
    "relationships": {
      "tracked_object": {
        "data": null
      }
    },
    "links": {
      "self": "/v2/tracking_requests/478cd7c4-a603-4bdf-84d5-3341c37c43a3"
    }
  }
}

Note that if you try to track the same shipment, you will receive an error like this:

{
  "errors": [
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/request_number"
      },
      "title": "Unprocessable Entity",
      "detail": "Request number 'xxxxxxx' with scac 'MAEU' already exists in a tracking_request with a pending or created status",
      "code": "duplicate"
    }
  ]
}

Why so much JSON? (A note on JSON:API)

The Terminal49 API is JSON:API compliant. JSON:API libraries can translate the response into a full object model compatible with an ORM, which is powerful but produces larger, more structured payloads. If you parse JSON directly, this can feel verbose. For production use, consider adopting a JSON:API client library to get the most out of the format. For this tutorial, you will work with the data directly.

Try it: make a tracking request

Try it using the request maker below!

1. Enter your API token in the authorization header value.
2. Enter a value for the request_number and scac. The request number must be a shipping line booking or master bill of lading number. The SCAC must be a shipping line SCAC (see data sources for a list of valid SCACs).

Note that you can also access sample code in multiple languages by clicking the “Code Generation” below.

Tracking Request Troubleshooting

The most common issue people encounter is that they are entering the wrong number.

Check that you are entering a Bill of Lading number, booking number, or container number — not an internal reference from your company or freight forwarder. Verify the number by going to the carrier’s website and tracking the shipment with it. If that works and the SCAC is supported by Terminal49, you should be able to track it through the API.

If you are unsure of the correct SCAC, try the Auto-Detect Carrier endpoint first.

Sometimes the issue is on the shipping line’s side. Temporary network problems, unpopulated manifests, and other issues can occur. See the Tracking Request Retrying section for how Terminal49 handles these cases.

Rate limiting: You can create up to 100 tracking requests per minute.

You can always email us at [e-mail] if you have persistent issues.

{
  "method": "post",
  "url": "https://api.terminal49.com/v2/tracking_requests",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  },
  "body": "{\r\n  \"data\": {\r\n    \"attributes\": {\r\n      \"request_type\": \"bill_of_lading\",\r\n      \"request_number\": \"\",\r\n      \"scac\": \"\"\r\n    },\r\n    \"type\": \"tracking_request\"\r\n  }\r\n}"
}

Try it: list your active tracking requests

If you have not set up a webhook to receive status updates from the Terminal49 API, you need to poll manually to check whether the tracking request succeeded or failed.

Try it below. Click “Headers” and replace <YOUR_API_KEY> with your API key.

{
  "method": "get",
  "url": "https://api.terminal49.com/v2/tracking_requests",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  }
}

Next up: get your shipments

Now that you’ve made a tracking request, let’s see how you can list your shipments and retrieve the relevant data.

Go to this page to see different ways of initiating shipment tracking on Terminal49.