Onboarding to the next phase of the Trader Support Service (API Users)
What is changing?
The core customs process remains unchanged.
The new API solution is designed to replicate current endpoints and support existing payloads.
The authentication mechanism for the new API has been changed to OAuth 2.0 standard for improved security. Your systems must use OAuth2.0, generate new credentials, and use the new API endpoint.
All new movements must be made via new API endpoint by 20 Oct 2026 at the latest. After this date, new movement creation will be blocked via the current API endpoint.
You may be required to integrate with both the current and new API in parallel during the transition period. Existing in-flight movements will not be migrated to the new service, and must be completed via the same system they were created in.
What are the timelines and what do I need to do?
| Step | Activity | When |
|---|---|---|
| 1 | Complete a sign-up form to gain credentials for early access to the new TSS test environment API.Access the Trader Support Service test environment and generate OAuth2.0 credentials. | Available now |
| 2 | Develop and test your integration to the new test environment API using the new OAuth 2.0 authentication standard. | Ongoing |
| 3 | Attend a meeting with the transition team. A coordination meeting will be scheduled. An important part of this call is to confirm and coordinate the parties involved in your movements (logistics providers, intermediaries, traders) to ensure they are mobilised to use the new service alongside you. | Ongoing |
| 4 | Once you have finished testing, please complete the API Technical Conformance Form to conclude your development and schedule your production environment cutover date.Shortly before the cutover date, your organisation’s primary TSS user will receive instructions for accessing the TSS production environment and generating new API credentials. | Ongoing |
| 5 | On your cutover date repoint your production environment to the new TSS endpoint. | By 20 October 2026 |
| 6 | All new movements must be made via the new API. New movements will be blocked on the old API. | 20 October 2026 |
| 7 | Close out any in-flight movements via the old API. | 20 October 2026 to 30 November 2026 |
Step 1: Access the Trader Support Service test environment and generate OAuth 2.0 credentials
Complete the sign-up form (opens in a new tab) to request a new account to use in the new test environment API.
Step 2: Develop and test your integration to the new TSS test environment API
The new API supports all existing endpoints and payloads. However, the authentication mechanism is upgrading to OAuth 2.0. You will need to update your systems to support this new standard.
After completing Step 1, your system will need to use these credentials to retrieve a temporary bearer token.
Get Bearer Token Endpoint
| Endpoint | https://auth.tt.nc-tss.uk/realms/TSS_Portal/protocol/openid-connect/token |
|---|---|
| Request Type | POST |
Body
| grant_type | client_credentials |
|---|---|
| client_id | To be provided to you |
| client_secret | To be provided to you |
The temporary bearer token must be included in the authorisation header to authenticate and call the new test environment API. The new endpoint URL is provided below. The new API supports the existing TSS endpoint paths and payloads.
API Base URL
| https://tt.nc-tss.uk/api/v1/trader_api/transition/[Path] |
|---|
Headers
| Authorization | Bearer YOUR_ACTUAL_TOKEN_HERE |
|---|
To assist with your integration, the following resources are available:
- API Schema (Swagger Documentation) (opens in new tab) version 1.0
- Bruno Collection (opens in a new tab) version 1.0
Step 3: Attend a meeting with the transition team
The transition team will schedule a coordination meeting.
A critical objective of this call is to map out and align the specific supply chain involved in your movements (logistics providers, intermediaries, and other traders). Existing movements started in the current TSS service will not be migrated to the new service and will not be visible there.
For example: the party submitting the Entry Summary Declaration (ENS) and the party completing the final declaration must both use the same TSS version for that specific shipment.
To ensure a smooth transition, this call will be used to:
- align your participation with a suitable supply chain cohort
- coordinate directly with your logistics providers, intermediaries, or dependent traders to ensure they are mobilised to use the new service alongside you
Step 4: Complete the production cutover process
Once you have finished testing, please complete the API Technical Conformance Form (opens in new tab) to schedule your production environment cutover date.Shortly before the cutover date, your organisation’s primary TSS user will receive instructions for accessing the TSS production environment and generating new API credentials.
Step 5: Repoint your production environment to the new TSS endpoint using new API credentials on the agreed switchover date
On your agreed switchover date you must repoint your production system to the new production API endpoint using the production credentials you generated in step 4.
Step 6: All new movements must be made via the new API. New movements will be blocked on the old API.
All new movements must be created and processed via the new API endpoint from 20 October 2026.
Step 7: Close out any in-flight movements via the old API.
Any in-flight movements started via the current API endpoint will not be migrated to the new API service. Existing movements must be managed and completed via the current API endpoint. Traders will retain access to the current platform until 30 November 2026 to finalise existing movements.
This means you may need to remain integrated with both the current and new API in parallel until your in-flight movements are cleared.