Plans, Credits and API Keys

This page explains how to get an API key, how CargoCONNECT plans and credits work, and how each API call is charged.

📘
Legacy API keys
This page applies to API keys created in the CargoCONNECT portal. API keys issued by CargoAi before the portal (legacy keys) keep their contractual terms: they do not use credits and do not return the credit headers described below. For any question about a legacy key, contact CargoAi at [email protected].

Create an API key

Sign in to the CargoCONNECT portal at connect.cargoai.co.
Open the API Keys page of your organization and click Create New Key.
Give the key a name that tells you where it is used (for example tms-integration, erp-sync or website-quotes) and copy it. The key is shown only once: store it safely.

Every key works on the live CargoCONNECT environment: there is no separate test environment. To test without real bookings, use the mock airline (airline code 00, AWB prefix 000).

From the same page you can rename, disable, enable, rotate or revoke a key, and see its calls and credit use.

Send the key in the x-api-key header of every request:

curl --request GET \
  --url 'https://api.cargoai.co/solutions/track?awb=000-11223343' \
  --header 'x-api-key: YOUR_API_KEY'

Keep the key on your server. Never put it in a web page or a mobile app, where anyone could read it.

Plans

Every CargoCONNECT organization has a plan. The plan sets the credits included, the number of offices (IATA/CASS) you can use, and whether you can buy more credits. All keys of an organization share one credit balance.

Plan	Credits included	Max offices (IATA/CASS)	Credit top-ups
Free	50, once	1 (set up by CargoAi support)	No
Bronze	150 per month	1	Yes
Silver	3,000 per month	3	Yes
Gold	9,000 per month	10	Yes
Pro	24,000 per month	20	Yes
Premium	65,000 per month	50	Yes
Ultimate	150,000 per month	80	Yes
Enterprise	Custom	Custom	Custom pricing

All plans are self-serve: the price of each plan is shown on the plans page of the portal, where you can subscribe or upgrade at any time.

The office limit counts the distinct IATA/CASS codes of your organization and of all its authorized users. When you go over it, see Errors below.

Free plan

The Free plan lets you try the APIs before you subscribe. Compared with paid plans:

50 credits, given once when the organization is created. They do not renew and cannot be topped up: when they run out, calls are refused until you upgrade.
Search, tracking and the other read endpoints work with all airlines. Write endpoints, such as booking and FWB & FHL, work only with the mock airline (airline code 00, AWB prefix 000): upgrade to a paid plan to book or send eAWBs with real airlines.
A lower rate limit (about 3 requests per minute).
The following products need a paid plan: CargoCOPILOT API, AWB SCAN API, User Provisioning API and CargoWALLET API.
Callbacks to your own webhook URL for bookings (FlyWINDOW callback) and for eAWB status updates need a paid plan. eAWB status updates by email stay available.
The CargoAI MCP connector cannot be used with a Free plan API key.

Credit cost per API call

Each call made with a CargoCONNECT key uses credits from your organization's balance. The cost depends on the endpoint and on the response status.

API	Call	Credits (2xx)	Credits (4xx)
Route & Schedule API	Search: `POST /solutions/search` with `x-api-name: Schedules`	1	1
Quote & Book API	Search: `POST /solutions/search`	1	1
Quote & Book API	Book: `POST /solutions/book`	0	0
Quote & Book API	Cancel a booking: `PUT /solutions/bookings/{flightUUID}`	5	1
Track & Trace API	Get tracking: `GET /solutions/track`	2	1
Track & Trace API	Subscribe: `POST /solutions/track/subscribe`	10	2
Track & Trace API	Unsubscribe: `POST /solutions/track/unsubscribe`	0	0
Cargo2ZERO API	CO2 calculation: `GET /solutions/co2calculation`	3	1
FWB & FHL API	Send an eAWB: `POST /solutions/eawb`	5	1
CargoCOPILOT API	Shipment extraction, text or Excel: `POST /solutions/ai/shipment`	2	0
CargoCOPILOT API	Shipment extraction, image: `POST /solutions/ai/shipment`	5	0
CargoCOPILOT API	Shipment extraction, several inputs (`MULTI` or `attachments`): `POST /solutions/ai/shipment`	8	0
AWB SCAN API	AWB extraction, image: `POST /solutions/ai/awb`	5	1 (only `INVALID_AWB_DOCUMENT`)
AWB SCAN API	AWB extraction, PDF: `POST /solutions/ai/awb`	8	2 (only `INVALID_AWB_DOCUMENT`)
AWB SCAN API	Upload URL: `POST /solutions/ai/uploads`	0	0
User Provisioning API	Create, update, get or delete a user: `/solutions/users`	0	0

When a call is charged

2xx: the full cost of the call.
4xx: 20% of the cost, rounded up to the next whole credit (shown in the table). A request with a mistake still uses a little, so fix the request before you retry it.
5xx: free.
Search polling is free: when you repeat a search with the id of an existing search to get more results, the follow-up calls use no credits. Only the first search is charged.
CargoCOPILOT API: a failed shipment extraction is never charged, whatever the status. A file that could not be read is reported in the response and costs nothing.
AWB SCAN API: errors are free, except 422 INVALID_AWB_DOCUMENT (the document is not an Air Waybill), which uses 20% of the cost because the document was read.
Track & Trace API: a 202 Accepted on Get tracking (data still being fetched) is free. Only the call that returns the tracking data is charged.
Mock airline: on a paid plan, searches, tracking calls, subscriptions and booking cancellations on the mock airline (airline code 00, AWB prefix 000) are free.

Credit headers

Every response to a call made with a CargoCONNECT key carries two headers:

Header	Description
`X-Credits-Consumed`	Credits used by this call. On a `402` it shows the price of the call, and nothing is charged.
`X-Credits-Remaining`	Your organization's balance after this call. It can be negative on a paid plan (see below). It is left out in the rare case the balance could not be read.

Running out of credits

Free plan: a call is refused with 402 INSUFFICIENT_CREDITS when the balance is lower than its cost. Once the balance is at 0, calls are refused with 403 CREDITS_EXHAUSTED. Upgrade your plan to continue.
Paid plans: a call is never refused because its cost is higher than the balance, so the balance can go slightly below zero. Once the balance is at 0 or below, calls are refused with 403 CREDITS_EXHAUSTED until you top up.
Enterprise: calls are never refused for lack of credits.

Top-ups

On paid plans you can buy more credits at any time from the billing page of the portal. The price per credit depends on your plan and is shown before you pay. Credits are added once the payment is confirmed.

You can also turn on auto top-up: when your balance falls under a threshold you choose, a top-up is bought automatically, so your integration keeps running.

Unused plan credits are reset at the end of each monthly period. Top-up credits carry over from month to month until you use them.

Errors

Status	Error code	When
402	`INSUFFICIENT_CREDITS`	Free plan: the balance is lower than the cost of the call.
403	`CREDITS_EXHAUSTED`	The balance is at 0 or below. Top up (paid plans) or upgrade (Free plan).
403	`OFFICE_LIMIT_EXCEEDED`	Your organization uses more offices (IATA/CASS) than your plan allows. Remove offices or upgrade.
409		User Provisioning API: creating or updating the user would go over your plan's office limit.

402 Insufficient credits (headers: X-Credits-Consumed: 10, X-Credits-Remaining: 2):

{
  "error": "INSUFFICIENT_CREDITS",
  "balance": 2,
  "required": 10
}

403 Credits exhausted:

{
  "error": "CREDITS_EXHAUSTED",
  "message": "Your credits are exhausted. Please top-up your credit balance."
}

On the Free plan the message is "Your free-tier credits are exhausted. Upgrade your plan to continue using the API."

403 Office limit exceeded:

{
  "error": "OFFICE_LIMIT_EXCEEDED",
  "message": "Your plan's office limit has been exceeded. Remove offices from your organization or authorized users, or upgrade your plan, to continue."
}

While your organization is over its office limit, the User Provisioning API stays available so that you can remove offices or users.