Goods Vehicle Movement Service end-to-end guide
Version 0.3 issued 24/06/2020
This guide explains how to use our APIs to use the Goods Vehicle Movement Service (GVMS).
It is written for software developers, designers, analysts, managers and others involved with creating or integrating software that connects to GVMS.
Goods moving into and out of the UK will be subject to new customs controls because the UK has left the EU Customs Union.
Customs controls make sure HMRC can collect the correct duties at the right time, protect UK businesses and consumers and avoid any unhelpful trade distortions between the UK and the EU.
The Goods Vehicle Movement Service (GVMS) will:
Link declaration references together. This means the person moving goods only needs to present one reference at the frontier to prove that their goods have pre-lodged declarations.
Link the movement of goods to declarations, meaning they can be automatically arrived and departed in HMRC systems in near-real-time.
Notify users via your software whether their inbound goods have been successfully cleared in HMRC systems by the time they arrive in the UK.
Goods Movement Records and References
At border locations operating a pre-lodgement model and using the Goods Vehicle Movement Service to control goods, pre-lodged declaration references will need to be linked together within a single Goods Movement Record (GMR).
Carriers will require hauliers to give them the reference generated by a GMR (the Goods Movement Reference or
when they arrive to use the crossings on these routes. This applies even for empty vehicles making a crossing.
Each GMR contains details for a single crossing and can be used only once.
Details required to obtain a valid GMR
Your software users will need to get reference numbers proving that declarations have either been pre-lodged or are not needed. This is needed for the goods in every vehicle making a crossing on a GVMS route.
Your users will need to identify the vehicle and one or more unique reference numbers for each consignment it is carrying.
These references numbers may include:
- Transit Accompanying Document MRNs for goods moving via Transit
- ERNs for goods declared into CHIEF
- MRNs for goods declared into CDS
- DUCR for goods declared for export into CDS/CHIEF
- an EORI for goods where the trader is authorised to make declarations in their own records
- ATA Carnet numbers
- TIR Carnet numbers
These references, and any Safety and Security declaration references must be linked together into one Goods Movement Record for each goods vehicle crossing the border. This also applies to unaccompanied trailers.
Hauliers can do this in two ways:
an online service
a direct link from software they use into GVMS - which is what this guide describes
When HMRC receives this information, we will provide a Goods Movement Reference which can be used by that vehicle on a single crossing.
Contents of a Goods Movement Record (GMR)
the Goods Movement Reference (or
gmrId) - a unique identifier like
GMRI 0005 J2FNissued by HMRC to identify the record.
the direction of the crossing
the vehicle registration number of the vehicle making the crossing (unless the movement will be unaccompanied)
the trailer registration numbers of all trailers attached to the vehicle
details of the planned crossing if available, including the departure and arrival port, carrier and departure time
whether the vehicle arriving at check-in will accompany the movement on the crossing
customs declaration references for all goods within the vehicle and its trailers that require them
safety and security declaration references for all goods within the vehicle and its trailers that require them
transit declaration references for all goods within the vehicle and its trailers that require them
EIDR, ATA and TIR declaration references
End-to-end user journey
The user must be authorised before they can use this API. The Government Gateway user ID that is used with the API must be registered for the Get a goods movement reference service which will link it to a UK EORI.
A GMR is requested using the Create Goods Movement Record endpoint.
You can request a GMR even if you do not have all the information needed to complete one.
The system will verify the data your software presents to it and will reply with a notification.
The notification will tell your software whether the GMR is finalisable. A GMR whose state is
NOT_FINALISABLEwill not be accepted by the carrier at check-in. A new GMR that has been verified as valid will have a state of
When your software is notified that a GMR is
NOT_FINALISABLE, the notification will include details of the invalid or missing data which your software can relay to the user.
The Update Goods Movement Record endpoint provides a way for your software to update an
NOT_FINALISABLEGMR. Like the create endpoint, this endpoint also triggers a notification with an updated state after the system has completed the verification process.
If the GMR is for a movement travelling out of Great Britain, the Goods Vehicle Movement System may decide that the movement must be inspected before embarkation. If this happens, your software will be notified that the
inspectionRequiredproperty has been set to ‘true’.
Once the inspection is complete and the goods are cleared, a customs official will update the system and your software will receive a notification that the
inspectionRequiredproperty has been cleared.
When you have an
OPENGMR, you should “finalise” it before the vehicle departs on its journey to the port.
To do this, use the Finalise Goods Movement Record endpoint. This will re-verify your GMR and update its state to
FINALISED. Once finalised, the details in a GMR can not be updated through the API.
When you have a
FINALISEDGMR, the vehicle with the registration number recorded on the GMR can travel to check-in at the port. The trailers arriving at the port for unaccompanied movements must have the correct registration numbers, as recorded on the GMR for the booking with the carrier.
At check-in, the carrier will use the Goods Vehicle Movement Service to verify the GMR presented to them and cross-check the details on the GMR with the vehicle.
Vehicles will be turned away at check-in if a valid GMR cannot be presented or if their registration number(s) do not match those on the GMR.
When the carrier checks-in a vehicle and GMR successfully using the Goods Vehicle Movement Service, the GMR state will be updated to
When the carrier notifies us that the vehicle and/or its trailers have embarked on the crossing, the GMR state will be updated to
If the GMR is for a movement travelling in to the UK, the Goods Vehicle Movement Service may determine that the movement requires inspection when it arrives. If this happens, your software will be notified that the
inspectionRequiredproperty has been set to
trueup to 30 minutes after embarkation.
If this happens, the vehicle must go to a customs inspection centre when it arrives. Once the inspection is complete and the goods are cleared, a customs official will update the system and your software will receive a notification that the
inspectionRequiredproperty has been cleared. GMRs for movements travelling into Great Britain from Northern Ireland will receive this notification prior to embarkation.
At any stage, your software can use the List Goods Movement Records endpoint to get a list of all GMRs for the user, or use the Get Goods Movement Record endpoint to get full details of a GMR.
More details on these steps can be found below:
Related API documentation
- Content review
- Content review
- First draft