Tools API
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]); }