Billing and usage

TrackingMCP keeps two counters. They answer different questions, so read them separately.

Counter	What it counts	What it is for
Calls	Every keyed request you send to a tracking path, whatever it answers.	Your call ceiling. When it is spent, the next request is refused with 429 quota_exceeded.
Unique shipments	Each distinct reference (container, B/L or booking) that returned real data in the period.	Your bill. This is the unit your plan allowance and your invoice are written in.

A request that finds nothing is still 1 call. It never becomes a unique shipment. That is why a miss can show up in your call count and still cost you nothing on the invoice.

MCP calls on an account with a Navo Tokens wallet use neither counter. They are paid in tokens (see Navo Tokens). MCP calls on an account without a wallet are counted in calls, as on REST.

What becomes a unique shipment

A reference is billed once per period, the first time it answers with data.

• One reference, one unit. A B/L or booking is one unique shipment, however many containers sit under it. The containers we discover beneath it are free.
• Repeats are free inside the period. Reading the same reference again, by lookup, by container detail or by polling, raises calls only.
• Period. On a monthly plan the period is the UTC calendar month (2026-11 runs from 1 November 00:00 UTC to the end of 30 November UTC). A reference you still read next month counts once more in that month. On a per-shipment plan a reference counts once for its whole life.
• Archived boxes are not billed again by reads.

Outcome table

What each answer costs on REST with an API key, and on the SeaRates-compatible endpoint (/compat/searates).

Answer	Calls	Unique shipment
Data returned (200, 201; compat OK)	1	Yes, first time in the period
Containers listed, no events yet (compat NO_EVENTS with data)	1	Yes, first time in the period
Line known, holds no movement of this shipment yet (compat NO_EVENTS with data: {})	1	No
Booking with no container list yet (compat NO_CONTAINERS)	1	Yes, first time in the period
Same reference again in the same period	1	No
Line answered “nothing on file” (compat SEALINE_HASNT_PROVIDE_INFO)	1	No
Shipment cancelled (compat SEALINE_CANCELED_SHIPMENT)	1	No
Still resolving (202, STILL_RESOLVING)	1	No
Not found, bad number, unsupported line (404 REFERENCE_NOT_RESOLVABLE, AUTO_CANT_FIND_INFO, compat WRONG_NUMBER, SEALINE_NOT_SUPPORTED)	1	No
409 ALREADY_TRACKED, 4xx from the route, 5xx	1	No
REST rate limit (429 over the 20 second window)	1	No
402 quota refusals on an add (UNIQUE_QUOTA_EXCEEDED, CONTAINER_QUOTA_EXCEEDED, PAYG_SPEND_CAP_REACHED)	1	No
Served from cache (compat)	1	No
401 (no or bad key)	0	No
Refusals before the route: 429 quota_exceeded, 403 access_expired, a key-limit refusal, 429 rate limit on compat	0, counted as refused	No
Account paths: /v1/usage, /v1/account, /v1/api-keys, /v1/billing, /v1/invoices, /v1/finance, /v1/team, /v1/webhooks, /v1/mcp	0	No
POST /v1/track/public (no key)	0	No

Every miss costs a call, so a retry loop on a reference that will not resolve eats into your call ceiling. It never reaches your invoice. Back off on the delay the answer gives you.

Free access

There are two separate ways to try Navo without paying.

• REST free evaluation. A free account with an API key can track 5 unique references in total, no card. The count is for the life of the account, not per month, and archiving a box does not give the reference back. The sixth new reference is refused with 402 UNIQUE_QUOTA_EXCEEDED.
• Navo Tokens trial. 7+ days and 1,250 tokens, for MCP and every Navo tool. See Pricing.

Test keys

A test key spends its own sandbox, never your commercial allowance.

• Default sandbox: 50 unique references per month per test key. Sales can set a different cap on a key.
• Calls made on a test key show in /v1/usage as calls.test_used.
• Over the sandbox cap, the next new reference gets 402 UNIQUE_QUOTA_EXCEEDED.

Quota refusals

Code	Status	What happened	How it clears
quota_exceeded	429	The call ceiling of your plan or of the key is spent.	Next period, or a higher plan. Not counted as a call.
UNIQUE_QUOTA_EXCEEDED	402	A new reference would pass your unique-shipment allowance. References you already track keep working.	Next period on a monthly plan, or a higher allowance.
CONTAINER_QUOTA_EXCEEDED	402	No container slot is free on your plan. The body names the next plan.	Archive or delete a box: its slot is returned. Delivered boxes are archived automatically and free their slots too.
PAYG_SPEND_CAP_REACHED	402	Pay-as-you-go: the add would cross the spend cap you set.	Raise the cap in billing settings.
access_expired	403	The access period on your plan has ended.	Renew.

Check your usage

GET /v1/usage (also mounted at /v1/account/usage) returns the counters the API enforces against, from the same ledgers your invoice and your account manager read. It is free to call.

curl https://api.trackingmcp.com/v1/usage \
  -H "Authorization: Bearer $NAVO_API_KEY"

{
  "ok": true,
  "data": {
    "period": "2026-11",
    "next_expiry": "2027-01-31",
    "invalid_references_this_month": 3,
    "products": [
      {
        "product": "container",
        "channel": "api",
        "plan": "paid",
        "billing_mode": "monthly",
        "refused_this_month": 0,
        "calls": { "used": 4210, "limit": 50000, "remaining": 45790, "test_used": 120 },
        "allowance": { "basis": "unique_reference", "limit": 500, "used": 212, "remaining": 288 }
      }
    ]
  }
}

Field	Meaning
period	The UTC calendar month the counters cover.
calls.used / limit / remaining	The call counter and your call ceiling.
calls.test_used	The part of calls.used made on test keys.
allowance.used / limit / remaining	Unique shipments billed this period and what is left. limit: null means no ceiling is set.
refused_this_month	Requests turned away (quota, expired access, key cap). Never billed.
invalid_references_this_month	Requests refused because the reference was malformed or its line is unsupported. Never billed.
next_expiry	The earliest date your access ends across products.

The SeaRates-compatible endpoint carries the same two counters in every answer: data.metadata.api_calls and data.metadata.unique_shipments.

Rate limits and the X-RateLimit-* headers are covered in Errors and rate limits.