Once a declaration has a Movement Reference Number, the question a broker's team asks most often is simple: where is this movement now, and is it waiting for us? MRN status tracking for NCTS transit and AES export answers that question. It turns a stream of asynchronous customs messages into one current state per movement, and it is the part of a customs integration that users look at every day.
This article uses the movement states that Irish Revenue documents for software developers in its AES message exchanges and NCTS message exchanges documents. Each national system has its own rules, so check the one you connect to. For the messages themselves, see the AES and NCTS message flow.
LRN and MRN
Every declaration carries two references, and they are not interchangeable.
- The Local Reference Number (LRN) is the trader's own reference. Your software assigns it before anything is sent, so it is the only key you have while the declaration is on its way.
- The Movement Reference Number (MRN) is allocated by customs when it accepts the declaration: with IE528 in AES and with IE028 in NCTS. From then on, customs messages and documents refer to the movement by its MRN.
A declaration that fails validation never reaches that point. In both message exchange documents, a syntactically invalid message is answered with IE917 (XML NACK), and a logically invalid declaration with a rejection (IE556 for export, IE056 for transit) instead of an MRN.
In the data model, the movement record exists from the moment you send the declaration, keyed by the LRN. The MRN is a nullable, unique field filled in later. Every message, sent or received, is linked to that record, so the messages behind a state can always be shown.
A state machine for an export movement
The AES message exchanges document names the states of an export movement at the office of export. The table lists them with the message that moves the movement into each one.
| State | Entered on | Final |
|---|---|---|
| Submitted | A syntactically valid IE515 (Export declaration) | No |
| Accepted | IE528 (Export MRN allocated) | No |
| Rejected | IE556 (Rejection from office of export) | Yes |
| Under Control | IE560 (Export control decision notification) | No |
| Goods Released for Export | IE529 (Release for export) | No |
| Not Released for Export | IE551 (Export no release) after unsatisfactory control results | Yes |
| Cancelled | IE509 (Export invalidation decision) after an IE514 invalidation request | Yes |
| Exported | Positive exit results, followed by IE599 (Export notification) | Yes |
| Export Stopped, Discrepancies at Exit | Negative exit results, followed by IE599 | Yes |
Two details matter for the implementation. First, release for export is not the end: the movement stays open until the results from the office of exit arrive. Second, according to the same document, IE599 follows both positive and negative exit results. A handler that maps the message code alone to "Exported" gets the negative case wrong. Check in the specification of your national system which data in the message tells the two outcomes apart.
The office of exit has its own states, such as Goods Presented at Exit and Exited, driven by the messages of the trader at exit (IE507, IE525, IE590). If your users act at exit too, model that as a second track on the same movement.
A transition function keeps these rules in one place:
static final Set<ExportState> FINAL = EnumSet.of(REJECTED, NOT_RELEASED, CANCELLED, EXPORTED, STOPPED_AT_EXIT);
ExportState next(ExportState current, IncomingMessage message) {
if (FINAL.contains(current)) return current; // log it and show it to a person
return switch (message.code()) {
case "IE528" -> ExportState.ACCEPTED;
case "IE560" -> ExportState.UNDER_CONTROL;
case "IE529" -> ExportState.RELEASED_FOR_EXPORT;
case "IE551" -> ExportState.NOT_RELEASED;
// which field tells the outcome apart depends on the national message specification
case "IE599" -> message.reportsPositiveExit() ? ExportState.EXPORTED : ExportState.STOPPED_AT_EXIT;
default -> current; // IE556, IE504, IE509 depend on the request they answer (see below)
};
}A state machine for a transit movement
The NCTS message exchanges document describes more states, because a transit movement involves an office of departure, a guarantee, and an office of destination.
At the office of departure:
| State | Entered on | Final |
|---|---|---|
| Rejected | IE056 for a logically invalid IE015 | Yes |
| Submitted | IE928 (Positive acknowledge) | No |
| Accepted | IE028 (MRN allocated) | No |
| Guarantee under amendment | IE055 (Guarantee not valid) | No |
| Under control | IE060 (Control decision notification) | No |
| Movement released | IE029 (Release for transit) | No |
| Not released for transit | IE051 (No release for transit) | Yes |
| Movement under resolution | IE019 (Discrepancies) | No |
| Movement written off | IE045 (Write-off notification) | Yes |
| Invalidated | a positive IE009 (Invalidation decision) | Yes |
The guarantee path is the one teams tend to miss. According to the document, when the guarantee check fails, the holder of the transit procedure receives IE055. If no IE013 amendment follows in time, customs sends IE051 and the goods are not released. Your status screen should treat IE055 as an action for the user, with a deadline, not as information.
At the office of destination, the arrival notification IE007 moves the movement to Arrival accepted. The IE025 goods release notification then carries a release indicator: a full release closes the movement as Goods released, while a partial release or no release leaves it waiting for the resolution of discrepancies. Here too, the state depends on a field in the message, not on its code.
The party at destination is often not the holder of the procedure at departure. Store the state of each office separately, and show your users the side they act on.
Rejections and amendments
Here a naive state machine breaks, because the same message code means different things depending on what it answers.
- Technical and business errors. IE917 means the XML was not processed at all, and in the NCTS document the movement has no state yet. IE906 (functional NACK) is also on the list of transit messages. A rejection such as IE056 means the content was checked and refused. Send technical errors to whoever maintains the integration, and business rejections, with the reason from the message, to the person who prepared the declaration.
- Amendments. An IE013 transit amendment is answered by IE004 (Amendment acceptance), and the state of the movement does not change. A rejected amendment is answered by IE056, and the state does not change either: the movement stays accepted, only the amendment failed. The document also notes that amendments are rejected while the declaration is under control. On the export side, an IE513 amendment is answered by IE504 or IE556.
- Invalidation. IE014 asks to invalidate a transit declaration. A positive IE009 sets the movement to Invalidated. After release, the document says, a request for invalidation is rejected automatically. For export, IE514 and IE509 lead to Cancelled.
- Enquiries. Movements that stay open can lead to an enquiry: IE582 (Request on non-exited export) for export, answered by IE583, and IE140 (Request on non-arrived movement) for transit, answered by IE141.
The practical rule: keep pending requests (an amendment, an invalidation, an answer to an enquiry) as separate records next to the main state. Correlate each response with the request it answers. Only then decide whether the main state changes.
MRN status tracking on the broker's screen
A broker's team needs fewer states on screen. A small set of user-facing statuses, each mapped from the customs states, works better:
| User-facing status | Customs states behind it |
|---|---|
| Sending | Sent, no answer from customs yet |
| Waiting for customs | Submitted, Accepted, Movement released, Goods Released for Export |
| Action needed | Rejected, Guarantee under amendment, an open enquiry, a rejected amendment |
| Under control | Under Control (export), Under control (transit) |
| Closed | Exported, Movement written off, Goods released |
| Stopped | Not Released for Export, Not released for transit, Export Stopped, Discrepancies at Exit, Invalidated, Cancelled |
Around that status, show what the user needs to act without reading XML: the LRN and the MRN, the reason text from the last rejection, the time since the last customs message, and, when transit follows export, a link from one movement to the other.
Three habits keep the status trustworthy: process each received message once, by its identifier; never leave a final state, but show a late message to a person; and record with every state change the message that caused it.
Warning
These states come from one customs administration's documentation. Before you build, compare them with the specifications of the national system you connect to.
How we can help
We build customs API integration for AES and NCTS, including the status of each movement: where each export or transit movement is, and what it is waiting for. The national connection and its certification stay with the party that holds them under the national rules.
