Playbook · Online access token metafield missing
Shopify online access token metafield missing? Prove user-session token, scopes, and owner.
Written for a Shopify DTC owner whose online access token (staff user session in an embedded or standalone admin app) queries a metafield that is missing, null, or blank. Start with whether an online token was issued for this user and shop, whether it expired, which scopes it carries, which owner and namespace.key the request reads, and one authenticated online Admin API call. This is distinct from offline access token metafield blank and session token metafield missing: those pages cover persisted offline tokens or JWT session claims; this page isolates the short-lived online access token used during an active staff session.
Nico at Latch AI Ops · Sep 17, 2026 · ~10 minute read
Buy the 72-hour install — $997Offline access tokenMerchant FAQ
01
An online-token miss is not the same as an offline or session blank.
Use this page when the metafield fails during an active staff session that should present an online access token to Admin API—while a background offline job may still succeed, or while the session JWT verifies but the exchanged/online access token does not. If only workers fail, start with offline access token metafield blank. If the iframe never authenticates, see embedded app auth metafield blank.
Capture shop, staff user id, online token issue/expiry, scopes, owner id, namespace.key, Admin value, GraphQL errors, and timestamp. Do not add a duplicate metafield before proving the request uses a live online token for the same shop.
02
Prove the online access token for this user and shop.
Confirm the app obtained an online access token for the current staff user (OAuth online grant or token exchange requesting online). Log issue time and expiry without pasting the secret. An expired online token often surfaces as empty metafield data after a long idle tab—not as a definition problem.
Keep this distinct from session token metafield missing (JWT session claims for the embed) and token exchange (the mint request). Here the question is: does this request carry a valid, non-expired online access token?
03
Check scopes, expiry, and staff vs app permissions.
Compare scopes on the online token to the metafield owner type. Staff can see Admin UI values while the app’s online token lacks read access—or the reverse if staff permissions hide a field the app can still query. Record expiry and refresh/re-auth behavior after idle.
If scopes were reduced after install, an online re-auth may be required even when an old offline token still works. Tie that to OAuth scopes metafield blank only when consent itself is the proven gap.
04
Prove owner, namespace.key, and one online Admin read.
With the online access token, query the exact owner gid and namespace.key. Compare to Admin for that staff user on that owner. Separate absent key, null, empty string, wrong resource, ACCESS_DENIED, and UI-only visibility. A metafield visible in Admin settings but not on the resource the online call queries will look like “missing online.”
Keep diagnosis separate from billing/API blanks and from offline worker paths unless those share the same owner bug.
05
Retest one online session; keep proof.
On one known shop and staff user, open a fresh session, obtain one online access token, then run one metafield query. Record issue/expiry, 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 expired online token, wrong user/shop, missing scopes, wrong owner, definition/value, or response mapping. Do not force a full reinstall until one online query returns the Admin-visible test value.
06
When to stay DIY vs pay $997.
Stay DIY when one session, expiry, scope, or owner check explains the miss. Keep the proof packet so later online-auth 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.