Submit a message for an excise movement
This endpoint allows you to submit a range of updates to an excise movement. Further information about updates which can be submitted can be found in Holding and Movements Assurance Guidance.
Use the POST endpoint Submit a message for an excise movement to submit an update on an existing excise movement.
Requirements
The consignor ID or consignee ID 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 |
Messages
You can submit the following message types to this endpoint:
| Message | Schema link | Example 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 |
| IE837 - Explain delay to delivery | IE837 XSD | IE837 Consignee XML |
| IE871 - Reason for shortage | IE871 XSD | IE871 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 |
|---|---|---|---|
| 202 | Successful | Message accepted | Movement ID, consignor ID, local reference number, consignee ID, administrative reference code |
| 400 | Unsuccessful | The submitted message has failed validation. | DateTime, message, debug message |
| 401 | Unsuccessful | Consignor or consignee not authorised. Invalid enrolment parameter. | DateTime, message, debug message |
| 403 | Unsuccessful | Consignor ID or consignee ID in submitted message is not in authorisation bearer token. | DateTime, message, debug message |
| 403 | Unsuccessful | Logged in ERN cannot send this message | DateTime, message, debug message |
| 404 | Unsuccessful | Movement doesn’t exist or cannot be accessed by supplied ERN. | DateTime, EMCS Correlation ID, message, debug message |
| 422 | Unsuccessful | The message has failed validation. | DateTime, message, debug message, EMCS Correlation Id, validatorResults |
| 500 | Unsuccessful | Internal server error. | DateTime, EMCS Correlation ID, message, debug message |
| 503 | Unsuccessful | Downstream service is unavailable. | DateTime, EMCS Correlation ID, message, debug message |
Error codes
A list of potential error codes is available in this service guide.
A workbook with more detailed information on error codes is available in the technical interface specification. The workbook includes validation rules and old error messages.