DEV Community: iCustoms

Automating Intrastat Returns in Ireland From ERP Data

iCustoms — Tue, 13 Oct 2026 08:22:17 +0000

You can automate Intrastat returns in Ireland by extracting monthly EU movements from your ERP, mapping them to the five fields Revenue expects, validating codes and values before upload and filtering out Great Britain trade. Submission is the easy part. Reshaping ERP export data the same way every month is the real engineering problem.

The Data Model

Each movement on the return needs five fields. Here is where they usually live:

Nature of transaction (sale, return, repair): order or document type
8-digit CN commodity code: item master
Partner member state: ship-from or ship-to country
Net mass or supplementary quantity: item master or delivery, depending on the commodity
Statistical value: invoice or delivery value

Why Validation Must Happen Upstream

Revenue's Return Preparation Facility (RPF) and its arrival and dispatch templates do not validate commodity codes or value consistency. Whatever your pipeline sends is what gets filed. The rules these checks enforce come from the full guide to Intrastat reporting for Irish importers and exporters.

A Minimal Pre-Filing Check

THRESHOLD_EUR = 750_000  # confirm the current figure with Revenue

def check_line(line):
    errors = []
    if not (line["cn_code"].isdigit() and len(line["cn_code"]) == 8):
        errors.append("CN code must be 8 digits")
    if line["partner_state"] == "GB":
        errors.append("GB trade goes on AIS/AES, not Intrastat")
    if line["net_mass_kg"] is None and line["supp_qty"] is None:
        errors.append("Net mass or supplementary quantity missing")
    return errors

def must_file(direction_total_eur):
    return direction_total_eur > THRESHOLD_EUR

Keep Separate Totals Per Direction

Store arrivals and dispatches as two running totals. Each crosses the threshold on its own, and the obligation starts from that point, not retroactively.

Pull Codes From One Master Record

If a product carries different codes on AIS, AES and Intrastat, the datasets stop matching. Read the CN code from a single source for every filing.

Want this pipeline without building and maintaining it yourself? Watch a demo.

Pre-Submission Checks for Irish AIS Customs Declarations

iCustoms — Mon, 12 Oct 2026 11:17:53 +0000

AIS declaration validation is the most practical way to cut customs penalty risk in Ireland. Most penalties trace back to data problems a pre-submission check can catch: an inconsistent commodity code, an origin claim with no evidence attached or a declared value that doesn't reconcile with the invoice. This post outlines a validation workflow for declarations filed through Revenue's Automated Import System (AIS).

The Problem: Errors That Replicate

Revenue's Audit and Examination Programme reviews declarations after clearance and can look back across a business's history. A defect in your data pipeline, such as the wrong code mapped to a product, is not a single error. It is replicated on every filing that touches that product.

Four Checks to Run Before Submission

Each check below maps to one of the four violations behind most Irish customs penalty triggers.

1. Classification consistency

Compare the commodity code on the new declaration with the codes used for the same product in previous filings. Flag any change for human review.

2. Origin evidence

If a preferential rate is claimed, confirm that proof of origin is attached and still current.

3. Value reconciliation

Check declared values against the commercial invoice and packing list. They should reconcile every time.

4. Licence requirements

Flag restricted goods that need a licence and hold submission until one is recorded.

A Simple Validation Sketch

def validate(declaration, history, documents):
    issues = []

    prior_codes = history.codes_for(declaration.product_id)
    if prior_codes and declaration.commodity_code not in prior_codes:
        issues.append("Commodity code differs from previous filings")

    if declaration.preference_claimed and not documents.has_current_origin_proof():
        issues.append("Preferential origin claimed without proof of origin")

    if not reconciles(declaration.customs_value, documents.invoice):
        issues.append("Declared value does not reconcile with invoice")

    if declaration.requires_licence and not declaration.licence_ref:
        issues.append("Licence required but not recorded")

    return issues

Handling a NOT_RELEASED Status

If a declaration is flagged before release and returns a NOT_RELEASED status, treat it as a priority. An unresolved NOT_RELEASED outcome is one of the most direct routes into a penalty discussion.

Log Every Correction

Keep a consistent record of every declaration and every fix. Errors you find and correct yourself are viewed very differently from errors a Revenue review finds first.

Want to see this kind of validation logic running on live AIS declarations? Watch a demo.

Modelling the Irish Customs Declaration Lifecycle in AIS

iCustoms — Fri, 09 Oct 2026 11:00:23 +0000

An Irish customs declaration moves through a defined set of statuses in Revenue's AIS (imports) and AES (exports). Once submitted, it is registered, then accepted after automated checks. Revenue risk-scores it, and it is either released or selected for a documentary or physical control. Treating that lifecycle as a state model helps forwarders build reliable, alert-driven workflows.

The Status Model

Each status tells you who has to act next. Here is a simple reference table you can drop into a tracking tool:

STATUS                  MEANING                                        WHO ACTS
REGISTERED              Declaration received by Revenue                Wait
ACCEPTED                Passed initial automated checks                Wait
UNDER_CONTROL           Selected for documentary or physical checks    Monitor closely
AWAITING_SUPPLEMENTARY  More information or documents needed           You
RELEASED                Cleared, goods can be released                 Move the goods
NOT_RELEASED            Not cleared, goods cannot be released          Investigate

A control is not automatically a problem. It does need to be understood rather than ignored, so route UNDER_CONTROL and AWAITING_SUPPLEMENTARY straight to a person.

Validate Before You Submit

Most rejections and checks trace back to data that was wrong before submission. The AIS and AES filing guide for Irish freight forwarders lists the common causes, and they translate neatly into pre-submission checks:

def pre_submission_checks(dec):
    issues = []
    if dec.eori != dec.registered_eori:
        issues.append("EORI does not match registration")
    if dec.claims_preference and not dec.has_origin_proof:
        issues.append("Preference claimed without proof of origin")
    if dec.wants_pva and not dec.pva_elected:
        issues.append("Postponed VAT Accounting not elected")
    if dec.direction == "export" and not dec.lodged_before_departure:
        issues.append("AES declaration must be lodged before departure")
    for auth in dec.authorisations:  # AEO, special procedures, PVA
        if not auth.referenced:
            issues.append(f"{auth.type} authorisation not referenced")
    return issues

This is illustrative logic, not Revenue's rule set, but it mirrors the mistakes the source guide flags.

Set Realistic Timing Alerts

Most declarations that are not flagged clear within minutes to hours. A documentary or physical control can add days. Alert on anything sitting in ACCEPTED longer than your normal window.

Plan for AIS V2

AIS V2 introduces Centralised Clearance for Import and a revised Annex B data structure. If you map data into AIS, plan for that structural change now.

Want to see pre-submission validation running on real AIS and AES workflows? Watch a demo of iAIS and iAES.

TSS Portal Validation Rules: Rule-Based vs Content Checks

iCustoms — Thu, 08 Oct 2026 10:32:28 +0000

TSS Portal validation rules are deterministic checks that confirm a customs declaration's structure: required fields are present, codes exist, formats match and references resolve. They cannot test semantic correctness. A valid commodity code can still be the wrong code for the goods, which is why a content validation layer before the Portal matters.

How the Portal's rules are layered

Validation runs at two scopes:

Field level: some checks fire as each field is filled in.
Declaration level: others run across the whole declaration before submission. The rule set covers six types: format and completeness, goods-line business rules, consignment-level checks, item-level controlled goods, CERTEX certificate matching, and scheme and authorisation checks.

What a rule can and can't assert

A rule can assert presence, existence, format and reference. It can't assert truth, which is why three classes of error pass the TSS Portal validation rules untouched.

Error	Why the rule passes it
Wrong commodity code for the goods	The code exists and is current
Certificate that doesn't cover the consignment	The reference matches the expected format
Description too vague to classify	The field is complete

Adding a content validation layer

Think of the workflow as a pipeline with two validation stages:

declaration
  -> content validation (before the Portal)
       commodity code     vs goods description
       certificate ref    vs certificate data
       preference claim   vs evidence on file
  -> TSS Portal rules
       format, completeness, goods-line, consignment,
       controlled goods, CERTEX, scheme/authorisation
  -> submission

AI-powered validation handles the first stage by reading content instead of checking format. The Portal then handles the second.

Why order matters

Automating submission without validating first produces wrong declarations faster. Catching an error upstream costs less than handling a rejection downstream.

Want to see a content validation layer running ahead of TSS? Watch a demo.

Validating TSS Controlled Goods Data Before Submission

iCustoms — Wed, 07 Oct 2026 11:03:44 +0000

TSS controlled goods data validation means checking, before you submit, that every controlled line carries the right licence or certificate, the correct document and status codes, item-level data and, for SPS goods, a Net Mass. It also means confirming the reference numbers match the certificate itself, because health certificates are checked against CERTEX and a mismatch is likely to trigger an inspection.

Where controlled goods logic lives

Control status isn't a field you set. It comes from the measures and conditions attached to a commodity code on the Northern Ireland Online Tariff, for the correct country of origin, plus any footnotes on the commodity page.

The data model for a controlled goods line

A controlled line needs more fields than a standard movement. The field list below follows iCustoms' write-up on TSS customs data for controlled goods.

Field	When it applies
Consignment and item-level entry summary data	Controlled goods (standard movements need consignment level only)
Document code and status code	Every certificate or licence (GOV.UK Appendix 5A and 5B)
National Additional Code	Where the commodity code lookup returns one
Net Mass at item level	All SPS controlled goods
Goods Domestic Status = `NIDOM`	GB to NI domestic movements
Status code `XW` with "Waiver claimed"	Products of animal origin or high-risk food where a CHED isn't required

Image suggestion: Image 4, "One Mismatch, One Outcome" | Alt text: Validation outcome where a declaration matching its certificate clears and a mismatch is referred

A pre-submission check in pseudocode

for line in declaration.lines:
    measures = ni_online_tariff.lookup(line.commodity_code, line.origin)
    if measures.require_document():          # read conditions and footnotes too
        assert line.document_code and line.status_code
        assert line.document_ref == line.certificate.reference
        if line.category == "SPS":
            assert line.net_mass is not None
if declaration.movement == "GB_TO_NI_DOMESTIC":
    assert declaration.goods_domestic_status == "NIDOM"

Troubleshooting TSS controlled goods data

Inspection referral: compare the declaration reference with the health certificate, since CERTEX checks one against the other.
Missed control: re-read the footnotes on the commodity page.
Unexpected measures: re-run the lookup with the correct country of origin. Want to see these checks run automatically inside a TSS workflow? Watch a demo.

B2B Parcel Declaration Workflow: Decision Logic for TSS

iCustoms — Tue, 06 Oct 2026 10:29:31 +0000

A B2B parcel declaration workflow for Northern Ireland is a short chain of decisions: classify the movement, test whether the goods are at risk, check UKIMS cover, then route the data to the right declaration. If you build or maintain systems that feed TSS, it helps to model this logic explicitly so every rule is easy to trace.

Step 1: Classify the Movement

Only business to business parcels enter this workflow. Consumer parcels for personal use need no customs declaration, and correspondence sits outside the rules entirely.

Step 2: Model At-Risk Status and Route

Goods can count as not at risk on duty rates alone, or move under UKIMS held by either party. Here is the logic as Python-style pseudocode, based on the published rules for declaring B2B parcels through TSS.

def not_at_risk_by_duty_rate(goods):
    if goods.in_gb_free_circulation:
        return goods.eu_rate == 0
    if goods.from_outside_eu_uk:
        # UK rate no more than 3 points below the EU rate
        return goods.uk_rate + 3 >= goods.eu_rate
    return False

def declaration_route(goods, sender, receiver):
    ukims = sender.has_ukims or receiver.has_ukims  # one side is enough
    if ukims and not goods.at_risk_of_moving_to_eu \
            and goods.for_uk_end_consumers:
        return "IMMI"  # no full declaration, no duty
    return "FULL_DECLARATION"  # EU-rate duty may apply

Step 3: Pick the EORI Prefix

eori_prefix = "XI" if (biz.established_in_ni or biz.fixed_place_in_ni) else "GB"

Step 4: Pass the Right Data

In TSS, goods that qualify under UKIMS go through Internal Market Movement Information (IMMI). Others need a full declaration. Either way, goods are still categorised as Standard, Category 1 or Category 2. If a carrier declares for you, pass it the UKIMS authorisation number and the associated EORI number.

Step 5: Store the Evidence

TSS does not decide UKIMS eligibility or at-risk status. Store the evidence behind each decision for five years against the movement it supports.

Edge Cases Worth Coding For

Mixed order books: flag each parcel as B2B or consumer, because carriers handle the two differently.
Entry summary declarations: only some parcel movements need one, so don't reuse a freight rule here.
Declaration channel: TSS, a carrier's service or a customs intermediary can submit, and each must apply the same duty-rate, UKIMS and processing conditions.
UKIMS-EIDR users: businesses declaring with their own software can apply the same UKIMS conditions to parcel movements. Prefer not to build this logic yourself? iCustoms runs the UKIMS eligibility and not-at-risk checks against your goods data for you. Watch a demo.

Modelling the TSS At-Risk Decision Logic in Pseudocode

iCustoms — Mon, 05 Oct 2026 10:32:08 +0000

The TSS at-risk decision logic can be modelled as an ordered set of rules. Hard stops come first and always return at risk. The duty-rate test comes next and can return not at risk without any authorisation. UKIMS conditions follow. Anything left over is at risk and pays the applicable EU rate of duty.

The inputs the decision needs

If you build or maintain tools that prepare GB to NI declarations, these are the fields the rules depend on:

origin: GB_FREE_CIRCULATION or OUTSIDE_EU_UK
eu_rate and uk_rate: duty rates, compared in percentage points
processed_in_ni: whether the goods will be processed in Northern Ireland before sale or use
processing_condition_met: turnover under £2 million, quota sheepmeat, poultry or beef, or an approved purpose
trade_remedies: whether EU trade remedies such as anti-dumping or countervailing duty apply
importer_holds_ukims and uk_end_consumer ## The decision function

The order below follows the TSS at-risk decision rules published by iCustoms.

def at_risk_status(g):
    # Hard stops: UKIMS cannot offset these
    if g.trade_remedies:
        return "AT_RISK"
    if g.processed_in_ni and not g.processing_condition_met:
        return "AT_RISK"
    if g.origin == "OUTSIDE_EU_UK" and (g.eu_rate - g.uk_rate) > 3:
        return "AT_RISK"

    # Duty-rate test: no authorisation needed
    if g.origin == "GB_FREE_CIRCULATION" and g.eu_rate == 0:
        return "NOT_AT_RISK"
    if g.origin == "OUTSIDE_EU_UK" and g.uk_rate >= g.eu_rate - 3:
        return "NOT_AT_RISK"

    # UKIMS route
    if g.importer_holds_ukims and g.uk_end_consumer:
        return "NOT_AT_RISK"

    return "AT_RISK"

Image suggestion: Image 3, Two Routes to Not at Risk
Alt text: Flow showing the duty-rate test and UKIMS authorisation as two routes to not at risk, with processing and trade remedy blocks

Mapping the result to duty

def duty_basis(g, status):
    if status == "AT_RISK":
        return "Applicable EU rate"
    if g.origin == "GB_FREE_CIRCULATION":
        return "No duty"
    return "UK duty"

Where TSS fits in the workflow

TSS does not run this logic for you. It is where the result is declared, using the Additional Information code, and where the Trader Goods Profile and IMMI or declaration data come together. The judgement and the evidence behind it stay with the trader.

That evidence means commercial receipts and invoices, VAT invoices, commercial contracts and, where relevant, Northern Ireland end-use declarations, kept for five years and accessible in the UK.

A note on scope

This is a simplified model to show the rule order. It explains the logic; it does not replace a proper assessment of each movement.

Building GB to NI declaration workflows and want to see how iCustoms approaches them? Watch a demo.

TSS Trader Goods Profile Fields: A Technical Breakdown

iCustoms — Fri, 02 Oct 2026 08:04:04 +0000

A TGP entry in the Trader Support Service is a structured record with six data points: product reference, goods description, commodity code, country of origin, category and an optional supplementary unit. Four are entered by the user, one is conditional and one (category) is assigned by TSS. A computed IMMI Ready flag then shows whether the record is usable on an IMMI submission.

The TGP as a Data Model

Think of the Trader Goods Profile as a table scoped to an EORI. Each row is one product. The profile is created automatically once a business holds UKIMS authorisation and a Customs Declaration Service subscription, so the container exists before you add any rows.

Field Rules and Validation

Each field has its own rule, and getting these right at entry time avoids rework later. You manage all of them through the TGP entries in the TSS portal.

Field	Source	Rule
Product Reference	User	Must be unique. Duplicates are not permitted.
Goods Description	User	Clear and specific. Generic terms slow HMRC review.
Commodity Code	User	6, 8 or 10 digits, validated against the Northern Ireland Online Tariff
Country of Origin	User	Where the goods were produced
Supplementary Unit	User, conditional	Added only where the goods require one
Category	System	Standard, Category 1 or Category 2

System-Derived Values

IMMI Ready

A boolean (true or false). It reports data quality only. It does not evaluate whether a movement is eligible for IMMI.

Record Lifecycle

Create: select Create New TGP Entry on the Management page, complete the fields and save.
Read: find entries with keyword search or column sorting.
Update: edit the fields, click Categorise to re-run categorisation, then save.
Delete: select Delete and confirm. The record is removed from HMRC's Trader Goods Profile and TSS screens. Write access to all four operations depends on portal permissions.

Want to see TGP data kept accurate and IMMI ready at scale? Watch a demo of iCustoms.

EIDR Data Flow Explained for Developers and Ops Teams

iCustoms — Thu, 01 Oct 2026 08:29:52 +0000

The EIDR data flow starts with a record in your own commercial books and ends with a supplementary declaration that closes. EIDR, Entry in Declarant's Records, replaces the upfront submission to customs for standard, non-controlled goods. If you build or maintain customs tooling, this is the sequence of identifiers and data your systems need to handle.

The flow at a glance

Movement happens
  -> Record in own books (EIDR created, via TSS or your own tooling)
  -> LRN + MRN + procedure code passed to transporter
  -> Goods movement reference created on GVMS
  -> Goods arrive in Northern Ireland
  -> Draft supplementary declaration appears in your account
  -> Complete and submit by the 10th calendar day of the next month
  -> Declaration closes

Identifiers to carry through

The Local Reference Number (LRN) is generated when the EIDR form is saved. If you created the EIDR yourself, hand that LRN to the haulier or intermediary handling the entry summary declaration. The Movement Reference Number (MRN) and the procedure code go to the transporter too. For a deeper walkthrough, see the TSS EIDR explained guide.

Data for the supplementary declaration

The supplementary declaration needs parties, goods and transport information. These come from commercial invoices, packing lists and transport documents. TSS pre-fills some fields from your EIDR, so store the original EIDR data in a form you can compare against.

Design notes

Treat the LRN, MRN and procedure code as required fields on any hand-off to a transporter.
Model the supplementary declaration as a dated obligation tied to the movement.
Keep the trader as the accountable party in your data model, even when TSS submits. Want to see how iCustoms connects these steps? Watch a demo.

Trader Goods Profile Fields Explained for UKIMS Users

iCustoms — Wed, 30 Sep 2026 08:03:00 +0000

A Trader Goods Profile is created automatically when a business registers for UKIMS. Each record holds five fields: goods description, commodity code, product reference, country of origin and category. When you complete an IMMI, you can select a profile entry instead of retyping the commodity data.

What a profile record holds

Think of each entry as one row of product master data. This sketch shows the shape of a record. It is illustrative, not an official schema.

{
  "goods_description": "<text>",
  "commodity_code": "<code>",
  "product_reference": "<your own reference>",
  "country_of_origin": "<country>",
  "category": "<Standard | Category 1 | Category 2>"
}

What populates and what you type

When you select a profile entry in an IMMI, the commodity code, origin and description populate automatically. You enter the product reference or a simple description by hand, plus the usual commercial detail: quantity, weight and value. For a business that moves the same range of products repeatedly, this is the biggest reduction in manual entry that IMMI offers. The wider context sits in this UKIMS and TSS customs declarations guide.

Keeping the profile useful

Keep one entry for each product you regularly move.
Check the category field carefully. Category 1 goods are always excluded from the UKIMS routes.
Review commodity code and origin before you rely on them, because they populate straight into the declaration. ### Is a Trader Goods Profile created automatically?

Yes. It is created when a business registers for UKIMS, so you do not build it from scratch.

Want a single place for UKIMS numbers, profiles and eligibility checks? Watch a demo.

IMMI Submission Workflow in TSS: Six Steps Before the Move

iCustoms — Tue, 29 Sep 2026 07:17:10 +0000

The IMMI submission workflow has six steps: confirm eligibility, create the movement, add the consignment, complete the goods record, attach documents and submit. When it finishes, TSS issues two reference numbers and the status changes to Authorised for Movement.

Overview

Submitting before the movement is the more typical route. It also produces the reference numbers the haulier needs. Vehicle and trailer details can be updated up to four hours before arrival, but goods data should be right earlier.

The six steps

For a detailed walkthrough, see iCustoms' guide to step-by-step IMMI submission through TSS.

Confirm eligibility. Goods are not at risk, in free circulation, the right category, with UKIMS authorisation on the correct side.
Create the movement. Enter transport details and an arrival date within 14 days. Later dates save as a draft.
Add the consignment. Validate the importer's EORI number against the UKIMS authorisation in use.
Complete the goods record. Select a Trader Goods Profile entry or enter data by hand, then confirm the procedure and additional procedure code.
Attach documents. Include the document code that confirms not-at-risk status.
Submit. Status moves to Authorised for Movement. ## State changes to watch

State	What it means
Draft	Arrival date is more than 14 days away
Authorised for Movement	Submitted; TSS has issued both reference numbers

After submission

TSS issues the Entry Summary Declaration and IMMI Movement Reference Numbers. Roll-on roll-off hauliers use both to build the Goods Movement Reference.

Why the order matters

Eligibility comes first because a failed condition changes the route. If any condition fails, the movement falls back to the TSS Simplified Procedure or a full frontier declaration. For roll-on roll-off movements, the haulier then needs both reference numbers to build the Goods Movement Reference before the vehicle can board.

Want to walk through this workflow with a specialist? Watch a demo.

The NCTS Declaration-to-Discharge Workflow

iCustoms — Mon, 28 Sep 2026 07:58:08 +0000

A transit movement passes through a clear sequence of states, and each one is tied to a reference number or message. Understanding the order makes it obvious why the LRN and MRN cannot be swapped.

The state sequence

Draft declaration created and tagged with an LRN.
GRN and access code validated against the principal's details.
Declaration accepted, MRN issued, guarantee reduced.
Movement travels through offices of transit under the MRN.
Office of destination confirms arrival and match.
IE045 discharge message sent, guarantee restored. ## Where it can stall

If the GRN or access code is wrong, the declaration is rejected before the MRN is issued. If no IE045 arrives within 60 days, the movement enters an enquiry procedure that ends with a discharge letter.

This walk through the NCTS declaration to discharge workflow covers each handoff in order.

The guarantee state

The guarantee tracks the movement: reduced at MRN issue, restored at discharge. Treating discharge as a state to confirm, not assume, keeps the balance accurate.

Ready to see the workflow in one view? Book a demo.