Executive summary
- What: Customer Account API version 2026-10 adds countryCode to CustomerAddress and CustomerAddressInput, and marks the existing territoryCode field as deprecated.
- Why: It aligns customer addresses with the strongly typed CountryCode enum used across the rest of Shopify's APIs and removes the country versus territory ambiguity.
- Who: Teams building on the Customer Account API. No merchant-facing change and no immediate action for anyone on 2026-07 or earlier.
What changed
From version 2026-10, customer address inputs and objects accept and return countryCode. It uses the CountryCode enum and takes ISO 3166-1 alpha-2 values such as US or CA. The territoryCode field is marked deprecated in the same version but has not been removed, and Shopify has announced no removal version.
Existing queries and mutations using territoryCode continue to work, including on older API versions. If an address input supplies both fields, countryCode wins.
Why it matters
On its own this is a naming correction, and the honest framing is that it changes very little today. It earns attention for two narrower reasons.
The first is type strictness. If your code has been passing alpha-3 or numeric country values such as USA or 840 and getting away with it, the enum will not accept them. That surfaces at the moment you bump the version, not before, and address writes are exactly the kind of call that tends to be exercised by real customers rather than by your test suite.
The second is the precedence rule. Both fields being accepted, with countryCode taking priority, is a quiet trap for code paths that build address inputs by merging objects. A stale territoryCode left in a spread or a shared address builder will simply be ignored once countryCode appears alongside it. The write will succeed and store something other than what the older code intended, which is the failure mode that costs time to diagnose.
Role-specific impact
- Marketers: No impact. Address data continues to behave as it does today, and nothing about the customer experience changes.
- Developers: The real audience. Grep for territoryCode across customer account code, confirm country values are alpha-2, and treat any address builder that merges partial objects as a place where the precedence rule can bite.
- Store admins: Nothing to configure. Worth knowing only so an agency or app vendor mentioning a 2026-10 migration does not sound like a surprise.
Use-case example
Real-world scenario
A Plus merchant runs a headless customer account experience where shoppers manage a saved address book. The address form posts through a shared helper that has passed territoryCode since it was written. The team upgrades the Customer Account API to 2026-10 to pick up unrelated features and adds countryCode at the form layer, leaving the helper untouched. Both fields now travel in the same input. countryCode takes precedence, which is fine while the form supplies it, but one legacy path that calls the helper directly still sends only territoryCode with an alpha-3 value inherited from an older import. Those writes fail validation. Because the path is used by roughly 2 percent of address updates, it clears QA and reaches production before support tickets identify it. A single grep for territoryCode before the version bump would have caught it.
Implementation checklist
- Search your codebase for territoryCode in every Customer Account API query, mutation, and address helper.
- Replace those uses with countryCode, and make sure no input can end up carrying both fields.
- Confirm the values you supply are ISO 3166-1 alpha-2, not alpha-3 or numeric.
- Test address creation, updates, and reads against version 2026-10, including any legacy or admin-only paths that bypass your main form.
- Leave apps on 2026-07 or earlier alone unless you are upgrading them for other reasons.
FAQ
Q: Is this breaking? Do we need to ship something now?
A: No. territoryCode still works, including in 2026-10, and no removal version has been announced. This is preparation work to do alongside your next planned version bump, not an incident.
Q: What happens if both fields are sent in the same address input?
A: countryCode takes precedence. That is convenient during migration but risky in code that merges partial address objects, because a stale territoryCode is silently ignored rather than flagged.
If you want a second pair of eyes on a Customer Account API migration, our engineering team can review it.
Resources
CustomerAddressInput, Customer Account API 2026-10
Need guidance? Talk to Makro.