Tools API
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.
The Tools API enables apps to register handler functions for the platform to invoke on behalf of the app.
Tools must be pre-declared statically in a json schema file linked in a Sidekick app extension's shopify.extension.toml. The platform discovers available tools from these schemas. At runtime, shopify.tools.register(name, handler) binds a live handler that executes inside the sandbox. Registered tools persist for the lifetime of the extension or until explicitly removed.
Anchor to Use casesUse cases
- In-app modifications: Enable merchants to ask Sidekick to make changes in your app, such as rescheduling a shipment, pausing a subscription, or updating a design with natural language.
- AI-powered workflows: Expose executable tools that Sidekick can invoke on behalf of merchants.
Anchor to MethodsMethods
| Method | Type | Description |
|---|---|---|
register | RegisterFunction | Registers a tool for this app. If a tool with the same name is already registered, the existing handler is replaced. |
unregister | UnregisterFunction | Unregisters a tool this app has previously registered. If no tool with the given name exists, this is a no-op. |
clear | ClearFunction | Removes all tools registered by this app. |
Anchor to [object Object]RegisterFunction
RegisterFunction| Parameter | Type | Description |
|---|---|---|
name | string | A unique name for the tool within this app. |
handler | ToolHandler | The function invoked when the platform calls this tool. |
Returns: () => void — A cleanup function that unregisters the tool. Equivalent to calling unregister with the same name.
Anchor to [object Object]UnregisterFunction
UnregisterFunction| Parameter | Type | Description |
|---|---|---|
name | string | The name of the tool to unregister. |
Anchor to [object Object]ClearFunction
ClearFunctionRemoves all tools registered by this app. Takes no parameters.
Anchor to [object Object]ToolHandler
ToolHandlerA handler function invoked by the platform when a registered tool is called. The handler receives an input object whose shape is defined by the tool's schema, and must return a result object (or a Promise that resolves to one).
| Parameter | Type | Description |
|---|---|---|
input | Record<string, any> | The input parameters provided by the caller. |
Returns: Record<string, any> | Promise<Record<string, any>> — The result of the tool invocation.
js
Examples
Description
Register a tool handler. This example registers a tool named `list_email_campaigns` that fetches campaign data from the app's backend. The platform can invoke this tool with input parameters defined by the tool's schema.
js
shopify.tools.register('list_email_campaigns', async (input) => { const {status, limit = 10} = input; const campaigns = await fetchCampaigns({status, limit}); return {campaigns}; });Description
Unregister a specific tool. This example removes a previously registered tool by name. If no tool with the given name exists, this is a no-op.
js
shopify.tools.unregister('list_email_campaigns');Description
Remove all registered tools. This example unregisters every tool the app has registered in one call.
js
shopify.tools.clear();Description
Use the cleanup function with React. The `register` method returns a synchronous cleanup function, making it compatible with React's `useEffect` cleanup pattern. This is useful when the tool handler closes over route-specific state that changes on navigation.
jsx
function CampaignEditor({campaignId}) { useEffect(() => { const cleanup = shopify.tools.register('update_campaign', async (input) => { const response = await fetch(`/api/campaigns/${campaignId}`, { method: 'PATCH', body: JSON.stringify({subject: input.subject, body: input.body}), }); return response.json(); }); return () => cleanup(); }, [campaignId]); }