---
title: Tools API
description: >-
  The Tools API enables apps to register handler functions for the platform to
  invoke on behalf of the app.
source_url:
  html: >-
    https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/tools-api
  md: >-
    https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/tools-api.md
---

# 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](https://shopify.dev/docs/apps/build/sidekick)'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.

### Use 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.

### Methods

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

#### `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`.

#### `UnregisterFunction`

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

#### `ClearFunction`

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

#### `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

### 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

  ```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

  ```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

  ```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

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

***