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.

Prerequisites

• A UK EORI number (format: GB + 12 digits)
• A Government Gateway account subscribed to the Customs Declaration Service
• Your business enrolled on HMRC's CDS (via the Government Gateway)

How to connect

• 1. From your Dashboard, click Connect HMRC in the top-right.
• 2. You will be redirected to HMRC's login page. Sign in with your Government Gateway credentials.
• 3. HMRC will ask you to grant freightcode® permission to access your CDS account. Click Allow.
• 4. You are redirected back to freightcode®. The Dashboard button now shows HMRC Connected in green with the token expiry date.

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

During the Beta period, freightcode® operates against HMRC's External Test (sandbox) environment. Declarations submitted in sandbox are not real submissions — no duty is charged and no goods are cleared. The environment is configured per deployment and cannot be changed by users.