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, then deployed with shopify app deploy. 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`

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`

Parameter	Type	Description
`name`	`string`	The name of the tool to unregister.

Anchor to [object Object]`ClearFunction`

Removes all tools registered by this app. Takes no parameters.

Anchor to [object Object]`ToolHandler`

A 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.

Examples

js

shopify.tools.register('list_email_campaigns', async (input) => {

const {status, limit = 10} = input;

const campaigns = await fetchCampaigns({status, limit});

return {campaigns};

});

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

Was this page helpful?

Anchor to Use casesUse cases

Anchor to MethodsMethods

Anchor to [object Object]RegisterFunction

Anchor to [object Object]UnregisterFunction

Anchor to [object Object]ClearFunction

Anchor to [object Object]ToolHandler

Anchor to [object Object]`RegisterFunction`

Anchor to [object Object]`UnregisterFunction`

Anchor to [object Object]`ClearFunction`

Anchor to [object Object]`ToolHandler`