The trigger ? customs flagging products at borders

Approximately 3 years ago, Army & Outdoors started seeing shipments held up at customs in multiple destination countries. The cause: incomplete or missing HS codes (Harmonised System tariff classifications) and country-of-origin metadata on the products being declared.

Customs authorities globally were tightening enforcement around tariff codes. Without accurate HS codes per SKU, packages were either delayed at borders or returned at the seller's cost. Lost revenue, frustrated customers, and a real risk of being flagged as a non-compliant exporter.

The directive came down from the AAO director and my manager: fix this, and make it sustainable. No bandaging it for one shipment at a time ? build a system.

The solution ? single CSV, all stores, overnight

I built a tool that takes one input ? a CSV with three columns: SKU, HS code, country of origin ? and pushes the data to every regional Shopify store automatically. At the time, that meant NZ, AU, US, and Canada (the Canadian store has since been retired ? current footprint is NZ, AU, US, EU).

How it works

  1. The compliance team uploads a single CSV ? typically once a week at the start, now triggered when bulk updates are needed
  2. The CSV lands in a MySQL staging table
  3. A cron runs every minute, processing rows in small batches
  4. For each row: the system looks up the matching product in each regional store via the Shopify Admin API and updates the HS code + country of origin metafields
  5. Processing rate is paced to ~7 products per minute ? deliberately slow so it shares the Shopify API rate budget with the other production systems running in parallel (multi-store sync, marketplace feeds, reporting, etc.)
  6. Overnight the entire CSV processes through. Compliance team sees the staging queue empty in the morning.

The recent evolution ? different HS code formats per region

Earlier this year (2026), the requirement evolved. Different markets started requiring different HS code formats:

  • NZ + AU ? 6-digit HS code (the international standard base)
  • EU ? 8-digit HS code (combined nomenclature, EU's extended classification)
  • US ? 10-digit HTS code (Harmonized Tariff Schedule, US-specific extension)

This isn't a small tweak. The same product might be classified 610910 for NZ but needs to be 61091000 for the EU and 6109100012 for the US ? and Shopify stores them in different metafield structures depending on region.

I extended the tool to handle the format differences automatically. The compliance team still uploads a single CSV with the longest format (the 10-digit US HTS), and the system truncates correctly per region: 10 digits to US, first 8 digits to EU, first 6 to NZ/AU.

Current state ? bulk tool + ongoing process

Today the system runs in two modes:

  1. Ongoing ? when a product manager adds a new product, they enter the HS code + country of origin at creation time directly in Shopify. No tool needed for one-offs.
  2. Bulk updates ? when classifications change, regulations update, or a backlog of products needs codes assigned, the CSV tool handles it. One upload, processes overnight, all four regions in sync.

3+ years in production. Customs incidents related to HS code data have effectively stopped.

The technical bits worth noting

  • Rate-limit-aware pacing ? 7 products/minute is deliberate. Shopify Plus rate limit is 40 req/s shared across all API clients. Bursting through HS code updates would starve the multi-store sync and other systems sharing that budget.
  • Idempotent processing ? if the cron crashes mid-CSV, restarting it picks up where it left off. No duplicate updates, no skipped rows.
  • Per-region metafield handling ? early on I tried using countryHarmonizedSystemCodes with EU as a country code (which isn't valid). Pivoted to per-store harmonizedSystemCode metafields. The kind of detail you only catch by working with this API in production for months.
  • Audit trail ? every processed row is logged with timestamp + Shopify response. If customs queries a specific SKU later, we can show exactly when its HS code was updated and what value was set.

Why this matters for your store

If you're shipping internationally and don't have a system for keeping HS codes accurate across regions, you're carrying invisible risk. Most stores don't notice until shipments start getting held up ? and by then it's already costing you customer trust and refund handling.

The complexity scales fast: 1 product ? 4 regions ? 3 different code formats = 12 data points to keep accurate. Multiply by your catalogue size and you can see why manual maintenance breaks down at any real scale.

I've built this exact system for one multi-region retailer and it's been quietly preventing problems for 3+ years. If you're shipping to multiple regions and your customs data is patchy, this is a fixable problem.