Playbook · OAuth scopes metafield blank
Shopify OAuth scopes metafield blank? Prove grant, reauth, and one Admin read.
Written for a Shopify DTC owner whose OAuth-scopes metafield is filled in Admin but returns null or missing because the app session lacks the scopes that read or write it. Start with definition ownership, required vs granted scopes, one reauthorization when the grant is stale, and one authenticated Admin read after a valid grant. This is not a custom-app scopes checklist alone, and it is not a session-token timing miss.
Nico at Latch AI Ops · Sep 17, 2026 · ~10 minute read
Buy the 72-hour install — $997Billing API fieldCustom scopesMerchant FAQ
01
A blank OAuth-scopes metafield is not automatically a missing custom-app toml.
Use this page when the metafield exists in Admin but the app cannot read or write it because the OAuth grant on that shop is missing a required scope (or still uses a pre-reauth token). If the miss is only declaring scopes on a custom app without an install grant check, use custom app scopes missing. If the miss is only session-token fetch timing after Bridge ready, use session token metafield missing.
Do not rotate client secrets yet. Capture the shop, app handle, required scopes from toml/Partner Dashboard, scopes returned on the access token or AccessScope query, namespace.key, and the exact Admin API error (403, ACCESS_DENIED, or empty metafield).
02
Prove the owner resource, definition, and exact saved value.
Open Settings → Custom data and confirm the definition is owned by the resource the OAuth session targets (often Shop or an app-owned definition). Record the exact namespace and key, for example app.oauth_note, the type, and whether the app owns the definition.
Save a short unmistakable test value on that resource, refresh, and confirm it survives in Admin. A theme Liquid read with no Admin API grant is not proof the OAuth session can return the field.
03
Compare required scopes, granted scopes, and reauthorization together.
List the scopes your app declares for the metafield path (for example read_products, write_products, or app-owned metafield access). Query the current grant on the shop (AccessScope / token introspection) and compare line by line. A toml update that was never followed by merchant reauth leaves the old grant in place.
If any required scope is missing, run one reauthorization redirect with the full required set, accept on the shop, then discard the old token. Do not assume a silent scope upgrade. Log scope names only — never log access tokens.
04
Trace one authenticated Admin read after a valid grant.
With the new grant, prove metafield(namespace: "…", key: "…") { value type } in Admin GraphiQL using the same API version as production. Then run the app’s authenticated read with the post-reauth token. If GraphiQL succeeds and the app still returns blank, fix token selection or API version rather than rewriting every product.
Keep the diagnosis distinct from Billing API metafield missing and Admin GraphQL metafield missing. Billing charges and generic GraphQL selection bugs can look similar while reading different failure surfaces.
05
Retest one shop install and keep a small proof packet.
Use one development or live shop. Record shop domain, app handle, required scopes, granted scopes before/after reauth, namespace.key, type, saved test value, GraphiQL result, and whether the app read shows the test value after the new grant. Repeat only if GraphiQL succeeds and the app still fails.
If the field is still blank, classify it as definition/value, missing required scope, stale pre-reauth token, wrong API version, or wrong resource id. Do not call a full reinstall until the metafield is Admin-readable under the granted scopes on one live session.
06
When to stay DIY vs pay $997.
Stay DIY when one definition, scope grant, or reauth step explains the blank. Keep the proof packet so future scope changes stay grounded in real grants.
Pay for the $997 one-time install when several Shopify surfaces, apps, catalogs, 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.