Shopify just rolled out a subtle yet powerful update to the GraphQL Admin API that will make handling shipping destinations smoother for developers and, indirectly, for merchants. Starting with version 2027‑01, the FulfillmentOrderDestination object now includes a provinceCode field, returning the standard two‑letter code for a destination’s province or state (for example, “ON” for Ontario). This means you no longer need to maintain custom mappings from full province names to their codes—a common pain point for fulfillment apps and custom integrations.
Understanding FulfillmentOrderDestination
When an order is fulfilled, Shopify creates a FulfillmentOrder that contains a nested FulfillmentOrderDestination object. This object already provided useful fields such as address1, city, province, countryCode, and zip. Apps use these details to calculate shipping rates, generate labels, and route orders to the correct warehouse or third‑party logistics provider. Prior to this update, if you needed the abbreviated province code (the format required by many carriers and tax services), you had to either query a separate lookup table or write custom logic to translate the full province name. That extra step added latency, increased maintenance overhead, and introduced potential mapping errors, especially for international destinations where naming conventions vary.
What Changed: The New provinceCode Field
The change is straightforward: FulfillmentOrderDestination.provinceCode now returns a String containing the alphanumeric province or state code. If the destination lacks a province (e.g., a city‑only address) or the province isn’t recognized for the given country, the field returns null. The field respects the same access permissions as the rest of the FulfillmentOrderDestination object—no new scopes are required, so existing apps won’t need to request additional permissions.
Who Is Affected?
Developers – Any private app, custom integration, or public app that reads fulfillment destination data will benefit. The new field reduces the need for external lookups, cuts down on API calls, and simplifies data models.
Merchants – While the change is invisible on the storefront, it indirectly improves order processing speed and accuracy. Merchants using fulfillment services that rely on province codes (e.g., UPS, Canada Post, or tax calculation services) will see fewer mismatches and faster label generation, which can translate into lower shipping errors and better customer experiences.
Existing apps – No breaking change is introduced. The field is additive, so existing queries continue to work unchanged. However, apps that already implement their own province‑to‑code mapping should consider refactoring to use the native provinceCode field for cleaner code and reduced maintenance.
How to Use provinceCode in Your Code
Below is a minimal GraphQL query that fetches the new provinceCode alongside the familiar fields. The query works with the 2027‑01 version or any later version of the Admin API.
graphql
query GetFulfillmentDestination($orderId: ID!) {
order(id: $orderId) {
fulfillmentOrders(first: 10) {
edges {
node {
destination {
address1
city
province
provinceCode # <-- New field
countryCode
zip
}
}
}
}
}
}
When handling the response in a Node.js app, you can now rely on provinceCode directly:
js
function formatShippingLabel(dest) {
const state = dest.provinceCode || dest.province; // Fallback if code is null
return ${dest.address1}\n${dest.city}, ${state} ${dest.zip}\n${dest.countryCode};
}
If you previously used a lookup map, you can safely remove it:
js
// Old approach – now unnecessary
const provinceMap = { Ontario: 'ON', Quebec: 'QC', /* … */ };
const stateCode = provinceMap[dest.province] || dest.province;
Switching to the native field reduces code size, eliminates a potential source of bugs, and speeds up each fulfillment request.
Migration Checklist – What You Should Do
2027-01. Older versions will not expose provinceCode.province for cases where the code may be null (e.g., territories without standard codes).null values.provinceCode values and adjust fallback logic if needed.By following these steps, you’ll ensure a smooth transition and take full advantage of the streamlined data provided by Shopify.
Conclusion & Next Steps
The addition of provinceCode to FulfillmentOrderDestination is a small but meaningful improvement that eliminates a common integration hurdle. Developers can now rely on a single source of truth for state abbreviations, cutting down on code complexity and API chatter. Merchants benefit indirectly through faster, more accurate fulfillment workflows.
Ready to upgrade? Update your GraphQL queries, retire legacy mapping tables, and test the new field in a sandbox store. If you need help refactoring or want to ensure your app complies with the latest Shopify standards, feel free to reach out or drop a comment below. Happy coding, and here’s to smoother shipments!
