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

# Tools API

**Info:**

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

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

***