Get all messages for an excise movement
Use the GET endpoint Get all messages for an excise movement using the movement ID to get all messages for a specific excise movement.
Requirements
The consignor ID or consignee ID of the movement must match an excise reference number (ERN) in the bearer token that you use for API authentication. If it does not, a 403 Forbidden error will be thrown.
Path parameters
| Parameter | Type | Details |
|---|---|---|
| movementId | String | The movement ID of the movement |
Query parameters
The query parameter must be entered as listed below. It is optional.
| Parameter | Type | Details |
|---|---|---|
| updatedSince | String |
Filter excise movements modified after provided timestamp. This can be used to poll for new messages for the movement. You can also poll on the Get excise movements endpoint which allows a more efficient way to poll as that can first give you a list of movements that have new messages, and then use this endpoint to retrieve the updated messages for those movements. |
| traderType | String (“consignor” or “consignee”) | Filter messages for a trader type. This will filter messages for this movement for a consignor or consignee by matching any of the ERNs in the bearer token with the consignor or consignee of the movement respectively. |
Messages
You can receive the following message types from this endpoint:
| Message | Schema link | Example link |
|---|---|---|
| IE704 - Generic refusal message | IE704 XSD | IE704 XML |
| IE717 - Control report | IE717 XSD | IE717 XML |
| IE801 - E-AD/E-SAD container | IE801 XSD | IE801 XML |
| IE802 - Reminder Message for Excise Movement | IE802 XSD | IE802 XML |
| IE803 - Notification of Diverted E-AD/E-SAD | IE803 XSD | IE803 XML |
| IE807 - Interruption of Movement | IE807 XSD | IE807 XML |
| IE810 - Cancellation | IE810 XSD | IE810 XML |
| IE813 - Change of destination | IE813 XSD | IE813 XML |
| IE818 - Report of receipt | IE818 XSD | IE818 XML |
| IE819 - Alert or rejection of E-AD/E-SAD | IE819 XSD | IE819 XML |
| IE829 - Notification of Accepted Export | IE829 XSD | IE829 XML |
| IE837 - Explain delay to delivery | IE837 XSD | IE837 XML Consignee |
| IE839 - Refusal by Customs | IE839 XSD | IE839 XML |
| IE840 - Event Report Envelope | IE840 XSD | IE840 XML |
| IE871 - Reason for shortage | IE871 XSD | IE871 XML |
| IE880 - Manual Closure Request | IE880 XSD | N/A |
| IE881 - Manual Closure Response | IE881 XSD | IE881 XML |
| IE905 - Status Response | IE905 XSD | IE905 XML |
Responses
Full details of successful and unsuccessful responses and their schema can be found in the API reference on the HMRC Developer Hub.
| Response code | Status | Details | Contents |
|---|---|---|---|
| 200 | Successful | Successful operation | encodedMessage, createdOn, messageType, messageId, recipient |
| 400 | Unsuccessful | Invalid movement ID, invalid Updated since format, or not allowed to access this movement | DateTime, message, debug message |
| 401 | Unsuccessful | Consignor or Consignee not authorised. Invalid enrolment parameter | DateTime, message, debug message |
| 403 | Unsuccessful | The requested movement’s consignor ID or consignee ID is not in authorisation bearer token | DateTime, message, debug message |
| 404 | Unsuccessful | Movement with supplied ID not found for this ERN | DateTime, message, debug message |