Skip to content

Shopify Dude Fix

Shopify Customer Account Address API Uses countryCode: Migrate Without Breaking Existing Addresses

Customer Account API 2026-10 adds countryCode and deprecates territoryCode. Update address reads and writes, avoid conflicting fields, and test country handling.

Quick answer: In Customer Account API 2026-10, use countryCode on CustomerAddress and CustomerAddressInput. The old territoryCode remains supported but is deprecated. If your input includes both, countryCode wins. This is a migration to plan, not an emergency outage.
On this page

Why this happens

Older integrations often model country as territoryCode. Shopify added the clearer, strongly typed CountryCode enum in its September 8, 2026 announcement. Code generated from the old schema may not expose the new field, and code generated from the new schema can surface deprecation warnings. Neither means a stored address has been deleted.

The change is scoped to the Customer Account API. Do not assume every Shopify Admin API or checkout address object has identical field names. Check the schema of the API your extension or app actually calls.

What to change

Pin the API version in your integration. Search GraphQL documents, generated types, mapping functions and address forms for territoryCode. When upgrading to 2026-10, update both reads and writes to countryCode, regenerate typed clients and update validation to accept two-letter ISO 3166-1 alpha-2 codes such as US, CA and GB.

Do not send both fields as a compatibility strategy: conflicting values create a silent precedence problem. Instead, keep a version-aware adapter for older API versions if you still support them. Verify country selection, province/state fields, and saved-address display independently; a correct country enum does not prove the entire address form works.

Practical example

Old Customer Account API selection:
  territoryCode

2026-10 selection:
  countryCode

2026-10 address input concept:
  countryCode: US

Avoid conflicting input:
  countryCode: US
  territoryCode: CA  # countryCode takes precedence

These are field-level examples, not a complete mutation. Use the mutation and variable structure documented for the exact Customer Account API operation. Don’t transform USA or numeric 840 into enum values without a deliberate mapping.

Common misunderstanding: Deprecation does not mean removal. Shopify has not announced a removal version for territoryCode. Existing integrations can continue working, but new code should use countryCode.

How to test this

  1. On a test account, read an existing US and non-US address using the old API version and record the values.
  2. Upgrade the client schema and query to 2026-10; confirm countryCode resolves and generated types compile.
  3. Create and edit an address with a valid two-letter country enum; read it back and verify province/postal code.
  4. Test validation for an invalid country value and ensure the app surfaces a useful error.
  5. Test the version-aware adapter if older deployed clients remain in service.