We’re using the Admin GraphQL API’s localized fields support for orders, as described in “Add locally required data to orders using localized fields”.
In the API, localized fields are available on:
These are critical for markets where additional, locally required data must travel with the order (for example tax IDs, customs information, or other regulatory details).
Problem
However, even though this data is present on the order object and is queryable via the Admin GraphQL API, it is not exposed in several downstream payload surfaces that our integration depends on, including:
-
Webhook payloads – for example:
-
orders/create -
orders/updated -
[add specific topics that you’ve confirmed do not include this data]
-
-
Other integration payloads – for example:
- [Describe your specific integration and which payloads are missing
localizedFields/localized_fields]
- [Describe your specific integration and which payloads are missing
As a result:
-
We have to perform an extra Admin API request (e.g.
order(id: ...) { localizedFields { ... } }) every time we receive a webhook, just to retrieve data that logically belongs with the order event itself. -
This adds latency and complexity to our integration.
-
It increases the chance of race conditions or failures (webhook succeeds but follow‑up Admin API call fails).
-
In some cases, our downstream systems work in a “fire-and-forget” mode, where we’d like to avoid extra network calls and simply rely on the payload they’re given.
Requested feature
Expose localizedFields (or equivalent localized_fields structure) on more payload surfaces, especially:
-
Order-related webhook payloads, such as:
-
orders/create -
orders/updated -
orders/paid -
orders/fulfilled -
[any other order-related topics you rely on]
-
-
Downstream integration payloads, where orders are already serialized with core fields like line items, shipping address, billing address, etc.
The goal is that any consumer that currently sees core order attributes in an event payload can also see these localized fields without needing a separate Admin API fetch.
Why this matters
-
These fields are explicitly designed for locally required, often compliance-critical data (tax credentials, customs info, government IDs, etc.).
-
For many merchants and integrators, this data is required by:
-
Tax authorities
-
Customs and logistics providers
-
E-invoicing systems
-
-
If the
localizedFieldsdata isn’t present at event-time, downstream systems can:-
Fail to generate valid documents (invoices, export docs)
-
Fail compliance checks
-
Require extra, brittle logic to “re-hydrate” orders from the Admin API
-
Workarounds (current state)
Today, we work around this limitation by, for each received order-related webhook:
-
Extracting the
order_idfrom the webhook payload. -
Performing an Admin GraphQL API call like:
Operation
Open in GraphiQLCopy
query OrderWithLocalizedFields($id: ID!) {
order(id: $id) {
id
localizedFields(first: 10) {
edges {
node {
countryCode
title
value
}
}
}
}
}
- Merging this data back into the event before forwarding it to our downstream systems.
This is functional but sub‑optimal in terms of latency, reliability, and architectural simplicity.
Summary
Please consider exposing localizedFields / localized_fields on:
-
All relevant order-related webhook payloads
-
Other downstream integration payloads where orders are serialized
so that integrators can consume locally required fields directly from event payloads without extra fetches.
If helpful, we’re happy to provide:
-
Example shop and order IDs
-
Sample webhook payloads
-
Our exact integration flow and impacted regions/markets