HMRC CDS

Connect HMRC

freightcode® connects to HMRC's Customs Declaration Service via official OAuth 2.0. This gives the platform authority to submit declarations and receive notifications on your behalf — without storing your Government Gateway password.

Test environment (TDR)

New organisations start in the test environment. Submissions go to HMRC's sandbox (TDR) only — not legally binding.

• Open Settings → Security and copy your organisation's HMRC Test User credentials.
• Click Connect HMRC and sign in with those Test User credentials — not your live Government Gateway.
• Enter your real EORI and trade data on declaration forms.

Live CDS (production)

After production access is approved for your organisation, Connect HMRC uses your live Government Gateway account. Submissions are legally binding.

• A UK EORI number (format: GB + 12 digits)
• A Government Gateway account subscribed to the Customs Declaration Service

How to connect

• 1. Go to Settings → Security (test environment: copy Test User credentials first).
• 2. Click Connect HMRC.
• 3. Sign in on HMRC's page and grant freightcode® permission. Click Allow.
• 4. You are redirected back. The Dashboard shows HMRC Connected when authorised.

Token expiry and refresh

HMRC access tokens expire after 4 hours. freightcode® checks the expiry before every submission — if the token has less than 5 minutes remaining, it is automatically refreshed using your stored refresh token before the declaration is sent.

The expiry date is shown on your Dashboard. If the token cannot be refreshed (e.g. your refresh token has also expired), the button will revert to Connect HMRC and you will need to re-authorise.

Disconnecting

Click Disconnect on the Dashboard to remove your stored HMRC token. This does not affect any existing declarations or notifications already stored in freightcode®. To submit again you will need to reconnect.

Sandbox vs Production

Test-environment organisations use HMRC's sandbox (TDR): Test User at Connect, real EORI on forms. Live organisations use production CDS and real Government Gateway — submissions clear goods at the border.