Billable references

Vizion implements a billing system based on unique reference IDs. Each unique reference ID created in the production environment counts as one billable reference. Demo environment references are not billable, but are limited to 50 active references and 15k requests per month. Demo references don't carry over to the production environment.

How billing works

When you create a reference, the response includes its reference ID. That ID is what counts toward your usage. A reference is billable as soon as it's created, because Vizion begins searching for data and processing the input you have provided. It is considered billable even if that work results in one of these last_update_status values:

• no_data: no tracking data was found for the container.
• extraction_failed: Vizion couldn't pull data from the carrier, often because of a temporary outage. Vizion continues checking for data at each update interval for 21 days.
• auto_carrier_not_found: Auto Carrier Identification couldn't match a carrier. Vizion keeps checking for data daily for up to 7 days.

See Check reference status for details on each status.

What's billable

Track by bill of lading or booking number

When you track by bill of lading or booking number, Vizion creates a parent reference for the document and a child reference for each container on it. See Parent and child references.

The parent is not billable. It is only used to find the containers. Each child is billable, since each one tracks an individual container. A bill of lading with 4 containers counts as 4. If the lookup finds no containers, nothing is billed.

flowchart TD
    A["Bill of Lading: 123456789<br/>(Parent - Not Billable)"]
    A --> B["MAEU1234567<br/>(Billable)"]
    A --> C["MAEU2345678<br/>(Billable)"]
    A --> D["MAEU3456789<br/>(Billable)"]
    A --> E["MAEU4567890<br/>(Billable)"]

    classDef parent fill:#FFFFFF,stroke:#C1C1C1,color:#081826,stroke-width:2px
    classDef child fill:#FFF9D5,stroke:#FFDD00,color:#0B2134,stroke-width:2px

    linkStyle default stroke:#C1C1C1,stroke-width:2px

    class A parent
    class B,C,D,E child

To stop tracking containers you don't need, unsubscribe each child by its own reference_id. Unsubscribing the parent unsubscribes every child under it. Either way, each child was billable when it was created.

Tracking a container two ways counts twice. If you track a bill of lading and also create a separate container reference for a container on it, that container has two billable references.

With Continuous MBL and Booking Processing enabled, the parent keeps checking for containers until the vessel departs the origin port. Each container found later creates a new billable child. If a container is removed from the bill before or at departure, its reference is deactivated and is not billed.

Recreating references and duplicate prevention

A new reference_id is always a new billable reference, even for the same container ID you've tracked before. Duplicate Prevention rejects a repeat request, but only while the original reference is still active and every input matches. That means:

flowchart LR
    A["Create Reference<br/>MAEU1234567 + MAEU"]
    A --> B{"Existing active reference with same input?"}

    B -->|Yes| C["Duplicate Reference Error<br/>No Reference Created<br/>(Not Billable)"]
    B -->|No| D["New Reference Created<br/>(Billable)"]

    classDef parent fill:#FFFFFF,stroke:#C1C1C1,color:#081826,stroke-width:2px
    classDef child fill:#FFF9D5,stroke:#FFDD00,color:#0B2134,stroke-width:2px

    linkStyle default stroke:#C1C1C1,stroke-width:2px

    class A,B,C parent
    class D child

    linkStyle 1,2 color:#FFFFFF

• Unsubscribing and re-creating counts as two references, even if the requests are seconds apart. Leave the original active if you might submit it again.
• Any different input is not blocked by duplicate prevention. A different carrier_code, bill_of_lading, or callback_url creates a separate billable reference.
• Container ID only requests aren't deduplicated. Duplicate Prevention needs a carrier_code, so ACI requests are not checked.
• Corrections are new references. Input cannot be edited once a reference has been created, so fixing a wrong container number or carrier code means creating a new billable reference. Unsubscribing the wrong one stops its tracking but doesn't refund it.

Check your usage

References count toward the billing period in which they were created, so you can count your own with the List references endpoint:

• Filter by creation date. Use created_start and created_end to match your billing period.
• Include inactive references. List references returns only active references by default. Make a second call with active=false so completed and unsubscribed references are counted too.

Count only references where the container ID is not empty. Leave out parent references.

See Check number of billable references created between start and end date recipe below for calculating usage:

Please reach out to [email protected] to request a usage report for a specific time period.