Shopify customs errors: every message, cause and fix

By Spencer Flaherty, founder of Origova

Shopify's customs error messages are terse and they all sound like the same problem. They aren't. Some are format validation, some are missing data, one is a geography surprise, and one only bites developers. This is the index: find your exact message, get the cause and the fix, and follow the link if you need the long version.

Quick index

"Harmonized code is invalid"

What Shopify is actually checking: the shape of the string, not whether the code is correct for your product. The rule is digits only, and an even number of them — 6, 8, or 10.

The five things that trigger it:

Fix: strip dots, spaces and letters, then count. If you land on 7 or 9 digits you've probably truncated a 8- or 10-digit national code — go back to the source rather than padding with a zero, because a padded code is a different classification. Dots are fine to type; Shopify strips them. Full breakdown of this error →

"HS codes and country of origin are required"

Cause: at least one item in the order has an empty HS code or country of origin. Shopify names the requirement but not the offending line item, which is why this one wastes so much time.

Fix for one order: open each product in the order → Shipping section → Customs information → fill both fields. Remember they're set per variant, so a product with five sizes has five separate places this data lives, and filling the first one doesn't fill the rest.

Fix for the pattern: if this keeps happening, the catalog has systematic gaps and fixing them order by order is a treadmill. Three ways to find every product missing a code → · Full breakdown of this error →

Customs information demanded on a "domestic" order

Cause: the order crosses a customs boundary that doesn't look like an international border. The usual suspects:

• US mainland → Puerto Rico, Guam, US Virgin Islands, American Samoa
• EU mainland → Canary Islands, Ceuta, Melilla (in the EU customs union for some purposes, outside for others)
• France → overseas departments such as Martinique or Réunion
• Your fulfilment location is in a different country than you assume — a 3PL or dropship supplier abroad makes every order international

Fix: check the actual origin and destination on the order rather than the customer's apparent country. If it's a territory case, the customs data is genuinely required and there's no way around it. Full breakdown →

Shipping label blocked at purchase

Cause: this is usually downstream of one of the errors above. Since the de minimis suspension, carriers require complete customs data before accepting an international parcel, so they've pushed validation to label purchase rather than risking a hold at the border. Shopify surfaces the rejection.

Fix: complete the customs fields on every variant in the order, then retry. Two things worth knowing:

• A description that reads as a real product matters too. "Item #4492-B" invites inspection; "women's cotton t-shirt" clears.
• A zero weight will block some carriers even when HS code and origin are present.

Don't route around this by switching carrier or service. The parcel still has to clear customs at the other end, and a label bought without complete data becomes a hold instead of a rejection — which is worse, because it happens after the customer is expecting delivery. Why carriers tightened this →

"Country of origin is required"

Cause: the field is empty. But there's a second, quieter failure here that produces no error at all and costs more: setting origin to where you ship from rather than where the product was made.

Country of origin means the country of manufacture or substantial transformation. A shirt made in Portugal and shipped from a New Jersey warehouse is Portugal. Declaring it as the US is a misdeclaration — it applies the wrong duty rate and forfeits any trade-agreement treatment the real origin might qualify for.

Fix: get origin from your supplier or the product label, not from your logistics setup. If you genuinely don't know for a product, that's a supplier question, not a guess. Where the field lives and how to set it in bulk →

Weight missing or zero

Cause: variant weight unset or left at 0, which is easy to miss because Shopify only enforces it at the point of buying a label.

Fix: set a real shipped weight per variant — packaging included, since that's what the carrier bills. Beyond the error itself, weight feeds duty-by-weight lanes in some destinations, so a placeholder value can produce a wrong duty assessment rather than a clean failure. Digital products and gift cards should be marked as not requiring shipping, which removes them from this check entirely.

GraphQL: harmonizedSystemCode rejected

Cause: the field isn't where most people look for it. HS code and country of origin live on the inventory item behind a variant, not on the product and not on the variant itself. Passing harmonizedSystemCode at product level in productCreate gets rejected or ignored.

Fix: set it through the inventory item — either nested as inventoryItem input on the variant mutation, or with a separate inventoryItemUpdate call carrying harmonizedSystemCode and countryCodeOfOrigin. Two things that catch people out:

• countryCodeOfOrigin takes a two-letter ISO code (PT), not a country name.
• The same even-digit validation from the admin applies at the API layer, and the error message is less helpful there.

Check the current field placement against Shopify's API reference for the version you're targeting — this has moved between versions. Origova's docs →

When the errors are a symptom, not the problem

One or two of these is a bad afternoon. Hitting them repeatedly means the catalog has systematic gaps, and every new product or supplier import reopens them. Shopify offers no report of which products are missing customs fields — the bulk editor will let you type codes but won't tell you where they're absent, and the product CSV has no column for two of the four fields.

That's the gap Origova fills: it scans the whole catalog, lists every variant missing an HS code, country of origin, or weight, flags malformed codes before Shopify or a carrier rejects them, and applies fixes in bulk — reversibly, written straight back to Shopify, with gift cards and digital products excluded automatically.

Frequently asked questions

Primary sources: the official Harmonized Tariff Schedule (hts.usitc.gov) and Shopify Help Center.

Related: Harmonized code is invalid: the fix · HS codes and country of origin are required · Customs info on a domestic order · Find products missing HS codes · Origova support