Common questions

This guide walks through common issues you may encounter as you get started with Vizion’s Container Tracking API. We will touch on questions related to carrier connectivity, invalid data input, webhook failures, and provide solutions to make tracking containers with Vizion as seamless as possible.

Why am I not seeing data returned?

After making a POST request to track a container, it should take thirty seconds to a few minutes to receive the first update payload. Sometimes there is an underlying issue causing the data to not be received. You can find more information by using the Get reference endpoint to view the last_update_status property.

If the last_update_status value is no_data, it is likely because:

• The carrier data is not yet available: If you attempt to track a container before the carrier has generated any data, no information will be returned. Until the carrier provides the necessary data for a container’s journey, no updates can be provided.
• Invalid data input: It is necessary to provide valid data when utilizing the API in order to receive the expected data in return. Make sure to verify you are using the correct carrier code, container ID, or bill of lading when subscribing to references.

If the last_update_status value is extraction_failed, it means an interruption in connectivity with the carriers has occurred. Once the connectivity issues are resolved, the data will be updated and received as expect.

❗️

Subscribe to the status page

We always recommend checking our status page to see if there are any current issues with a carrier that may explain the extraction failure you are seeing. You can subscribe by clicking the 'Subscribe to updates' button.

How can I unsubscribe from references once the journey is complete?

The API automatically unsubscribes references at the end of a container's journey in two ways (see Auto-unsubscribe documentation):

• Gate in empty return detected: If the API detects a "Gate in empty return" milestone at the destination port, the reference is automatically deactivated.
• New container journey: If the latest update shows new and more recent milestones from the previous journey, the API identifies it as a new journey and unsubscribes the reference.

If you wish to track containers across multiple journeys, we can turn off this feature for you.

What does 'Unknown carrier' mean?

If you attempt to subscribe to a container with an unsupported carrier, you will receive a “Unknown carrier. If you believe this is an error, please contact support” error. Vizion supports a wide range of major carriers and actively incorporates smaller carriers into its system. You can find a comprehensive list of supported carriers here. If you regularly utilize a carrier that is not listed, please contact support and let us know as we are always evaluating how to expand our carrier support.

How often will I see updates?

Vizion searches for updates every 12 hours. When a new event has been added or a change to the shipment has occurred, you will receive a new update payload. If there is no change to a shipment, an update will not be shared and the last_update_status property on the reference will be set to duplicate_payload.

How does duplicate prevention work?

With duplicate prevention enabled, you'll see the error below if you try to create a duplicate reference:

{"error":"Duplicate Reference. Unsubscribe cd76fc01-ba19-4b44-9f50-657b3a257e72 to proceed. If you believe this is an error, please contact support at [email protected]."}

Each input field must differ to avoid duplicates. For example the below are considered unique input and therefore separate references:

• Container ID: TCLU1746543
• Container ID & Carrier Code: TCLU1746543, MAEU

See full duplicate prevention documentation.

ACI Limitations: Using just the container ID for ACI bypasses duplicate prevention.

What does a last_update_status of webhook_failed mean for my updates?

If you are not receiving update payloads and see webhook_failed for your reference’s last_update_status, this indicates a problem with our ability to access the callback URL you have provided. The best way to troubleshoot and understand the root cause is to examine the logs on your server to determine why it is unavailable. In these cases, Vizion will retry your callback URL at the next update internal. You can always use the List reference updates endpoint to request all updates you might have missed in chronological order. Once the webhook server is available, update payloads will be sent.

Contact support

If you are still encountering issues when attempting to subscribe to containers, please contact support.