Changes to the API
This page explains how ITS changes and how to keep your integration working when it does. The Changelog lists what changed and when. The ITS API reference always shows the current contract.
Build for additive change
Some changes add something without breaking what is there. Build your client so it keeps working when they arrive:
- Ignore response fields you do not recognise. New fields appear beside existing ones. The document's own keys never move.
- Treat code lists as open. A new
notice_key,action_kind,change_typeor error code can appear. Log a value you do not recognise instead of failing. - Send only the fields in the contract. A field ITS does not read is ignored, not refused, so never rely on one being processed.
- Match on error codes, not messages. Codes are stable. Messages may change or be translated.
A retired error code is never reused. A code in an old log still means what it meant.
The partner contract is one version
The endpoints your systems implement for ITS follow the partner contract. It has a single version, v1, and every path ITS calls is under {base_url}/v1/. There are no v2, v3 or v4 levels: a receiving endpoint is declared at v1, and any other contract_version is refused with 400.
The version stays the first path segment, so if the contract ever needs a breaking change it can be published beside v1 and countries can move one at a time. See Receiving announcements.
Endpoints that moved
If you integrated before August 2026, several endpoints moved. Their old paths mostly still exist under another method, so an old call answers 405 (ERR-022), not 404.
| You were calling | Call instead |
|---|---|
GET /etd/{serial_no}/corridor | GET /etd/{serial_no}?include=corridor |
GET /etd/{serial_no}/versions | GET /etd/{serial_no}?include=versions |
GET /etd/{serial_no}/versions/{n} | GET /etd/{serial_no}?version={n} |
GET /etd/{serial_no}/deliveries | GET /etd/{serial_no}?include=deliveries |
GET /etd/{serial_no}/guarantee | GET /etd/{serial_no}?include=guarantee_status |
GET /etd/{serial_no}/tracking | GET /etd/{serial_no}?include=tracking |
POST /etd/batch | GET /etd?filter=serial_no@@A,B,C |
POST /etd/{serial_no}/exit | POST /etd/{serial_no}/endorsements/exit with next_country_code, or POST /etd/{serial_no}/endorsements/discharge to close the transit |
That exit path has since been renamed: see Exit became transit.
An include nests its answer under its own name, so the response shape moves with the URL. What was data.stops is now data.corridor.stops. The status code does not change, so check the shape when you migrate, not only the status.
Other changes that fail quietly
These changes give you no error at all, because an unknown query parameter or a discarded field is ignored:
| Change | What an old client sees |
|---|---|
GET /etd no longer takes cursor or limit. Use page-number, page-size and a created_at watermark. | Page one at the default size, and 200 |
The named list parameters state=, departure_country=, destination_country=, created_from= and created_to= were replaced by filter. | An unfiltered list |
endorsed_at, a stamp time you sent, is gone. ITS records when it received each stamp. | Nothing. The field is not read. |
Totals, td_date and the point of loading are assigned by ITS. | Nothing. The fields are discarded. |
transport_mode is yours to state on every means of transport you send; ITS no longer assigns road. See Mode of transport. | 400, ERR-015 on transport_mode, for a means of transport sent without it |
ITS no longer validates TINs. tin_scheme and country on a party are ignored, and GET /api/reference/tin-schemes answers 404. | Nothing breaks |
The lifecycle gained a release act
The lifecycle now has three acts per country: entry, release (depart) and exit. A declaration that is registered has not left, and an exit without a depart before it is refused. EXITED became DISCHARGED, closing a transit became its own discharge act, and every act fires a transition. See Lifecycle and stamps.
Exit became transit
The act that hands the goods to the next country is now called transit, the word the Transit Document uses. Nothing else about the lifecycle moved. Only the names changed, and ITS keeps no alias for the old ones.
| What it was | What it is now |
|---|---|
POST /etd/{serial_no}/endorsements/exit | POST /etd/{serial_no}/endorsements/transit. The old path answers 400 VAL-ETD-064. |
The acts entry, depart, exit and discharge | entry, depart, transit and discharge |
Stamp types TRANSIT_ENTRY and EXIT | ENTRY and TRANSIT (TD boxes 43 and 44) |
State IN_TRANSIT, shown as "In transit" | TRANSITED, shown as "Transited" |
Operation EXIT in an act's result | TRANSIT |
List filter state@@IN_TRANSIT | state@@TRANSITED. IN_TRANSIT is refused with 400 VAL-ETD-034. |
Sandbox check EXIT_ETD, sample body exit.json | TRANSIT_ETD ("Record transit"), transit.json |
Notice etd.endorsed with params.act exit | The same notice with params.act transit |
| Lost-handovers report columns for the exit country, post and time | transited_country ("Transited from"), transit_station ("Transit post"), transited_at and hours_since_transit |
Error wording follows: VAL-ETD-034 lists TRANSITED, BUS-ETD-063 says the previous country "has not stamped its transit", and VAL-ETD-064 says "Use depart, transit, entry or discharge." Match on the codes, as always.
Ledger versions signed from now on record the act kinds ENTRY and TRANSIT (ledger information model v1.4). Versions signed before the rename keep TRANSIT_ENTRY and EXIT and still verify, so a verifier must accept both sets. Where a place is meant, the word stays: "office of exit" is still the office of exit, and TD box 44 keeps its adopted title, "Authorization Stamp by Exit Office".
One announcement body (21 October 2026)
Every announcement is now the signed document, ETD_DOCUMENT_V1, sent over HTTPS to your approved receiving endpoint. The consortium ledger keeps one job: it anchors ITS's records. A State Party that runs a ledger peer can verify those anchors on its own peer. It no longer delivers announcements, and countries no longer attest versions on it.
| What is gone | What it means for you |
|---|---|
The signed notice, ETD_SIGNED_NOTICE_V1 (schema EtdSignedNotice) | POST {base_url}/v1/etd/notifications receives EtdDocumentAnnouncement only. The partner contract stays v1. |
| The ledger delivery channel: the private on-chain inbox, the on-chain acknowledgement, the receive probe and the member relay | Announcements go over HTTPS only. You acknowledge with POST /etd/{serial_no}/deliveries/ack and catch up with the digest, as before. |
The eight delivery-channel endpoints: GET and POST /api/v1/onboarding/organisations/me/delivery-channels, POST /api/v1/onboarding/organisations/me/delivery-channels/{channelId}/probe, GET /api/v1/onboarding/delivery-channels, GET /api/v1/onboarding/organisations/{organisationId}/delivery-channels, and POST /api/v1/onboarding/delivery-channels/{channelId}/approve, /reapprove, /withdraw and /probe | A receiving endpoint is still declared with POST /onboarding/organisations/me/endpoints and approved by the Secretariat. |
| Country attestations | ?include=integrity loses country_attestation and GET /api/public/verify/{code} loses country_attestations. ITS's own signature, attestation, is unchanged. |
Delivery rows' channel, receipt_tx_id and ledger_key | ?include=deliveries rows keep every other field. |
The notice integration.delivery-channel-changed | It is no longer raised and nothing replaces it. If you subscribed to it, you need change nothing: it simply stops arriving. |
Error codes BUS-ETD-112 to 116, BUS-ETD-118, BUS-ETD-122, VAL-ETD-117, VAL-ETD-120, RES-ETD-119, CFG-ETD-121, INT-ETD-123 to 125 and SYS-ETD-127 | Retired and never reused. BUS-ETD-126 stays. |
What to do: nothing, if your receiving endpoint already accepts ETD_DOCUMENT_V1. If you built for the signed notice or the ledger inbox, implement the signed document as described in Receiving announcements, and stop calling the delivery-channel endpoints. The Changelog's 2026-10-21 entry lists every removed path and field.
Tracking leaves the partner contract (27 October 2026)
ITS no longer asks your receiving endpoint about electronic seals. It reads seal positions from the integrated cargo tracking system, at one address in each ITS deployment's own configuration.
| What is gone | What it means for you |
|---|---|
GET /v1/tracking/{e_seal_id}, POST /v1/tracking/positions and GET /v1/tracking/{e_seal_id}/history, with their schemas (TrackingResponse, TrackingData, TrackingBatchResponse, TrackingHistoryResponse, TrackPoint) | Your receiving endpoint need not implement them. ITS never calls a tracking path on it. |
Nothing changes for readers. include=tracking and the public track route answer as before, and a seal the tracking system does not know reads TRACKING_UNAVAILABLE. The guarantee check, GET /v1/guarantee/{reference}, and POST /v1/etd/notifications are unchanged, and the partner contract stays v1.
The contract also states what ITS already did on a 401 from your endpoint: it drops its token and retries the announcement with a new one. A 403 is final.
What to do: nothing. If you built the tracking paths, you can retire them. The Changelog's 2026-10-27 entry lists every removed path and schema.
Stay informed
- Read the Changelog before you upgrade your client.
- Watch the notifications feed for notices about your own integration.