Pro feature

Customs data

Why this layer exists

Charging VAT at checkout is only half of IOSS. The other half happens at the border: the customs declaration for the parcel must carry your IOSS number, or the import-VAT exemption cannot be granted. The customs data layer is the Pro feature that gets your IOSS number and per-item customs data to the systems that lodge those declarations. It requires a Pro license — see Licensing.

The failure mode, spelled out

If your IOSS number is missing or wrong on the declaration, VAT is levied at importation even though the customer already paid it at checkout. The customer pays VAT twice — plus the carrier’s disbursement fee for fronting the border charges. Those fees are not small: verified examples include a flat EUR 7.50 at Deutsche Post, EUR 6.95 at An Post, around 2% with a EUR 16.50 minimum at DHL Express in the Netherlands, and EUR 21.50 at bpost for low-value parcels; express carriers generally run 2–3.5% with EUR 10–17 minimums. Your customer, who chose you partly because the checkout said “no surprises at delivery,” gets a payment demand before the parcel is released.

Responsibility for supplying the number sits with you, the seller. And there is no safety net downstream: carriers can check only that a number is present, not that it is valid, and there is no mechanism to reclaim doubly-charged VAT through your IOSS return — the fix is refunding your customer and correcting your return, which is expensive and slow. Prevention is the whole game.

Electronically, not on the label

The IOSS number travels electronically — in the shipment data you transmit to the carrier or in your label platform’s tax-identifier field — so it lands in the customs declaration. Do not print it on the parcel or the packing slip: a visible IOSS number invites misuse by third parties, and printing is not how declarations are populated anyway. If you book shipments manually in a carrier portal, look for the IOSS/tax-ID field there.

Product fields: HS code and country of origin

Low-value customs declarations also want to know what the goods are and where they were made. Pro adds two fields to each product (variation-aware, so variants can differ):

  • HS code — the tariff classification (6 digits is the customary baseline for these declarations).
  • Country of origin — where the goods were manufactured, which is not necessarily where you ship from.

Fill these once per product and they flow into every shipment. Classifying products is your call — the fields record it, and your carrier’s requirements determine how much precision they demand.

The per-order snapshot and the filter

At capture time, Pro assembles a customs snapshot on the order: the IOSS number used, plus per-item description, quantity, HS code, origin country, and the EUR values fixed at payment acceptance (the EUR intrinsic value is the recommended figure for the commercial invoice). The snapshot is stored as order meta and exposed through a stable filter:

$data = apply_filters( 'ioss_customs_data', array(), $order );
// $data: ioss_number, items[] with description, quantity,
// hs_code, origin_country, value_eur, plus totals and fx rate.

Shipping integrations consume this contract to feed supported label plugins, and the same filter lets you wire up anything else — a custom carrier API, an ERP export, a fulfillment webhook — without touching plugin internals.

What to verify yourself

Send one test shipment and confirm with your carrier that the IOSS number actually arrived in their system. Five minutes of verification beats discovering the gap through a customer’s double-VAT complaint.