Shopify just released a key update to the Customer Account API: starting with version 2026-10, address inputs and objects now include a countryCode field. The long‑standing territoryCode field is officially deprecated, though still functional for now. This change aligns address data with the rest of Shopify’s APIs, which already use the strongly typed CountryCode enum. If you build apps that create, read, or update customer addresses, this post walks you through the update, explains who it impacts, and provides concrete steps—and code—to migrate smoothly.
What Changed
Who Is Affected
Why This Matters
Shopify’s ecosystem has been converging on a single country‑code terminology. The new CountryCode enum is used across many APIs—orders, shipping, tax, and now customer addresses. This reduces confusion between “country” and “territory,” eliminates the need for developers to guess whether a three‑letter code (USA) or numeric code (840) is acceptable, and enforces a consistent data contract across the platform.
How to Migrate: Actionable Steps
Code Example: Creating an Address with countryCode
Below is a GraphQL mutation that creates a customer address using the new countryCode field. The snippet assumes you’re using the 2026-10 API version.
graphql
mutation CreateCustomerAddress($customerId: ID!, $address: CustomerAddressInput!) {
customerAddressCreate(customerId: $customerId, address: $address) {
customerAddress {
id
firstName
lastName
address1
city
province
countryCode
}
userErrors {
field
message
}
}
}
Variables:
{
"customerId": "gid://shopify/Customer/1234567890",
"address": {
"firstName": "Jane",
"lastName": "Doe",
"address1": "123 Maple St",
"city": "Seattle",
"province": "WA",
"countryCode": "US",
"zip": "98101"
}
}
Reading the Updated Field
When you query a customer’s addresses, include countryCode in the selection set to verify the value is stored correctly:
graphql
query GetCustomerAddresses($customerId: ID!) {
customer(id: $customerId) {
addresses(first: 10) {
edges {
node {
id
address1
city
province
countryCode
# territoryCode is still available but deprecated
}
}
}
}
}
Testing & Validation Checklist
✅ Verify that all mutations use countryCode and supply a two‑letter ISO code.
✅ Ensure your GraphQL client is set to version 2026-10 or newer.
✅ Run end‑to‑end tests that create, update, and fetch an address; assert that countryCode matches the input.
✅ Check server logs for any deprecation warnings related to territoryCode.
✅ Once clean, remove territoryCode from the payloads and from any GraphQL fragments.
Conclusion & Next Steps
The addition of countryCode to Shopify’s Customer Address APIs is a small but important step toward a more consistent, type‑safe platform. While existing apps won’t break today, embracing the new field now ensures your integrations stay future‑proof and reduces the risk of ambiguous address data. Update your API version, swap out territoryCode for countryCode, and run the quick test suite outlined above.
Got questions or need help with the migration? Drop a comment below or reach out to our Shopify developer community—staying ahead of API changes keeps your store running smoothly and your customers happy.
