Receiving notifications
Notifications
At various stages of the asynchronous customs declaration process, your application will need to be notified by HMRC systems of certain events resulting from interactions with one of the CDS APIs.
As a bare minimum for each declaration you can expect to receive a notification of acceptance and clearance, though others may be sent.
CDS DMSxxx notifications will be routed primarily to the submitter of the declaration. It is the responsibility of the submitter to then route the notifications to the declarant, if appropriate.
All of the CDS APIs that use notifications offer the choice of either push or pull notifications. Part of an application’s subscription to a CDS API defines how notifications from that API will be delivered to it.
If the subscription specifies a push notification callback URL, that will indicate that the API should use push notifications. Notifications generated by this API will be sent to the supplied callback URL by CDS via this ‘channel’.
If the subscription omits the callback URL, that will indicate to the API that pull notifications are to be used. Your application will need to retrieve notifications from CDS via the pull API.
Each subscription of your application to an API can configure different notification mechanisms as required, so you can choose different notification mechanisms for different APIs.
Push notifications
CDS ‘pushes’ notifications as they are generated via the specified channel to the trade systems. The trade systems need to always be ready to receive them at the callback URL specified in the subscription configuration.
When your application is granted access to CDS in Production, you will be asked to specify a callback URL as part of the application approval process. If the callback URL subsequently changes, this will need to be communicated in advance to Software Developer Hub Support, who will ensure that the necessary configuration changes are completed.
If CDS successfully delivers a notification, it cannot thereafter be resent. There are no API endpoints that would enable a re-delivery to be requested.
If CDS fails to deliver a notification (due to the specified callback URL not being contactable or the trade system responding with a non-200 HTTP response code), then it will reattempt to deliver the notification using the following rules:
| Failure | Retry Behaviour |
| Callback URL does not respond, or responds with a 5XX HTTP code |
CDS will retry to send the failed notification every 2½ minutes until successful, or until the notification expires (2 weeks from the original date of sending).
All other notifications due to be sent through the same subscription channel will be blocked until the issue is resolved. |
| Callback URL responds with a 1XX, 3XX or 4XX HTTP code | CDS will retry to send the notification back to the trade system every 10 minutes until successful, or until the notification expires (2 weeks from the original date of sending).
Other notifications to the same subscription channel will continue unaffected. |
If your endpoint is hosted by AWS, then you must either use edge-optimised custom domain names or regional custom domain names.
Pull notifications
Using this strategy, the application ‘pulls’ notifications from CDS when it is ready to do so.
The Pull API endpoints allow identification and retrieval of selected notifications via a range of identifiers.
Pull retrieval also allows (within limits) previously read notifications to be re-read if necessary.
For more details about using the API, please see the Pull notifications API documentation on the HMRC Developer Hub.
Notification types and definitions
| DMS code | Notification type | Description | Sub-process found | Mapping to CHIEF equivalent |
| 01 | DMSACC | With this message, the submitter is informed that the declaration has been legally accepted. | Validate Declaration | |
| 02 | DMSRCV | With this message, the submitter is informed that the message has been registered. This can apply to pre-lodged declarations as well as additional messages. | Validate Declaration | H2/P2 |
| 03 | DMSREJ | With this message, the submitter is informed that the received message has been rejected. This can apply to declarations and additional messages. | Validate Declaration | Cancellation Refusal: N3/S3 |
| 05 | DMSCTL | This message informs the submitter that Customs intends to physically examine the goods.This will only be received when the goods are on hand. | Initiate Control | E1 (Imports) / X1 (Exports) |
| 06 | DMSDOC | With this message, the submitter is asked (and obligated) to present one or more documents that are related to the declaration. The message is also used to remind the submitter about a document that had to be submitted already. | ||
| 07 | DMSRES | The submitter is informed that corrections have been applied to the declaration by the trader, or as a result of physical inspection by customs (latter not likely to be triggered). | Clear Declaration | N/A |
| 08 | DMSROG | This message informs the submitter that the goods can now be released. Note that this is different to clearance as it implies that the debt calculated is not yet finalised. | Clear Declaration | Currently implied by N5 / IVL notification |
| 09 | DMSCLE | This message informs the submitter that the declaration is now cleared, and by implication, the goods can be released. | Clear Declaration | Contained in N5 report if non-inventory linked. If inventory linked, trader will receive a notification from the inventory system. |
| 10 | DMSINV | This message informs the submitter that the declaration has now been cancelled. This can be as a result of a trader-initiated invalidation, or system-initiated. | Invalidate Declaration | Cancellation Approval: N4/S4 Goods Disposal Advice: S9 |
| 11 | DMSREQ | With this message, the submitter is informed of the acceptance or denial of the additional message submitted to customs. In the case of a denial, the reason is indicated. | Handle Additional Message | N3/S3, N4/S4 |
| 13 | DMSTAX | With this message, the submitter is informed of the duties liable. It can either inform on what has been reserved against a deferment account or similar method of payment. Alternatively, it can be used as a payment instruction for immediate methods of payment. In the immediate payment scenario, a payment reference is also provided. | Handle Customs Debt | Contained within E2 |
| 14 | DMSCPI | This message informs the submitter of the insufficient balance against a deferred method of payment. The relevant financial party will need to take action to rectify the situation before the goods can be released. | Handle Customs Debt | E9 and X9 |
| 15 | DMSCPR | This message is a reminder regarding the need to take action on the insufficient balance against a deferred method of payment. It can also be used as a reminder to make an immediate payment. | Handle Customs Debt | N/A |
| 16 | DMSEOG | EXPORTS ONLY. The message informs the submitter that the goods have now exited the customs union. | Monitor After Release | Indicated by ECS via IE518 |
| 17 | DMSEXT | This message informs the submitter that the declaration needs to be handled manually. Only used in exceptional circumstances where the system cannot handle the declaration. | Handle Irregularities | N/A |
| 18 | DMSGER | EXPORTS ONLY. This message informs the submitter that the exit results have not yet been received by the Export system. This could be a trigger to submit an alternative proof of exit. | Monitor After Release | S0 |
| 50 | DMSALV | This message informs the submitter that a decision has been made by Defra that will delay clearance of the goods. | Perform Control | Contained within E0 |
| 51 | DMSQRY |
This message informs the submitter that a query has been raised on the declaration by Customs, advising that a caseworker has sent a secure message and is awaiting action by the submitter. It is not possible to respond to this message, it is just an alert to access the query online. IMPORTS ONLY. For declarations that require CERTEX Checks, a DMSQRY will be sent to the trader when a follow up action is required by the trader and when a case that has required caseworker manual intervention is resolved. These will be prefixed with CERTEX Check. |
Notification message structure
Notification messages are XML documents.
The latest schemas and annotated XML samples can be found in the Customs Declarations API (may require login).