Shopify Embedded App Check: What It Needs and How Long It Takes

Last updated October 23, 2026 · By Chad Norris

The embedded app check is an automated gate on the submission page. It turns green only when Shopify has observed your app authenticating with session tokens and running App Bridge inside the admin. Code that is correct but unused, freshly reinstalled or too slow to render stays red or pending. Plan on a couple of hours of real activity after any reinstall, and up to a day or two in bad cases. Disclosure: we build Shopify apps under Orbitloft (disclosure); the “in our submissions” parts come from our own notes.

What Shopify requires

On December 17, 2024, Shopify announced in its changelog that starting January 6, 2025, embedded apps must use session tokens for user authentication to be eligible for submission, and that listing text and screenshots would get AI-assisted checks that flag issues without blocking submission. The requirements page adds two relevant rules:

Shopify’s session token documentation explains why: third-party cookies aren’t reliably available in the admin iframe, and ID tokens expire one minute after issue, so the frontend should fetch a fresh token per request rather than cache one. The official pages do not say what the checks measure or how often they run, so the timing below is from staff replies and our own experience.

How the check actually works

Staff answers in the developer community thread on embedded app checks say the checks are triggered by telemetry from actual app usage in the admin. Having the code present is not enough: the system needs to see App Bridge activity and session token events. The same replies say the checks run every 2 hours, with up to a 2-day lag before telemetry is fully processed. Treat those numbers as a staff statement in a forum, subject to change.

That matches our pipeline note: reinstalling an app on the dev store resets what the crawler has seen, and Submit stays blocked until about two hours of session-token activity has been observed. So reinstall early, not on submission day.

A red check that was not an auth problem

Our most confusing case: a batch of apps showed a red X on “Using session tokens”, which looked like an authentication bug. Auth was fine (token exchange worked and sessions were valid). The cause was a dashboard loader making a slow, uncached call to a language model, plus a body that rendered nothing on the server, so the iframe stayed white for 25 to 60 seconds. After bounding the call with a timeout, caching the result and rendering a spinner during server render, pages painted within seconds, and the red X flipped to green once Shopify observed fast embedded traffic. We changed nothing in the session-token configuration. If your check is red and your config is standard, test load time first. The fixes are in Why Shopify Rejects Apps.

Preparation checklist

Staff advice from that thread, plus what worked for us:

1. Deploy to production. Test the live URL, not a local dev server. After config changes, run shopify app deploy.
2. Install App Bridge from the CDN. Put the script in the head, after the shopify-api-key meta tag. A “missing required configuration fields: shop” error usually comes from the older npm @shopify/app-bridge v3 package or a createApp() call running alongside the CDN script; remove those.
3. Validate tokens on your backend. In incognito on a dev store, open the network tab and confirm backend requests carry an Authorization: Bearer header. If they don’t, the implementation is incomplete.
4. Use the app for real. Click every navigation item and run the core feature, ideally from a fresh development store. Do this on the deployed build.
5. Wait a cycle. Allow at least two hours before debugging. If it stays red for more than a day with everything verified, other developers report asking Partner Support to review it manually; that comes from forum posts, not Shopify documentation.
6. Don’t let the page be slow. A blank iframe is a failure for reviewers too.

Diagnosing a stuck check yourself

Work from the cheapest test to the most expensive, and stop when you find the break:

A normal first load in a token-exchange app logs a message that no valid session was found and then requests an offline access token. In our logs that was the expected path, not an error, so don’t “fix” it. Also confirm your app configuration matches what you deployed: after editing the app configuration file, deploy it again so the live version, not just your local copy, carries the change.

Keep a short note of the date and time of each reinstall and each walkthrough. When the check is still red, that note tells you whether you are inside the two-hour cycle or past it.

Two fresh-install patterns to avoid

If you maintain several apps, stagger the reinstalls so you can click through each app’s screens while its window is open, and write down when each one was last touched.

What not to do

• Don’t re-edit auth code while waiting. Each change risks resetting activity and masking the real fix.
• Don’t rely on a cookie-based session even as a fallback; it breaks the incognito rule (1.1.1).
• Don’t reinstall repeatedly to “refresh” the check. Every reinstall resets observed activity.
• Don’t assume green means ready. The check covers authentication, not billing, data access or listing content.

Where this sits in the submission order

The embedded check is one of the pre-submit gates, along with a complete listing. Do the slow things first: provision, deploy, reinstall on a dev store to mint a fresh token, then work on protected customer data and the listing while the check accumulates observations. That way the two-hour wait costs nothing. For review timing after submission, see what to expect from Shopify app review.

Finally, remember the order of operations on reinstall: Shopify’s requirements (2.3.4) say OAuth must run immediately on reinstall, even for merchants who previously uninstalled. Confirm that your reinstall flow lands in the embedded UI without showing a shop-domain form, because that bounce is a rejection reason on its own.

Quick summary

Authenticate with session tokens, load the App Bridge CDN script first, deploy to production, use the app on a dev store, keep it fast, then wait for the next two-hour cycle. If one of those is missing, no amount of waiting turns the check green.