Skip to main content
Table of contents

Create or update a GMR

Before moving goods into or out of the country via a route that is using the Goods Vehicle Movement Service, the haulier must get a Goods Movement Reference (known internally to software as a gmrId) from HMRC.

You must get a new gmrId from HMRC for every goods vehicle crossing over these routes. Without one, vehicles will not be allowed to check-in for their crossing

Creating a GMR for an upcoming goods vehicle movement crossing

Software can get a new gmrId from HMRC using the Create Goods Movement Record endpoint.

You will need to get an access token for your users to make requests to this API. Find out how to do this in Developer Hub documentation for user-restricted endpoints.

Your software will need to capture information for the Goods Movement Record from the user before calling the API with this information. See the overview section of this documentation for details of what a GMR is and how it is used.

The user will need to update their GMR with all of the information HMRC needs for the goods movement before checking in at the customs border.

The level of information depends on what goods they are moving and under which customs procedure. Users must provide all customs references before moving goods.

Users can enter incomplete information before moving goods so that they can get a gmrId early in the process.

Your software will receive updates via the Notifications API as described under Notifications.

If the user sends an incomplete or invalid GMR, you will get a gmrId and a list of reasons why it cannot be used for moving goods yet. In this case the GMR status will be NOT_FINALISABLE.

Updating a GMR

GMRs are kept for 28 days from the last update and can be updated using the Update Goods Movement Record endpoint as many times as needed before being used at check-in, which will finalise the GMR.

The whole GMR record is sent with every update and replaces the last version received. Notification of status and reasons is via the same route as for the Create endpoint, described under Notifications.