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.

What is a tracking request?

Your tracking request includes two pieces of data:

• Your Bill of Lading, Booking number, or container number from the carrier.
• The SCAC code for that carrier.

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.

What sort of numbers can I track?

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 numbers (HBOL)
• Customs entry numbers
• Seal numbers
• Internally generated numbers, for example PO numbers or customer reference numbers.

How do I use tracking requests?

Terminal49 is an event-based API, which means you can use it asynchronously. The general data flow is:

1. You send a tracking request to the API with your Bill of Lading number and SCAC.
2. The API confirms it received your tracking request and returns the shipment data available at that time.
3. After you submit a tracking request, Terminal49 automatically tracks the shipment and all of its containers.
4. Terminal49 sends updates to the webhook you have registered whenever data changes. Updates typically occur when containers reach milestones. ETA updates can happen at any time. As the ship approaches port, you receive terminal availability data, Last Free Day, and more.
5. You can request a list of shipments and containers from Terminal49 at any time. This is covered in a separate guide.

How do you receive tracking request data?

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

Poll the GET /tracking_request/{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 Bearer Token style authentication. This means you send your API Key as your token in every request.

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

Here is JavaScript code that demonstrates sending a tracking request

fetch("https://api.terminal49.com/v2/tracking_requests", {
  "method": "POST",
  "headers": {
    "content-type": "application/vnd.api+json",
    "authorization": "Token YOUR_API_KEY"
  },
  "body": {
    "data": {
      "attributes": {
        "request_type": "bill_of_lading",
        "request_number": "",
        "scac": ""
      },
      "type": "tracking_request"
    }
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

Anatomy of a tracking request response

Here’s what you’ll see in a Response to a tracking request.

{
  "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.