Disclaimer - I didn’t write this, sidekick generated it based on the context it has wrto theme extensibility. (with emdashes removed). Context and direction is mine, notes are from sidekick on what can be done with examples.
Apps that ship theme extensions - app embeds, sections, and blocks - require merchants to manually enable and place them in the theme editor. Today, Sidekick can guide merchants through this process, but has no mechanism to verify completion or signal back to the app that setup is actually done.
The result: apps are left guessing whether their extension is live. Merchants assume it’s working. Support tickets follow.
Real-World Failure Scenarios by Theme Extension Type
App Embeds
- Merchant enables the embed on a development or duplicated theme, not the published live theme
- Merchant enables the embed but forgets to click “Save” in the theme editor
- Embed is disabled silently after a theme update or when the merchant switches to a new theme
- Merchant publishes a different theme version that doesn’t have the embed enabled
Theme Sections
- Section is added to the wrong template (e.g., added to
indexinstead ofproduct) - Section is present in the template JSON but set to
hidden: true - Section is removed when the merchant reorganizes their template or switches themes
- Merchant adds the section to a template that isn’t assigned to any products or pages
Theme Blocks
- Block is placed inside the wrong parent section
- Block is in the correct section but in the wrong position, breaking the intended UX
- Block is removed when the merchant edits the section layout
- Block is present but its required settings (e.g., linked metafield, product picker) are left unconfigured
Root Cause
There is no Admin API surface that exposes:
- Which app embeds are enabled on which theme, and whether that theme is the live published theme
- Which sections and blocks from a given app are present in which templates
- Whether those sections/blocks are visible, correctly positioned, and fully configured
Without this, neither the app nor Sidekick can verify setup - they can only guide and hope.
What We’re Asking For
1. App Embed Status API
Expose per-theme app embed enablement via Admin GraphQL so apps and Sidekick can query it programmatically without scraping theme editor UI or parsing settings_data.json manually:
query {
theme(id: "gid://shopify/OnlineStoreTheme/123") {
appEmbeds {
appId
handle
enabled
themeRole # "main" | "unpublished" | "development"
}
}
}
2. Section & Block Placement API
Extend the existing Assets API or introduce a dedicated endpoint that returns which sections and blocks from a given app are present in each template, including visibility and configuration state:
query {
theme(id: "gid://shopify/OnlineStoreTheme/123") {
templates {
name
sections {
type
appId
blockHandle
visible
settings {
key
value
}
}
}
}
}
3. Sidekick Hints Write API
Allow apps to POST a structured task definition that Sidekick evaluates against live store state:
{
"task_id": "enable-embed-live-theme",
"title": "Enable app embed on live theme",
"surface": "theme",
"completion_criteria": {
"type": "app_embed_enabled",
"theme_role": "main",
"app_id": "your-app-id",
"embed_handle": "your-embed-handle"
},
"callback_url": "https://your-app.com/webhooks/sidekick-completion"
}
For section/block placement:
{
"task_id": "place-product-block",
"title": "Add review block to product template",
"surface": "theme",
"completion_criteria": {
"type": "block_placed",
"theme_role": "main",
"template": "product",
"block_handle": "your-block-handle",
"app_id": "your-app-id",
"require_visible": true,
"require_configured": ["metafield_namespace", "product_picker"]
},
"callback_url": "https://your-app.com/webhooks/sidekick-completion"
}
4. sidekick/task_completed Webhook Topic
Fire when Sidekick verifies all criteria are met against live store state:
{
"topic": "sidekick/task_completed",
"task_id": "enable-embed-live-theme",
"app_id": "your-app-id",
"verified_at": "2026-07-30T04:00:00Z",
"payload": {
"theme_id": "gid://shopify/OnlineStoreTheme/123",
"theme_role": "main",
"embed_handle": "your-embed-handle",
"enabled": true
}
}
5. App Bridge sidekick:task_completed Client Event
For apps that prefer a real-time client-side signal over a server webhook, emit this event so the embedded app UI can update its onboarding state without a round-trip:
shopify.addEventListener('sidekick:task_completed', (event) => {
const { taskId, verifiedAt, payload } = event.detail;
// Mark onboarding step complete in your UI
});
6. Persistent Task State in Sidekick
Incomplete tasks registered by an app should survive session close and be re-surfaced the next time the merchant opens Sidekick - with full context intact:
- “Last time you were setting up [App Name]. Your app embed still isn’t enabled on your live theme. Want to finish that now?”
Tasks should be dismissible by the merchant but re-surfaceable by the app if the criteria remain unmet.
7. Verification Loop Behavior
After guiding the merchant through enabling an embed or placing a block, Sidekick should:
- Query the theme state via the APIs above
- Confirm success explicitly: “Your app embed is now enabled on your live theme ✓”
- Fire the completion webhook/event
- If verification fails: surface the specific reason and offer to retry - not just repeat the same instructions
Expected Impact
- Eliminates the #1 source of “why isn’t my app working?” support tickets for theme-dependent apps
- Gives app developers a reliable signal to gate further onboarding steps on confirmed theme setup
- Allows Sidekick to move from guide to verified completion engine for theme workflows
- Merchants on new themes or after theme updates get proactive re-verification, not silent breakage