Integrating Shopify Sidekick in your app
TL;DR
Sidekick app extensions are now available to every Shopify app developer. Here is how the Spring '26 Edition fits together, what we shipped in Waitlist Flow, and the mental model you need before writing your first tool.
Shopify's Spring Editions '26 developer release landed with a clear theme: agentic commerce is no longer a special-access lane. UCP, Catalog API, Sidekick app extensions, and a rebuilt platform layer are all aimed at the same problem—commerce is moving into conversations, and apps that only exist as separate admin destinations will feel increasingly out of step.
We recently shipped Sidekick integration in Waitlist Flow. This post is a high-level walkthrough for other app developers: what Sidekick extensions are, how they fit the Spring '26 picture, and what we learned without turning this into a full implementation manual.
Spring '26: the context that matters for app builders
If you have not read Shopify's Spring '26 developer edition post, the headline is not a single feature—it is a platform shift.
Agentic commerce is self-serve. UCP (Universal Commerce Protocol) and Catalog API are open to the wider developer ecosystem. Agents can discover products, build carts, and move toward checkout without a bespoke partnership approval process.
Sidekick is where merchants already work. Shopify reports Sidekick weekly active shops up 4× year over year in Q1. The platform's bet is straightforward: merchants will ask questions and take actions in conversation, not by tab-hopping across fifteen apps.
The infrastructure underneath got serious attention. Next Gen Events (field-level webhook filtering, customizable payloads), App Events (your app's telemetry in the Dev Dashboard), App Pricing (usage metering on Shopify invoices), Flexible Fulfillment (mixed ship/pickup in one order), and a consolidated Developer Dashboard are all signals that Shopify is rebuilding the boring parts so you can focus on product.
The AI Toolkit went GA. If you build in Cursor, Claude Code, or VS Code, the toolkit bundles skills and CLI access so your editor can reference Shopify docs and run commands without constant context switching—worth pairing with Sidekick work, not replacing it.
Sidekick app extensions sit in the middle of this story: they are how your app's data and workflows show up inside the conversation merchants are already having.
What Sidekick app extensions actually do
At a high level, Sidekick extensions let your app answer two kinds of merchant questions:
- "What does my app know?" — search, summarise, count, list.
- "Can my app do something about it?" — open the right screen, stage a change, confirm an action.
Shopify splits these into two extension patterns:
| Pattern | Target | What it does |
|---------|--------|--------------|
| Data | admin.app.tools.data | Headless tools that return app data to Sidekick |
| Action | admin.app.intent.link | Navigate to a URL in your embedded app, with in-page tools |
There is also admin.app.intent.render for inline UI surfaces—useful when you want a focused Sidekick-native panel instead of routing to an existing page.
Official docs: Sidekick app extensions.
The mental model: three layers
Before you scaffold anything, it helps to think in three layers:
1. Declaration (what Sidekick is allowed to call)
You declare tools in tools.json, describe when to use them in instructions.md, and wire everything in shopify.extension.toml. For action extensions you also declare intents—the verbs Sidekick can invoke (create, edit, etc.) and the schema for parameters.
You also add an extensions_summary to shopify.app.toml. This is easy to miss and required: it is how Sidekick routes merchant questions to your app across multiple extensions.
2. Runtime registration (what actually runs)
Declared tools are not enough. At runtime your app must bind handlers with shopify.tools.register().
- Data extensions register handlers in a small headless module (
src/index.js). - Action extensions register page-level handlers from the React route Sidekick navigates to—after the merchant lands on your screen.
Navigation is owned by the action extension. Do not declare a tool that only duplicates "open this page."
3. Backend (where the truth lives)
Sidekick tools should call your existing app APIs, not reach into the database from the extension sandbox. In Waitlist Flow we added authenticated /api/sidekick/* routes that use authenticate.admin() and return JSON with CORS headers via cors().
Keep the same tenancy rules you already enforce: every query scoped to session.shop.
What we shipped in Waitlist Flow
Waitlist Flow helps merchants run queues for sold-out products, classes, and drops—capturing demand and notifying the next customer when a spot opens.
Sidekick was a natural fit. Merchants already ask operational questions in plain language:
- "How many people are on my waitlists?"
- "Who is waiting on the yoga class?"
- "Open my sneaker drop waitlist."
- "Notify the next customer—a spot just opened."
We shipped three extensions:
| Extension | Role |
|-----------|------|
| sidekick-waitlist-data | Search waitlists and entries, return queue stats |
| sidekick-waitlist-actions | Open a waitlist detail page + notify next customer |
| sidekick-waitlist-create | Navigate to create a new waitlist |
Data tools return resource links
Search results are not arbitrary JSON blobs. Sidekick expects resource links—structured objects with a uri, name, and mimeType that connect search results to action intents.
We used application/campaign as the intent type (there is no native "waitlist" type in Shopify's supported list yet). URIs look like gid://application/campaign/{waitlistId}. Consistency between data results and action intents is what lets Sidekick go from "here are three waitlists" to "open this one" without the merchant re-explaining context.
Actions reuse existing admin pages
The edit intent opens /app/waitlists/{id}—a route we already had. We added a small hook on that page to register notify_next_customer and refresh_waitlist_summary when Sidekick is active.
The create intent opens /app/waitlists/new with a lightweight eligibility check tool so Sidekick can warn merchants on plan limits before they fill out the form.
No parallel Sidekick-only UI was required. That kept scope tight and avoided maintaining two versions of the same workflow.
Practical lessons (the stuff docs understate)
Write specific descriptions. Sidekick chooses extensions based on the description in each shopify.extension.toml and each tool in tools.json. Vague copy ("search extension for your app") means merchants must name your app explicitly. Be domain-specific: who is waiting, queue stats, claim links, cancellations.
Instructions are guidance, not prompts. instructions.md should explain when tools apply and how they relate. Shopify's policy is clear: do not try to override Sidekick's behaviour or sneak in upsells.
Deploy with a recent CLI. admin.app.intent.link extensions must upload tools.json, instructions.md, and intent schema files as deploy assets. Older Shopify CLI versions fail validation with "Assets are required for links using the admin.app.intent.link target." Upgrade to CLI 3.94+ before you debug your TOML for an hour.
Test in admin Sidekick, not CLI preview. Run shopify app dev, open your dev store admin, and talk to Sidekick there. The CLI preview shortcut is not a reliable stand-in.
Respect intent pathname binding. An intent modal is bound to one URL pattern. If your page redirects elsewhere on load, Sidekick closes the modal. Keep merchants on the bound route while work is in progress.
Related compliance work: expiring offline tokens
Sidekick was the visible Spring '26 feature. Under the hood we also completed Shopify's expiring offline access token migration ahead of the Jan 1, 2027 deadline for public apps.
That work is separate from Sidekick but shares the same theme: the platform is moving toward shorter-lived, refreshable credentials and more production-grade infrastructure. If you have not enabled expiringOfflineAccessTokens in shopify-app-remix and added refreshToken columns to your Prisma Session model, put it on the roadmap now—not December 2026.
Where this fits in the bigger Spring '26 picture
Sidekick extensions are the in-admin side of agentic commerce. Spring '26's UCP and Catalog API are the buyer-facing side—agents discovering and transacting with products across surfaces.
As an app developer you may touch one, two, or all three depending on your product:
- Retention and ops apps → Sidekick extensions are the highest-leverage starting point.
- Discovery and merchandising apps → Catalog API and richer product metadata matter more.
- Checkout and agent builders → UCP is the protocol layer to study.
The AI Toolkit GA announcement is the meta-layer: Shopify expects you to build these integrations inside AI-assisted workflows, not by alt-tabbing between docs and a terminal.
A reasonable first milestone
You do not need five intents and twenty tools on day one. Shopify caps you at 5 intents and 20 tools shared across extensions anyway.
A solid v1 for most apps:
- One data tool that searches your core resource.
- One edit action that opens an existing admin page.
- One page tool on that page for the single action merchants ask for most often.
Ship, watch Dev Dashboard Sidekick logs, read what merchants actually ask, then expand.
Further reading
- Sidekick app extensions — Shopify docs
- Build app actions
- Build app data tools
- Spring '26 Edition for developers
- Sidekick app extensions available today — changelog
- Waitlist Flow on the Shopify App Store
If you are shipping Sidekick integration in your own app and want to compare notes, get in touch—we are actively building on this stack across our app portfolio.