DEV Community: Kristi Hampson

TSS API for Freight Forwarders: A Technical Overview

Kristi Hampson — Fri, 11 Sep 2026 06:43:38 +0000

What the TSS API actually offers

The Trader Support Service exposes an API that allows authorised customs agents to submit declarations programmatically instead of through the portal. For freight forwarders with repeat-lane volume, this is where scaling stops meaning more people and starts meaning cleaner pipelines.

Prerequisites

You need an agent account (converted from trader, one-way), individual client authorisations, MFA-capable service accounts, and source data clean enough to survive schema validation without hand-repair.

Watch the 99-item limit

A single TSS declaration is capped at 99 items. Consolidated loads exceeding that must be split before submission. This TSS software for freight forwarders guide covers the splitting decision as part of the portal-vs-API choice.

Client-scoped identifiers

Every declaration must carry the correct client EORI and, where relevant, the client UKIMS authorisation. Hard-coding these into shared config is where multi-client integrations most often fail.

Exception handling in code

The API returns rejections and amendments that must be routed back to the right client. Design your exception queue with the client context attached, not the submission ID alone.

When API is the wrong answer

Ad-hoc consolidated loads, low-volume clients, and new movement types often submit faster through the portal. Automation earns its keep on repeat shapes.

See a multi-client TSS integration in production. Watch a demo.

TSS API Integration: A Practical Technical Guide

Kristi Hampson — Thu, 10 Sep 2026 09:07:10 +0000

What the TSS API actually is

The TSS API is a JSON-based submission channel to the Trader Support Service. It accepts the same declarations the portal accepts, from a system rather than a human. TSS charges nothing for access and the endpoints are the same for every registered trader.

Field mapping is where projects live or die

Every declaration field must be sourced from an authoritative system. If a value appears in two places, decide which one wins before writing any code. The TSS API integration guide sets out the sequence: register, locate fields, map to TSS specifications, build, test, validate failure paths, run in parallel.

Build a test environment first

Do not integrate against production. Build in the dedicated environment TSS provides, run the full lifecycle including rejections, and only then plan cutover.

Rejection handling is the real design

Success cases are easy. Rejections need a defined path: which system logs the failure, which team sees it, what the retry pattern is, and how long a submission can sit in an error state before it violates a deadline.

Progressive assembly

The API supports adding information incrementally as consignment details arrive. Model that in your queue design; do not treat every declaration as a single atomic post.

Run both channels during migration

Parallel running is not optional. Keep the portal live for the same movements until API submissions have produced clean results across a full month cycle.

See a working TSS API integration inside iCustoms. Watch a demo.

TSS Automation Software: A Technical Buyer's Checklist

Kristi Hampson — Wed, 09 Sep 2026 07:42:10 +0000

If you are the engineer being asked to sign off on a TSS tool, the marketing decks will not help. Six technical checks will.

1. Submission API surface

Which declaration types are live in production today: ENS, simplified frontier, supplementary, full frontier? Does UKIMS internal market movement work end to end? Can port movement references be created programmatically?

2. Validation contract

What checks run pre-submission, and can they be triggered independently of submission? A useful walk-through of validation depth sits in this iTSS automation guide.

3. Throughput and back-pressure

Batch limits, per-declaration item caps, rate limits, and behaviour under the 10th-of-month spike.

4. Error contract

Structured error codes, remediation hints, webhook or queue delivery, and idempotency on retry.

5. Integration surface

File pickups, ERP connectors, OCR handoff, and clean interfaces for supplier invoice ingestion.

6. Audit export

Full history export as machine-readable data, not just PDFs, retained for the periods your movements require.

Test the API surface against your workload. Watch a demo.

TSS to GVMS: The Data Flow Behind a GMR

Kristi Hampson — Tue, 08 Sep 2026 07:19:39 +0000

What the systems actually do

TSS (Trader Support Service): produces the customs declarations and issues the MRNs for GB to NI and NI to GB movements.
GVMS (Goods Vehicle Movement Service): the vehicle-facing system at Roll-on Roll-off ports. Holds the GMR that ties declarations to a vehicle.
CDS (Customs Declaration Service): the underlying declaration system whose MRN format appears on GMRs. ## The reference formats you will see

Reference	Meaning	GVMS declaration type
`CDS...`	CDS format MRN	Customs declaration
`YYGB...`	Year-plus-GB format MRN	Customs declaration
`XI...`	Entry Summary Declaration made in ICS2	Entry in Declarant's Records (plus trader EORI)

The build sequence

Register for GVMS on GOV.UK (GB EORI required).
Start a new GMR and enter movement information.
Select the declaration type based on the reference format.
Add customs references from TSS notifications.
Add additional consignments.
Include any non-TSS consignments with MRN and safety and security data.
Review.
Save or print the GMR barcode. The full annotated sequence is in this technical TSS to GVMS reference.

Update semantics

A GMR is mutable until the boarding barcode is scanned. After that, the reference is fixed for that movement.

Connect TSS, CDS and GVMS into a single API-driven flow. Watch a demo.

Technical Guide: Filing ENS to Northern Ireland Through TSS

Kristi Hampson — Mon, 07 Sep 2026 08:10:49 +0000

What the ENS actually is

An ENS is a structured safety and security data message, not a customs declaration. Since 31 December 2025 it terminates in ICS2, replacing the older ICS endpoint.

Filing chain

Trader provides consignment data.
Carrier holds legal responsibility for submission.
Forwarder or intermediary often submits on the carrier's behalf.
ICS2 acknowledges and issues a Movement Reference.
Vehicle uses the Movement Reference at port check-in. The full data flow is documented in the ENS filing for NI movements reference.

Required data fields

Consignor and consignee identifiers
Plain-language goods description
Transport mode, vehicle, carrier ID
Routing details
Security-relevant consignment data
XI-prefixed EORI

Common technical failures

GB EORI on a Northern Ireland ENS
Missing routing data on multimodal legs
Generic descriptions rejected by validation
Corrections applied only to downstream customs data, not the source ENS

Downstream integration

Under the simplified customs route, supplementary declarations auto-generate from ENS data. That coupling means a bad ENS produces a bad supplementary. Validate upstream.

Wire ENS submissions into your ops stack — Watch a demo.

A Developer's Guide to TSS Declaration Data Structure

Kristi Hampson — Fri, 04 Sep 2026 06:58:59 +0000

Why This Matters for Engineers

If you are building anything that touches TSS submissions, you are modelling five data groups: parties, goods, customs treatment, transport, and safety & security. Get the schema right up front and the rest of the pipeline is straightforward.

The Data Model

Parties: EORI, importer, exporter, declarant, intermediary. Goods: commodity code, description, quantity, gross and net mass, value, currency, origin, packaging. Customs treatment: procedure, customs value, duty position, preference, reliefs, authorisations, scheme status. Transport: mode, carrier, vehicle, route, port, arrival/departure. Safety & security: consignor, consignee, description, routing.

Consignment vs Item Level

Consignment-level fields describe the shipment. Item-level fields repeat per goods line. A 15-product shipment carries 15 item objects. Model this as a one-to-many, not a flattened row.

Validation Rules Worth Encoding

Gross mass > net mass. Sum of item values equals invoice total. Currency matches invoice. Commodity code exists and is current. Digit count matches goods category. Origin is a country, not "country of despatch".

The prepare customs data for TSS walkthrough sets out each rule in the same shape you would encode it.

Ship the Schema First

Constraints belong in the model, not in the UI. Enforce them at ingestion and you push rejections back to source.

See how validated customs data is produced upstream of the portal. Watch a demo.

TSS Declaration Field Validation: A Technical Reference for Ten Common Errors

Kristi Hampson — Thu, 03 Sep 2026 07:52:41 +0000

TSS declarations are a structured data problem. Each rejection has a specific field, a specific rule, and a specific validation that would have caught it.

Field-Level Failure Points

Vague goods descriptions fail free-text validation. Entry summary declarations run a stop-word list rejecting values like "goods" and "gifts." Commodity codes at eight or ten digits require an annual freshness check against the current tariff. Document codes at DE 2/3 must be present, unique per record, correctly paired with reference details and status codes, and consistent with the Tariff Requirements for the commodity.

Weight fields — gross mass, net mass, package count, supplementary unit — must reconcile against each other and against the invoice, packing list, and transport document. Currency and value fields require the customs value calculation, not the invoice total. EORI fields need format and check-digit validation to catch transpositions. The TSS data entry errors reference enumerates each field with examples.

What Validation Can and Cannot Do

Automated validation handles the mechanical layer: presence, format, cross-reference, arithmetic, and freshness. It cannot evaluate whether a description is honest, whether a preference claim is substantiated, or whether goods risk classification is correct. The split between mechanical and judgment work drives where automation adds value.

See the validation stack running against live TSS submissions. Watch a demo of iCustoms.

Understanding the Structure of an Automated TSS Declaration Workflow

Kristi Hampson — Wed, 02 Sep 2026 08:35:56 +0000

The Six Building Blocks

An automated TSS declaration workflow can be broken into six defined stages:

Ingestion. Trade documents and system feeds are collected: invoices, packing lists, transport paperwork, ERP records.
Extraction. Fields are read from documents: parties, goods lines, quantities, weights, values, origin, references.
Validation. The record is checked for completeness, cross-document consistency, format and rule compliance.
Enrichment. Fields the source documents do not carry (commodity codes, authorisations, internal identifiers) are added from approved sources.
Submission. The validated record is sent to TSS through an API.
Status handling. Accepted responses are logged. Rejections are routed with context for a person to resolve. ### Where the Structure Matters

Each stage is designed so a failure at that point can be inspected, corrected and re-run without breaking the ones before it. That is what makes the pipeline maintainable. For a step-by-step walkthrough, see How Customs Declaration Automation Works.

The Boundary Between Software and Human

Software handles the mechanical stages. People handle the interpretive ones: new product classification, risk judgement and final accountability.

Design Principles

Validate early; do not submit uncertain data.
Enrich from reference sources, not from guesses.
Treat rejections as first-class events, not error logs.
Keep exception ownership explicit. See how the structure plays out inside a working system and Watch a demo of iCustoms.

TSS API: A Developer's Introduction to Customs Declarations

Kristi Hampson — Tue, 01 Sep 2026 07:06:43 +0000

Overview

The Trader Support Service (TSS) API is a submission channel for customs declarations moving goods into Northern Ireland. Your system builds a payload, sends it to TSS, and gets back a JSON response — accepted, or an error list.

Declaration types you can submit

Entry Summary Declarations
Simplified Frontier Declarations
Supplementary Declarations
Full Frontier Declarations
Port movement references (authorisation-dependent) Payloads can be built progressively, so partial state is normal. The TSS API technical guide explains how this maps to real workflows.

Request and response shape

Requests carry declaration data. Responses are JSON with either an acceptance confirmation or an errors array. Design your client to treat both as first-class outcomes.

What you still have to build

The API does not extract invoice data, validate commodity codes, confirm weights or resolve missing documents. That is your upstream problem.

See a working TSS integration from data ingest to submission — Watch a demo.

TSS Declaration Types: A Technical Breakdown for Trade Systems

Kristi Hampson — Mon, 31 Aug 2026 07:22:18 +0000

Why "TSS" is not one API

If you are building or integrating a customs stack for Northern Ireland trade, "TSS" is not one endpoint. It is five declaration types, each with its own payload, owner and lifecycle.

Declaration inventory

ESD: safety and security data, carrier-submitted, pre-arrival.
SFD: minimal commercial data, trader-submitted, at movement.
Supplementary: full commercial + duty + at-risk data, due 10th of following month.
IMMI: reduced data set, UKIMS-gated, non-Category 1, pre or post movement.
Full Frontier: complete data set, inventory-linked port/airport movements. The TSS declaration process breakdown has the field-level detail worth mapping into your data model.

Integration takeaways

Model declarations as separate entities, not as states of one form. Model the SFD → supplementary link as a parent-child relationship, not as an update. Guard the supplementary submission against auto-population defaults so commodity codes require explicit sign-off. And expose a UKIMS flag on the trader entity so IMMI eligibility can be computed at movement time.

Deadlines as scheduler events

Handle the 10th-of-month deadline as a hard scheduler event with escalation, not as a soft reminder.

Want a ready-built engine for all five declarations? Watch a demo of iCustoms.

The TSS Data Model for GB to NI Movements

Kristi Hampson — Fri, 28 Aug 2026 07:03:51 +0000

The Trader Support Service isn't a monolith. It's a sequence of data submissions with strict ordering: safety and security data, customs information, then movement reference.

Core entities

Every GB to NI move needs a trader EORI, party data for the consignor and consignee, a goods table with commodity codes (6 digits standard, 8 for Category 2), an at-risk flag, and a UKIMS authorisation reference where claimed.

Ordering constraints

The movement reference cannot exist before the customs entry. Build the pipeline to enforce this — do not rely on humans catching it.

The full sequence and the field-level dependencies sit in this engineer-friendly guide to TSS for GB to NI.

Where integrations usually break

Vehicle details typed twice. Container numbers absent. Trailer swaps not reflected downstream. Every one is a data-sync problem, not a customs problem.

Design recommendation

Model the eight TSS stages as a state machine. Each transition validates the payload before the next call. Reject early, log verbosely, and surface the specific failing field.

To see how iCustoms exposes this data model through an API-first customs platform, watch a demo.

TSS, ICS2, GVMS and NCTS: A Technical Overview

Kristi Hampson — Thu, 27 Aug 2026 08:30:55 +0000

TSS, CDS, ICS2, GVMS and NCTS are best understood as a small distributed system with a shared input layer and four specialised backends.

The pipeline

The trader submits movement information once. TSS validates and enriches it, then routes structured messages to the correct downstream system.

CDS receives the customs declaration payload.
ICS2 receives the safety and security payload.
GVMS receives declaration references bundled into a Goods Movement Reference.
NCTS receives the transit declaration when the movement runs under the Common Transit Convention. ## Shared identifiers All four backends describe the same consignment. They share EORI numbers, commodity codes and transport identifiers. That shared vocabulary is what lets TSS route once and reconcile later.

Where the pipeline breaks

Historical development created inconsistencies in formatting expectations. A commodity code entered one way in CDS may be accepted differently by another system, and a vehicle registration mismatch will fail GVMS check-in. Most production incidents are data quality issues at the entry point. The TSS routing to HMRC systems walkthrough covers the flow in more detail.

Practical takeaway

Treat the entry layer as the schema-of-record. Normalise once, validate at the boundary, and rely on TSS to route.

Want to see this pipeline running end to end? Watch a demo to see iCustoms.ai orchestrate the flow.