Why isn't my app embed showing up in the Shopify Theme Editor?
A theme app extension's embed either isn't showing up under App Embeds at all, or it's there but silently doing nothing. Here's how to tell which problem you actually have.
What's going on
A merchant installs an app that's supposed to add a floating widget, tracking snippet, or on-page overlay to their storefront, but nothing shows up, and worse, there's no obvious toggle in the Theme Editor to turn it on. Or a developer builds a theme app extension, deploys it, installs it on a dev store, and the App Embeds panel simply shows no apps with embeds installed, even though the extension is clearly live in the Partner Dashboard.
These are actually two different problems that get reported as the same symptom. The first is normal Shopify behavior working as designed: every app embed is deactivated by default the moment an app installs, specifically so apps can't silently inject code into a storefront without the merchant's knowledge. The fix is just finding the right toggle. The second is a real configuration or deployment defect: the embed was never registered as an embed in the first place, so there's no toggle to find no matter how carefully you look.
Merchants usually hit the first version after installing an app and expecting it to just work. Developers, and merchants troubleshooting a broken integration, usually hit the second version, and longer debugging threads tend to cluster around it, because the Theme Editor gives no error message and no hint about why the embed isn't listed. It just looks like the app didn't do anything.
Why it happens
Shopify treats app embeds as opt-in by design: activating one after install is a manual merchant action under Theme Settings > App embeds, not automatic, so the most frequent cause of this problem is simply that no one has toggled it on yet. That part is expected behavior, not a bug.
When the embed doesn't even appear in that list, the root cause is almost always in how the theme app extension's block is configured. App embed blocks and regular app blocks share the same theme app extension system, but only an embed block needs to declare where in the page it injects. If that configuration is missing, wrong, or the extension hasn't actually been deployed and installed on the store being tested, Shopify has nothing to list, so the toggle simply never materializes.
Less commonly, the storefront's theme.liquid file is missing structure Shopify relies on to inject embed code, which can make an otherwise correctly configured embed fail to render even after it's been activated.
5 ways to fix it
Check Theme Settings > App embeds first (it's probably just off)
In the Theme Editor, look in the left-hand sidebar for a section called App embeds. Shopify deactivates every app embed by default the moment an app is installed, so if the extension deployed correctly, it is very likely sitting there already, just toggled off. Turn it on, save, and reload the storefront preview before assuming anything is broken. This is free, requires no code changes, and resolves the majority of "my app embed disappeared" reports.
If it's missing from the list entirely, check the embed block's schema configuration
App embeds and regular app blocks are defined differently in a theme app extension's schema. An embed block needs to declare a valid target for where it injects (the head or body of the page, plus a restricted option reserved for compliance-related apps like cookie banners). If that target is missing or misconfigured, Shopify won't recognize the block as an embed at all, and it will never show up under App Embeds no matter how many times you reinstall the app. Reviewing the block's schema against Shopify's theme app extension documentation is the fastest way to catch this.
Confirm the extension actually deployed and is installed on that store
Check the Partner Dashboard or run your deploy command to confirm the theme app extension is live, and confirm the app is installed on the specific store and theme you're testing, not a different dev store or an older app version. Also double-check you're editing the theme you think you are; embeds are enabled per theme, so testing on a draft theme that never had the app activated will look identical to a broken embed.
Rule out a broken or non-standard theme.liquid structure
App embeds are injected near the closing head or body tags of the storefront's layout file. On older or heavily customized themes with a non-standard theme.liquid, missing the structure Shopify expects, the injection point may not exist, so the embed can install fine but never render or even appear as toggleable. Comparing your theme.liquid against a current default Shopify theme is a reasonable way to spot obvious structural gaps.
If you're deep-linking merchants to activate the embed automatically, verify the link format
A common install-flow bug is a malformed activation link. Shopify supports a theme editor URL parameter that pre-activates a specific app embed by combining the extension's identifier with the block's handle. Getting either value wrong, for example using the app's client ID instead of the extension's own identifier, will open the Theme Editor but silently fail to activate or highlight the embed, which looks identical to the embed not existing at all.
Bottom line
Most of the time this is a two-minute fix, not a bug: open Theme Settings > App embeds and flip the toggle. It only becomes a real debugging problem when the embed doesn't show up in that list at all, which is almost always a schema or deployment issue on the developer's side rather than anything wrong with the store. If you're regularly juggling several app embeds and losing track of what's active, deactivated, or conflicting across themes, a store-health or app-audit tool that surfaces embed status alongside other storefront checks can save the recurring hunt, but it's a convenience layer on top of the fix above, not a replacement for it.
Browse the rest of the problem library, run a free storefront scan to catch issues like this automatically, or email us and we'll work out a custom solution for it.