TSS API: What It Is and How It Works
- John Hall
- Customs Specialist at iCustoms.ai
Yes, TSS has an API. It lets your own systems do what a person would otherwise do by hand in the TSS Portal: create, edit and submit declarations, and receive confirmations or errors back in JSON. It supports entry summary declarations, simplified frontier declarations, supplementary declarations and full frontier declarations, and agents can use it on behalf of the traders they represent.
A surprising amount of writing about Northern Ireland customs still describes the Trader Support Service as a portal you type into. That has not been true for a long time, and if you are filing at volume it is the single most expensive misconception in this space.
What the TSS API actually does
The TSS declaration API mirrors the portal. Anything a user would complete manually on screen, a system can send instead.
A request carries declaration data. TSS processes it and returns a response confirming acceptance or listing errors, formatted as JSON. Your system reads that response and acts on it, which is what makes unattended processing possible: no one has to sit and watch a screen to find out whether a submission landed.
It is worth being precise about what this is not. The API does not change any customs rule, remove any obligation, or decide anything on your behalf. It changes how the information gets there, not what the information has to be.
Which declarations it can submit
- Entry Summary Declarations
- Simplified Frontier Declarations
- Supplementary Declarations
- Full Frontier Declarations
That covers the routes most businesses use. There is also authorisation-dependent functionality for creating the movement reference the vehicle needs at the port.
If the declaration names above are not yet familiar, our guide to simplified and supplementary declarations explained sets out what each one contains and when it is due.
How the TSS API works in practice
YOUR SYSTEM
ERP, WMS, TMS or customs platform
↓
request with declaration data
request with declaration data
TSS API
↓
JSON response
JSON response
ACCEPTED
ERRORS
↓
Government systems
One detail catches people out in a good way. You do not have to send everything at once. The API mirrors how the portal behaves, so a system can add information, stop, and come back and add more later. Declarations can be built up progressively rather than assembled perfectly before the first call.
That matters for real operations, where the commercial invoice arrives on Monday, the weights get confirmed on Tuesday and the transport details are not settled until Wednesday.
TSS bulk upload
Consignments do not all need uploading simultaneously. The Functional Guide sets a maximum of 99 items per declaration, so very large consignments have to be structured with that in mind.
Check the current reference
The 99-item figure comes from the API Functional Guide. The TSS Declaration API Reference is actively maintained, currently at version 2.9.6 and updated in July 2026, so limits and field definitions do move. Build against the current reference document rather than against any article, including this one.
Responses and errors
Responses come back in JSON. An accepted submission returns confirmation. A rejected one returns the errors.
This is the part worth designing carefully, and it is the part most first implementations underestimate. Getting a declaration accepted on a clean data set is straightforward. Handling the rejections sensibly, routing them to a human, retrying what should be retried and not silently swallowing failures, is where the engineering effort actually goes.
What you need before you can use it
Access to the Trader Support Service API is requested through your TSS company profile. The guidance is direct about who it suits: organisations with an experienced IT department. This is not a no-code integration.
Beyond the registration, you need:
- Shipment data combined with customs declaration information, in one place
- Commodity codes, including for any controlled goods you move
- A working understanding of the tariff requirements that apply to your goods
- Your data sets prepared and mapped to the API specification
- The relevant authorisation, where you want the port movement reference created automatically
Look at that list again. Only one item is technical. The rest is customs data readiness, which is the real reason API projects stall.
The test environment
There is a dedicated test environment, with credentials issued for both test and production. You can iterate against test before anything goes live, and TSS provides guidance during implementation.
Use it properly. A test cycle that only exercises the happy path will not tell you how your system behaves when a commodity code is rejected at four in the afternoon before a sailing.
Where the TSS API documentation lives
Four documents matter, and they do different jobs. Reading them in the wrong order wastes a lot of time.
The API Functional Guide
Start here. It explains what the API does, who is eligible, the benefits, which declaration types it handles, how bulk and automated upload work, and what a business needs in place first. It is the document to read before committing anyone’s development time.
The TSS Declaration API Reference
This is the technical specification: fields, structures and the detail your developers actually build against. It is versioned and revised regularly. Treat the current version as the only authority on field definitions and limits.
The TSS declaration data requirements data guide
This one is channel-independent, and it is the one non-developers should read. It sets out what each declaration type needs regardless of whether you submit through the portal or programmatically, covering entry summary, simplified frontier, supplementary and full frontier declarations, plus the automated creation of port movement references.
If your API project is stuck, this guide is usually where the answer is. The blocker is rarely the interface.
Permissions management for goods profiles and UKIMS
Relevant once more than one person or system acts on your account. Worth reading before you discover a permissions problem mid-implementation.
The whole TSS API guide set sits on the NI Customs and Trade Academy site. Bookmark the reference rather than a downloaded copy, because a saved PDF quietly becomes wrong
Movement reference automation
Creating the reference the vehicle needs at the port can also be automated through the API, subject to holding the relevant authorisation. Worth asking about specifically if port turnaround is a pressure point, because it removes a manual step at exactly the moment when there is least time to fix anything. The mechanics are covered in our guide to creating movement references in TSS.
Who should use the TSS API, and who should not
| Profile | API or portal | Why |
|---|---|---|
| A few movements a month | Portal | The integration effort will not pay back. The portal is free and adequate. |
| Steady volume, stable product range | Worth modelling | Repetition is what the API removes. Stable products make mapping straightforward. |
| High volume, many customers | API | Manual entry becomes the constraint on how much work you can take on. |
| Agent or intermediary | API | It can create, edit and submit on behalf of the traders you represent. |
| Data still in email and spreadsheets | Fix the data first | An API cannot submit information you have not structured yet. |
That last row deserves emphasis, because it is the most common misdiagnosis. Businesses reach for an integration when the actual bottleneck is that nobody has decided where the authoritative commodity code lives.
What an implementation realistically involves
- Register for API access through your TSS company profile.
- Work out where each required field will come from in your existing systems. This takes longer than people expect and is the step that determines whether the project succeeds.
- Map your data to the API specification.
- Build against the test environment, including the failure cases.
- Design the exception path: who sees a rejection, how fast, and what they do about it.
- Move to production with credentials for the live environment.
- Monitor. Acceptance rates, error patterns and time to resolution tell you whether it is working.
Steps two and five are where the value is won or lost. Step one is administrative and step three is mechanical.
The API is a channel, not a solution
This is the honest framing, and it saves a lot of disappointment.
The TSS API solves submission. It does not solve the work that happens before submission: reading a supplier’s commercial invoice, pulling out the goods lines, checking the commodity code is still valid, confirming the weights add up, catching a missing certificate for Category 2 goods, and turning all of that into a structured, validated data set.
For most businesses that manual preparation, not the submission itself, is where the hours go. Connecting an API to a process that still depends on someone retyping an invoice moves the bottleneck rather than removing it.
Our work on Northern Ireland customs automation covers the layer that sits in front of submission: document extraction, validation and connecting the business systems that already hold the data.
For the workflow view of that end to end, see automating TSS declarations. If you are weighing the two operating models against each other, we compare TSS API compared with manual portal entry separately.
Four things that go wrong
Treating it as a data problem solved
The API accepts what you send. If what you send is wrong, you have automated the production of wrong declarations, faster.
No exception path
Rejections arrive. If nobody owns them, they accumulate quietly until a deadline forces the issue.
Testing only the happy path
The test environment exists so you can break things deliberately. Use it for that.
Building against an old reference
The reference document is versioned and updated. Anything built against a two-year-old copy will drift.
On the data readiness point, our guide to what data a TSS declaration needs is the place to start, and what to look for in TSS automation software covers the evaluation criteria if you are buying rather than building.
Frequently Asked Questions
You may also like:
Struggling to Extract, Catagorise & Validate Your Documents?
Capture & Upload Data in Seconds with AI & Machine Learning
Subscribe to our Newsletter
About iCustoms
iCustoms is an all-in-one solution helping businesses automate customs processes more efficiently. With AI-powered and machine-learning capabilities, iCustoms is designed to streamline your all customs procedures in a few minutes, cut additional costs and save time.
Struggling to Extract, Catagorise & Validate Your Documents?
Capture & Upload Data in Seconds with AI & Machine Learning