What is it?
Customs Declarations is a feature within Ingrid Transport (SOM API) that handles the declaration data required for cross-border shipments. When a shipment crosses a customs border, you include a customs_declaration object in the booking call — either inline or via a separate step before booking.
Customs declarations are legal documents. Ingrid provides a consistent API model and allows static per-route data to be pre-configured in booking rules. The retailer is the source of truth for product and order-specific customs data.
When is a customs declaration required?
Any shipment where the origin and destination are in different customs territories:
- EU → Norway
- EU → UK
- EU → Switzerland
- Any country → non-EU destination
- Åland Islands (treated as outside EU VAT area)
Tip: If you are unsure whether a route requires customs, check with your carrier. Including a declaration on domestic routes where it is not needed will not cause errors.
What data you must provide per order
For cross-border shipments, you must include accurate customs data in every booking call. This information comes from your product catalogue, ERP, or PIM — Ingrid cannot derive it automatically.
Per line item:
- HS tariff number
- Country of origin
- Declared value (in smallest currency unit — cents or öre, not whole units)
- Net and gross weight (in grams, not kilograms)
Per order:
- Seller identification numbers (EORI, VAT, VOEC, IOSS as applicable)
- Buyer identification numbers (if known — e.g. VOEC for Norway, PCCC for South Korea)
- Incoterms — determines who pays duties: DDP = seller pays, DAP/DDU = buyer pays
- Invoice number and date (if required by your carrier)
If customs data is missing or incorrect, the carrier may reject the booking or the shipment may be delayed or held at customs.
Three ways to provide customs data
Option 1: TOS ID booking
If you use Ingrid Delivery Checkout, you can book using a tos_id. Ingrid resolves shipment data (addresses, shipping method) from the checkout session — but you still need to include customs_declaration in the booking request.
Best for: Retailers using Delivery Checkout who want the simplest possible cross-border integration.
Option 2: Full API booking
Send the full shipment payload together with customs_declaration in a single shipments.createAndBook call.
Best for: Retailers not using Delivery Checkout, or those who prefer to provide all shipment data directly.
Option 3: Two-step flow (create, then upsert customs data)
Create the shipment first via shipments.create, add customs data separately via shipments.upsertCustomsDeclaration, then book via shipments.bookParcels.
Best for: Retailers where customs data comes from a separate system or pipeline step (e.g. ERP enrichment after shipment creation in WMS).
How booking rules reduce what you need to send
Many customs declaration fields are the same for every order on a given route — seller address and tax IDs, incoterms, currency, "sold-to" importer address. With booking rules, Ingrid can populate these static fields automatically at booking time, based on conditions like origin country, destination, or carrier product.
This means your integration only needs to send what genuinely changes per order: line items and their customs attributes.
What booking rules can auto-populate:
seller_identification_numbers— VAT, EORI per origin countryincotermsandplace_of_incotermscurrencysold_to— importer or customs broker address- Carrier-specific metadata
What you must always send per order:
items[]— HS tariff number, country of origin, value, net and gross weight per line itemcontents_typeandcontents_explanation(unless configured as a static rule)invoice_numberandinvoice_date(if required by carrier)
Booking rules are configured by the Ingrid team. To set them up, contact your integration manager or support@ingrid.com with your route setup and which fields are static per origin country or warehouse.
Examples
Swedish retailer shipping to Norway
A Swedish retailer (VOEC registered) ships from a single SE warehouse to Norwegian consumers. A booking rule for the SE → NO route sets the VOEC number, DDP incoterms, and SEK currency automatically. The retailer only sends item-level data per order. Consumers see no unexpected charges at delivery.
Pan-European retailer, multiple warehouses
A fashion retailer ships from warehouses in the UK and Sweden to EU and Norwegian customers. Separate booking rules are configured for GB and SE origins, each with the correct seller IDs, incoterms, and currency. The API payload is minimal — item data only. When tax IDs change, only the booking rule needs updating.
WMS-driven integration with separate customs enrichment
A retailer's WMS creates shipments at dispatch. Customs data (HS codes, values, weights) is produced by a separate ERP step. Using the two-step flow, the WMS creates the shipment, the ERP upserts customs data, and booking executes once everything is in place.
FAQ
-
Do I need to send customs declaration data if I book with a TOS ID?
Yes. A TOS ID reduces the shipment data you need to send, but cross-border shipments still require customs declaration data in every booking call. -
Can booking rules fully replace customs data in my API request?
No. Booking rules auto-fill static per-route fields, but item-level data (HS codes, values, weights, country of origin) must always come from your systems per order. -
What happens if customs data is missing or incorrect?
The carrier may reject the booking, or the shipment may be delayed or held at customs. Incorrect declarations can also have legal and financial consequences for the retailer. -
Can I update a customs declaration after booking?
No. Once a shipment is booked, the customs declaration cannot be changed. If corrections are needed, contact your carrier directly. -
Who do I contact to set up booking rules?
Contact your Ingrid integration manager or email support@ingrid.com with your route setup and which fields are static per origin country, destination, or carrier product.