Nothing halts a launch day like an error that looks harmless but blocks everything from ads to checkout. “Supplied countryName is invalid” is one of those deceptively simple errors that can derail paid campaigns, catalogs, checkout flows, and CRM syncs. On the Watsspace Digital Marketing Blog, we’re tackling this head-on with a practical, SEO-friendly guide that shows exactly what the message means, where it appears across your martech stack, how to fix it fast, and how to prevent it for good—so your ads serve, your feeds approve, and your revenue flows.

What the “Supplied countryName is invalid” error actually means

At its core, this error indicates a mismatch between the value you provided for a country field and what the receiving platform expects. Most modern platforms do not accept a free-form country name; they require a standardized country code, nearly always the ISO 3166-1 alpha-2 two-letter code (like US, GB, DE), sometimes the three-letter alpha-3 code (like USA, GBR, DEU), and rarely a full localized name.

Common triggers include:

Sending “United States” when the API expects “US”
Submitting “UK” where only “GB” is accepted
Providing “Russia” when canonical RU is required
Using characters or encodings that the platform rejects (e.g., “Côte d’Ivoire” vs “Cote d’Ivoire”)
Passing unsupported territories (e.g., “Kosovo” often needs “XK” in some systems but is absent from ISO 3166 lists)

Why the confusion? Each platform has a documented set of allowed values for country, sometimes called countryName, country_code, country, or shipping_country. If you don’t normalize upstream, the receiving system flags the input as invalid.

Authoritative guidance: ISO 3166-1 alpha-2 is the global standard for country codes (source: ISO 3166 Maintenance Agency). Major martech platforms and payment gateways reference this standard directly or indirectly in their documentation (sources: Google Merchant Center Help, Meta for Developers, Shopify Admin API, Stripe API Reference).

Where marketers commonly see this error

Digital marketing teams run into “Supplied countryName is invalid” in a handful of high-impact workflows:

Product feeds into Google Merchant Center, Meta Commerce Manager, and marketplaces
Ad platform APIs when creating audiences, locations, or assets (Meta Marketing API, LinkedIn, TikTok)
Checkout and payments with Stripe, PayPal, Adyen, Braintree, and Shopify Payments
CRM or CDP integrations (HubSpot, Salesforce, Segment) when normalizing address fields
Analytics and attribution (GA4, BigQuery pipelines) when joining geographic dimensions
Custom forms and landing pages where free-text inputs feed downstream systems

The stakes are high. A single invalid country can get a product disapproved, prevent an ad set from running in a key region, throw a 400 error during checkout, or break nightly syncs.

Fast checklist to resolve the error now

Confirm the platform’s expectation: ISO 3166-1 alpha-2 is the default; check the exact field name and constraint in docs.
Map your input to the correct code (e.g., United States → US, United Kingdom → GB, South Korea → KR).
Normalize casing to uppercase two-letter codes (US, GB, DE).
Trim whitespace and remove non-printable characters.
Handle common synonyms (“Ivory Coast” → CI, “Russia” → RU, “Viet Nam” → VN).
Verify encoding (UTF-8) for names with diacritics (“Côte d’Ivoire”).
Check for unsupported territories and use the platform’s accepted substitute if documented.
Resend the corrected payload and monitor logs to ensure no other fields fail.

Accepted formats by major platforms

Different systems emphasize different fields and value formats. Use this as a quick-reference before you transform your data.

Platform	Field name (typical)	Accepted value	Example valid	Example invalid	Source
Google Merchant Center	shipping:country, tax:country	ISO 3166-1 alpha-2	US, GB, DE	United States, UK, Germany	Google Merchant Center Help
Meta Commerce/Marketing API	country, shipping_country, targeting geo	ISO 3166-1 alpha-2	US, FR, AU	USA, France, AUSTRALIA	Meta for Developers
Shopify (Storefront/Admin API)	countryCode, country	ISO 3166-1 alpha-2	CA, JP, BR	CAN, Japan, brazil	Shopify Admin API
Stripe	country, address.country	ISO 3166-1 alpha-2	NL, ES, SG	Netherlands, ESP, Singapore	Stripe API Reference
PayPal	country_code	ISO 3166-1 alpha-2	IT, NO, MX	Italy, NOR, Mexico	PayPal Developer Docs
HubSpot/Salesforce	Country, Mailing Country (varies)	Configured picklist or ISO codes	US, GB	USA, UK (if expecting GB)	Platform Admin Docs

Important nuance: Some systems appear to accept names in the UI but store codes under the hood. If your integration hits the API layer, assume it needs the code.

Common root causes (and how to diagnose each)

Code vs. name mismatch: You pass “Germany” while the platform wants “DE.” Diagnose by checking logs for 400/422 responses and the API field documentation.
Case sensitivity: Some systems require uppercase (US not us). Normalize to uppercase as a rule.
Whitespace and hidden chars: Trailing spaces or zero-width spaces can trigger failures. Log inputs with visible delimiters or hex dumps to detect.
Encoding issues: Diacritics (Å, É, Ō) can break naive transformations. Ensure UTF-8 end-to-end and sanitize before submission.
Synonyms and legacy names: “Ivory Coast,” “Czechia,” “Viet Nam,” “Swaziland” (now Eswatini). Maintain a synonym map.
Territories and regions: “UK” vs “GB,” “Hong Kong” (HK), “Macau” (MO), “Taiwan” (TW). Some platforms treat them distinctly—always follow platform lists.
Unsupported geos: Not all platforms support every country. If a platform doesn’t support ads or shipping to a region, it may reject that value outright.
UI-to-API disconnect: Marketers select a country from a drop-down, but a custom theme or script passes the wrong value to the API. Inspect network requests in DevTools.
Data drift in integrations: CSVs, ETL jobs, and CDP transformations can strip formatting or convert codes to unexpected values (e.g., Excel auto-formatting). Add validation before export.

Fixing the error in product feeds (Google Merchant Center and Meta)

Product feeds are fertile ground for this issue because shipping and tax configurations include country fields. Here’s how to correct them:

Google Merchant Center

Use ISO 3166-1 alpha-2 codes in the shipping and tax attributes (source: Google Merchant Center Help).
Transform upstream: If your source lists full names, create a feed rule or transform that maps names to codes.
Avoid “UK”; prefer GB. “UK” is not the ISO alpha-2 code, even if it’s colloquially used.
Validate your feed in the “Diagnostics” tab and fix item-level disapprovals.

Meta Commerce/Marketing

Catalog feeds should contain two-letter country codes wherever a country field is expected (source: Meta for Developers).
Targeting in ads uses country codes for geo. If you bulk upload audiences or locations, pre-normalize to codes.
Encoding matters: If your product titles or descriptions include special characters, make sure file encodings don’t corrupt the line with the country attribute.

In both ecosystems, build a reusable mapping layer so every export writes a canonical code once, consistently.

Fixing the error in Shopify and WooCommerce

Storefront tools make this easier with built-in picklists—but customizations and third-party apps can reintroduce errors.

Shopify

Forms and themes: Ensure your checkout or custom form passes countryCode as ISO alpha-2 (source: Shopify Admin API).
App conflicts: Some apps collect addresses in popups or embedded widgets. Test the payload they emit; if they send names, normalize before creating orders or customers.
Exports: When exporting customers/orders, configure exports to include or map to ISO codes so downstream systems don’t choke.

WooCommerce

Country field in checkout typically uses ISO codes under the hood. Custom checkout fields or translations can break this—confirm the POSTed value.
Shipping plugins: Carrier plugins may reject non-ISO values. Cross-check plugin docs and perform a test label.

Fixing the error in payment gateways (Stripe, PayPal, Adyen)

Payments are strict. If you pass a non-ISO value, you’ll often get a hard failure.

Stripe: Use uppercase ISO alpha-2 for country on accounts, customers, payment methods (source: Stripe API Reference). Example: US, not United States.
PayPal: Set country_code to ISO alpha-2 (source: PayPal Developer Docs).
Adyen: Follows ISO 3166; ensure consistent 2-letter codes in address objects and risk checks.

Extra checks:

Merchant country vs. buyer country: Some products require your merchant account to be in a specific country. Errors can be misinterpreted if you mix them up. Verify you’re fixing the buyer address not the account country.
Sandbox vs. live: Sandboxes sometimes have narrower validation sets. Test both if a value fails unexpectedly.

Programmatic normalization: production-ready examples

Stop fixing this one payload at a time. Implement a robust normalization layer and apply it across catalogs, forms, APIs, and ETL jobs.

JavaScript/TypeScript utility

// Minimal ISO alpha-2 mapping (expand for production)
const COUNTRY_MAP = {
  "united states": "US",
  "usa": "US",
  "us": "US",
  "united kingdom": "GB",
  "uk": "GB",
  "great britain": "GB",
  "england": "GB",
  "scotland": "GB",
  "wales": "GB",
  "northern ireland": "GB",
  "germany": "DE",
  "deutschland": "DE",
  "ivory coast": "CI",
  "côte d’ivoire": "CI",
  "cote d'ivoire": "CI",
  "russia": "RU",
  "russian federation": "RU",
  "south korea": "KR",
  "republic of korea": "KR",
  "vietnam": "VN",
  "viet nam": "VN",
  "czechia": "CZ",
  "czech republic": "CZ",
  "kosovo": "XK" // Note: XK is not ISO standard; use only if your platform accepts it
};

function normalizeCountry(input) {
  if (!input) return null;
  const cleaned = input.toString().trim().toLowerCase();
  // Two-letter code path
  if (/^[a-z]{2}$/i.test(cleaned)) return cleaned.toUpperCase();
  // Map known synonyms
  if (COUNTRY_MAP[cleaned]) return COUNTRY_MAP[cleaned];
  // Fallback: remove accents and retry
  const ascii = cleaned.normalize("NFD").replace(/[u0300-u036f]/g, "");
  if (COUNTRY_MAP[ascii]) return COUNTRY_MAP[ascii];
  return null; // Unknown; trigger validation error upstream
}

// Example:
console.log(normalizeCountry("United States")); // US
console.log(normalizeCountry("uk")); // GB
console.log(normalizeCountry("Côte d’Ivoire")); // CI

Python normalization with a whitelist

import unicodedata

ALPHA2 = {
    "US", "GB", "DE", "FR", "CA", "AU", "NZ", "NL", "SE", "NO", "DK", "FI",
    "IT", "ES", "PT", "IE", "CH", "AT", "BE", "LU", "PL", "CZ", "SK", "HU",
    "RO", "BG", "GR", "TR", "RU", "UA", "CN", "JP", "KR", "VN", "IN", "ID",
    "MY", "SG", "TH", "PH", "HK", "MO", "TW", "AE", "SA", "IL", "EG", "ZA",
    "BR", "AR", "CL", "MX"
}

SYNONYMS = {
    "united states": "US",
    "usa": "US",
    "united kingdom": "GB",
    "uk": "GB",
    "cote d'ivoire": "CI",
    "côte d’ivoire": "CI",
    "ivory coast": "CI",
    "russia": "RU",
    "russian federation": "RU",
    "viet nam": "VN",
    "vietnam": "VN",
    "czechia": "CZ",
    "czech republic": "CZ",
    "south korea": "KR",
    "republic of korea": "KR",
    "kosovo": "XK"  # platform-specific
}

def normalize_country(value: str) -> str | None:
    if not value:
        return None
    v = value.strip()
    if len(v) == 2 and v.isalpha():
        return v.upper()
    low = v.lower()
    if low in SYNONYMS:
        return SYNONYMS[low]
    ascii_low = unicodedata.normalize('NFD', low).encode('ascii', 'ignore').decode('ascii')
    if ascii_low in SYNONYMS:
        return SYNONYMS[ascii_low]
    return None

def is_valid_alpha2(code: str) -> bool:
    return code in ALPHA2

# Example:
code = normalize_country("United Kingdom")
print(code)  # GB
print(is_valid_alpha2(code))  # True

SQL guardrail in your data warehouse

-- Flag rows with invalid or non-ISO countries before export
WITH src AS (
  SELECT id, country
  FROM customer_staging
),
normalized AS (
  SELECT
    id,
    UPPER(TRIM(country)) AS country_clean
  FROM src
)
SELECT *
FROM normalized
WHERE NOT REGEXP_CONTAINS(country_clean, r'^[A-Z]{2}$');

Apply these utilities at the earliest touchpoint—form submission, ETL entry, or pre-API hook—and log mismatches with context so you can address upstream sources.

Special cases and geopolitical gotchas

Even if you follow ISO rules, you’ll encounter edge cases. Here’s how to handle the ones marketers see most.

UK vs. GB: ISO alpha-2 code is GB, not UK. Some platforms accept UK as an alias; many do not. Prefer GB.
Kosovo: Not officially assigned in ISO 3166-1. Some systems accept XK as a user-assigned code; others reject it. Check your platform’s docs.
Hong Kong (HK), Macau (MO), Taiwan (TW): Distinct from CN in many platforms; use their own codes when asked for a country.
Ivory Coast: Canonical ISO English short name is “Côte d’Ivoire”; code is CI. Normalize both “Ivory Coast” and “Côte d’Ivoire” to CI.
Czechia: Official short name since 2016; code CZ. Accept both “Czech Republic” and “Czechia” as CZ.
Eswatini: Formerly Swaziland; code remains SZ.
Russia: Code RU. Avoid “RUS” (alpha-3) unless explicitly allowed.
United States: Always US, not USA in alpha-2 fields.
Åland Islands: AX. Watch out for diacritics in source feeds.
Congo: Two countries—CD (Congo – Kinshasa, DR Congo) and CG (Congo – Brazzaville, Republic of the Congo).

Keep a clearly documented exception list in your codebase or feed rules so the next person knows exactly how to map these cases.

Country synonyms and canonical codes quick-reference

Use the following reference to resolve the most frequent mismatches we see in marketing operations.

Input (common)	Canonical ISO alpha-2	Notes
United States, USA, U.S.A.	US	Never use USA in alpha-2 fields
United Kingdom, UK, Great Britain, England, Scotland	GB	Use GB; do not use UK unless explicitly allowed
South Korea, Republic of Korea	KR	North Korea is KP
Russia, Russian Federation	RU
Vietnam, Viet Nam	VN	Both spellings map to VN
Czechia, Czech Republic	CZ
Ivory Coast, Côte d’Ivoire	CI	Normalize diacritics
Bolivia	BO	Full official name is long; code is BO
Hong Kong	HK	Distinct from CN
Macau, Macao	MO	Distinct from CN
Taiwan	TW	Use TW where accepted
Kosovo	XK	Non-ISO; platform-specific
Vatican, Holy See	VA
Syria	SY	Don’t use SYR in alpha-2 fields
Laos, Lao PDR	LA
Brunei, Brunei Darussalam	BN
Swaziland, Eswatini	SZ	Updated country name; code unchanged
Cape Verde, Cabo Verde	CV
Burma, Myanmar	MM
East Timor, Timor-Leste	TL

Why this matters for marketing, SEO, and revenue

Beyond simply “making the error go away,” correct country codes directly impact:

Feed eligibility: Wrong shipping/tax country values lead to product disapprovals or limited serving in Merchant Center and Meta catalogs (sources: Google Merchant Center Help, Meta for Developers).
Ad delivery and cost: Mis-targeted or rejected geo settings waste budget or reduce reach.
Checkout conversion: Unclear or strict validations cause user drop-offs. Research shows checkout friction from form errors is a persistent driver of abandonment (source: Baymard Institute).
Analytics accuracy: GA4, BI dashboards, and MMM models rely on consistent geographies for segmentation and attribution.
Localization and SEO: Correct geographies help maintain clean site experiences and structured data. Consistency reduces the risk of serving mismatched shipping information to searchers.

Quality assurance and monitoring practices to prevent regressions

Build a lightweight, reliable safety net so country issues don’t crop up again during a campaign push.

Centralize mapping: Maintain a single source of truth (SSOT) for country code mappings used by all services.
Add preflight validators: Before sending data to an API, assert alpha-2 compliance and log violations.
Use test fixtures: Keep fixtures with edge cases like diacritics and ambiguous names.
Dashboard error rates: Track 4xx API errors involving country fields by service and endpoint.
Data contracts: Define schema, types, and allowed values for shared events (e.g., customer_created.country must be [A-Z]{2}).
Sample production payloads: Periodically sample and lint to catch drift from spreadsheets, CSV edits, or ad hoc scripts.

Example observability event

{
  "event": "api_request_failed",
  "service": "feed_uploader",
  "field": "shipping_country",
  "value": "United States",
  "expected_format": "ISO_3166_1_ALPHA_2",
  "created_at": "2026-03-05T13:22:07Z",
  "item_id": "SKU-12345",
  "platform": "google_merchant_center"
}

Collaborating across teams and vendors

“Supplied countryName is invalid” is a cross-functional problem. Solve it at the seams:

Marketing ops: Define business rules for geographies you target and ship to. Maintain the canonical list of supported countries per channel.
Engineering: Implement normalization libraries, CI tests, and runtime guards. Document accepted formats in the repo.
Data team: Store ISO codes as typed fields; publish a countries_dim dimension with code/name synonyms for analytics joins.
Vendors: Ask app providers to confirm their expectations. If they accept “UK,” confirm whether they resubmit as “GB” downstream.

Benchmarks and research insights that back this up

ISO conformity: ISO 3166-1 alpha-2 is the de facto standard for country codes across commerce, payments, and ad tech (source: ISO 3166 Maintenance Agency).
Feed resilience: Merchant Center and Meta documentation explicitly require ISO alpha-2 for country fields in shipping/tax/targeting (sources: Google Merchant Center Help, Meta for Developers).
Checkout friction: Research shows that unclear validation and error messaging is a leading cause of form abandonment in checkout flows (source: Baymard Institute).
Address formats: The Universal Postal Union’s S42 guidelines illustrate how international addresses vary and why robust parsing/validation is essential (source: Universal Postal Union).
Globalization best practices: The W3C Internationalization Working Group emphasizes normalization and character encoding handling for multilingual inputs (source: W3C Internationalization Working Group).

Together, these sources reinforce the simple remedy: standardize country data to codes, validate early, and log consistently.

FAQ: Quick answers to common questions

Does “countryName” mean I should pass the full name? No. Despite the label, most APIs expect ISO alpha-2 codes like US or GB.
Is “UK” acceptable? Often not. Use GB unless the platform explicitly lists UK as supported.
Do I need alpha-3 codes (e.g., USA)? Rarely. Use alpha-2 unless the docs call out alpha-3.
How do I handle Kosovo? Some systems accept XK; many don’t. Check the target platform’s support matrix.
Why did my CSV upload fail when the UI worked? The UI mapped your choice to ISO behind the scenes; your CSV likely contained names. Convert to codes before upload.
Are names with accents okay? They can be in descriptive fields, but country fields should still be alpha-2 codes. Normalize early.
How do I prevent Excel from “fixing” my codes? Import/export as text and set the column data type to Text. Better yet, use CSV via scripts.
Should I store both name and code? Yes. Store code for systems integration and name for display, both derived from a canonical source.
Can a code be lowercase? Some systems accept it, but standardize to uppercase to be safe.
What about territories like Puerto Rico? Use their ISO codes (PR). Confirm how the target platform treats territories vs. countries.

Troubleshooting flow: from error to fix in minutes

Read the platform docs for the specific field to confirm the expected format (likely ISO alpha-2).
Inspect your payload in logs or browser DevTools. Is it a name, a 3-letter code, or malformed?
Normalize the value using a mapping layer; ensure uppercase two-letter code.
Resend and verify the request or re-upload the feed. Check diagnostics for other issues.
Patch upstream so future values are correctly formatted before they enter your system.
Add tests and monitoring to catch reintroductions.

Real-world scenarios and fixes

Scenario 1: Merchant Center disapproval for shipping country

The feed shows “United States” in shipping:country. Create a feed rule to map “United States” → “US” and “United Kingdom” → “GB.” Reprocess the feed; diagnostics clear within a couple of hours (source: Google Merchant Center Help).

Scenario 2: Meta Catalog import fails

A CSV includes “UK” under a country column. Replace “UK” with “GB” and ensure uppercase. Re-upload; the import succeeds (source: Meta for Developers).

Scenario 3: Stripe payment intent error

Your backend passes address.country: “Germany.” Change to “DE” and set the serializer to force uppercase. Retest; the intent confirms (source: Stripe API Reference).

Scenario 4: CRM integration breaks overnight

A marketing automation step exports lead countries from a free-text field. Add a transformation to map names to ISO codes before pushing to the CRM, and reject records lacking a confident mapping. Queue them for manual review.

Implementation blueprint: make it stick

To prevent “Supplied countryName is invalid” from resurfacing, put this plan into action:

Define a canonical lookup: A simple key-value store of name/synonym → ISO alpha-2, stored in source control and versioned.
Normalize at intake: When data arrives—via forms, webhooks, CSV—normalize and validate before storing.
Contract-first schemas: Share JSON Schema or OpenAPI specs that enforce patterns like ^[A-Z]{2}$ for country fields.
Error budgets: Track and set a target (e.g., <0.1% invalid geo errors per 10k requests) with alerts.
Documentation: Explain edge cases (GB vs. UK, XK), platform-specific rules, and test cases.
Regression tests: Add unit tests for your mapping function and integration tests for top platforms.

Copy-and-paste error messages and how to read them

Sometimes platforms wrap this issue in different words. Here’s how to interpret similar messages:

“Invalid parameter: country”: Generic, but almost always means wrong format or unsupported code.
“Unsupported two-letter country code”: The code is syntactically correct but not in the platform’s allowed list.
“Supplied countryName is invalid”: Field value doesn’t match expected enumeration; convert to ISO alpha-2.
“Invalid address: country is required”: A missing value—ensure non-empty, validated code is present.

Testing plan for marketers and non-developers

You don’t need to be a developer to validate this:

Check uploads: Open your CSV in a plain-text editor to verify country columns are two-letter codes.
Use a staging account: Upload a tiny sample (5–10 rows) to Merchant Center or Meta to test formats before full imports.
Browser DevTools: On a custom form, submit a test and inspect the network request payload for the posted country value.
Ask for logs: Request your dev team share sanitized logs that show error responses and field values.

Error-proof content and SEO implications

While this is a data issue, it intersects with SEO and content operations:

Localized landing pages: Ensure geo-targeted CTAs and shipping notes match the countries you can actually accept and validate.
Schema consistency: If you use structured data that includes address objects, keep country codes and names aligned to avoid mixed signals.
Editorial QA: Content teams should avoid using ambiguous country synonyms that contradict platform constraints in downloadable templates or onboarding docs.

Takeaways for executives and stakeholders

This is not “just a dev bug.” It’s a revenue risk and an operational maturity signal:

Risk mitigation: A single mapping layer can reduce feed disapprovals, ad setup delays, and checkout errors.
Time-to-market: Standardized data accelerates launches in new markets without platform-by-platform fire drills.
Data quality: Consistent geographies power more accurate reporting and forecasting.

Summary: the reliable path to green checks everywhere

To resolve “Supplied countryName is invalid” quickly and permanently:

Assume the destination wants ISO 3166-1 alpha-2 and validate accordingly.
Normalize once, reuse everywhere via a shared mapping layer and SSOT.
Handle edge cases (GB vs. UK, HK/MO/TW, synonyms, diacritics) explicitly.
Instrument logs and dashboards so these errors are caught before a big import or ad launch.
Document the standard, and add tests to keep it that way.

Do that, and your Merchant Center diagnostics clear, Meta imports pass, Stripe charges succeed, and your customers sail through checkout—no cryptic errors, no lost conversions. That’s the Watsspace way: practical fixes that keep your marketing machine moving.

Citations: ISO 3166 Maintenance Agency; Google Merchant Center Help; Meta for Developers; Shopify Admin API; Stripe API Reference; PayPal Developer Docs; Baymard Institute; Universal Postal Union; W3C Internationalization Working Group.

Check out other posts

How to solve “Supplied countryName is invalid” error