Playbook · Token exchange metafield missing
Shopify token exchange metafield missing? Prove session→access token and owner.
Written for a Shopify DTC owner whose app uses token exchange (session token → offline or online access token) and a metafield is missing, null, or blank on the post-exchange Admin API call. Start with exchange HTTP status, returned token type, scopes, shop, resource owner, namespace.key, and one authenticated read. This is distinct from embedded app auth metafield blank and offline id token metafield missing: those pages cover in-iframe session rendering or id-token claims; this page isolates the exchange step that mints the access token your backend uses for metafield queries.
Nico at Latch AI Ops · Sep 17, 2026 · ~10 minute read
01
A token-exchange miss is not the same as an embedded session blank.
Use this page when the session token looks valid but the access token produced by exchange fails the metafield query—or when exchange itself fails and the job never reads the field. If the embedded UI is blank before any backend exchange, start with embedded app auth metafield blank.
Capture shop, session-token verify result, exchange endpoint status, offline vs online flag, scopes returned, owner id, namespace.key, Admin value, and post-exchange GraphQL errors. Do not add a duplicate metafield before proving the exchanged token’s shop and scopes.
02
Prove session token → access token exchange request and response.
Log the exchange request (without pasting secrets): client id, grant type / subject token type, shop, and HTTP status. A 400/401 from exchange is not fixed by editing metafield definitions. Confirm the subject session token’s shop matches the store you think you are querying.
Keep this distinct from classic OAuth install flows covered in OAuth scopes metafield blank. Token exchange assumes an already-installed app and a live session token.
03
Name offline vs online token and the scopes returned.
Offline tokens persist for background jobs; online tokens are user-session scoped and expire. A metafield read that works in the embedded UI (online) but fails in a webhook/worker (offline) often means you never stored an offline token, or exchange requested the wrong token type. Record scopes on the returned token and compare to the metafield owner’s required access.
If scopes omit the owner type or protected customer data approval is missing, Admin may still show the value to staff while your token gets empty data or an access error that your code maps to “missing.”
04
Prove owner, definition, and one post-exchange metafield read.
With the exchanged access token, query the exact owner gid and namespace.key. Compare to Admin on that owner. Separate absent key, null, empty string, ACCESS_DENIED, and wrong API version. A saved value on a different resource or an app-owned definition the token cannot read will look like “metafield missing after exchange.”
Keep the diagnosis distinct from session token metafield missing and from billing/API blanks. Those are different auth surfaces than the exchange mint step.
05
Retest one exchange and one metafield query; keep proof.
On one known shop, run one controlled session→access exchange, then one metafield query. Record exchange status, token type, scopes, owner id, namespace.key, Admin test value, GraphQL field state or error code, and timestamp. Retry only after the first trace is captured.
Classify the miss as exchange failure, wrong token type, missing scopes, wrong owner, definition/value, or response mapping. Do not force a full reinstall until one post-exchange query returns the Admin-visible test value.
06
When to stay DIY vs pay $997.
Stay DIY when one exchange, scope, or owner check explains the miss. Keep the proof packet so later token-exchange changes stay grounded.
Pay for the $997 one-time install when several Shopify surfaces, apps, and ops alerts need to be wired and documented on one live store. Nico at Latch AI Ops can connect the agreed workflow in a 72-hour window after collaborator access. No earnings claim, conversion guarantee, or theme rebuild is included; owner passwords are not requested.