---
title: Use extensions to surface app actions
description: Use extensions to surface app actions
source_url:
  html: 'https://shopify.dev/docs/apps/build/sidekick/build-app-actions'
  md: 'https://shopify.dev/docs/apps/build/sidekick/build-app-actions.md'
---

# Use extensions to surface app actions

By declaring and defining your app's actions in an app extension, Sidekick can take the merchant to the right page in your app to perform a rich action.

***

## Example: Edit email content

In this example, a merchant can ask Sidekick to edit the content of an email campaign. Sidekick takes the merchant to the [Shopify Messaging](https://apps.shopify.com/shopify-email) app, navigated to the correct email campaign.

![Sidekick with email app](https://shopify.dev/assets/assets/admin/sidekick/sidekick-messaging-BmyWcPHr.png)

***

## Expose actions to Sidekick

Use app extensions to expose actions in your app. By providing your app's actions in an app extension, Sidekick can take the merchant to the right page in your app to perform a rich action.

Multiple app extension types are supported. Choose the right app extension type for your app.

| Extension type | App Home support | Standalone app support |
| - | - | - |
| Admin link | ✅ | ❌ |
| UI extension | ✅ | ✅ |

***

## Requirements

* [Create an app](https://shopify.dev/docs/apps/build/scaffold-app).
* For App Home, use the latest version of [App Bridge](https://shopify.dev/docs/api/app-home).
* Add an [`extensions_summary`](https://shopify.dev/docs/apps/build/sidekick#add-an-extensions-summary-to-your-app) to your `shopify.app.toml`. This is required for all apps with Sidekick-eligible extensions.

**Limits:**

You can register a maximum of 5 intents and 20 tools for each app. The tool limit is shared across all extension types (data and action).

***

## Example: Allow Sidekick to edit email content

Use an **app extension** to allow Sidekick to edit content in your app.

### Create an app extension

Use the [Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps) to create a Sidekick app action link extension, or a Sidekick app action extension. The example below shows how to create an app extension using an app action link extension.

## App action link

```terminal
shopify app generate extension --template app_action_link --name open-email
```

The command creates a new extension template in your app's `extensions` directory with the following structure:

## Edit extension folder structure

```toml
extensions/open-email
  ├── email-schema.json // Schema definition for the intent's input parameters
  ├── instructions.md // Guidelines for Sidekick on tool usage
  ├── README.md
  ├── shopify.extension.toml // The config file for the extension
  └── tools.json // Tool definitions for Sidekick actions
```

Modify `shopify.extension.toml` to include the `name`, `handle`, and `type` of your app extension.

## extensions/open-email/shopify.extension.toml

```toml
[[extensions]]
name = "Open email"
description = "Edit an email campaign"
handle = "open-email"
type = "admin_link"


[[extensions.targeting]]
target = "admin.app.intent.link"
url = "/edit/{id}"
tools = "./tools.json"
instructions = "./instructions.md"
```

**Note:**

`admin.app.intent.link` is a special target that is not tied to a Shopify resource that can be invoked from anywhere in the Shopify Admin.

The `description` field helps Sidekick understand when your extension is relevant. Be specific about what your extension does — a vague description means Sidekick won't reliably invoke your extension when merchants need it. See [Writing effective extension descriptions](https://shopify.dev/docs/apps/build/sidekick#writing-effective-extension-descriptions) for detailed guidance and examples.

The `url` may contain `{placeholder}` segments that are substituted at invocation time from values in your intent schema. Placeholders aren't filled automatically. You must declare a field with `mapTo: "param"` in the schema whose name (or `fieldName` alias) matches the placeholder. See [Map intent values into the URL](#map-intent-values-into-the-url) for the full mechanism.

### Register your extension as an intent

Add an `intents` configuration to your `shopify.extension.toml` with an `action`, `type` and `schema`.

`application/email` is used as an example `type` for this guide because this guide walks through editing an email campaign. App extensions support several app types for various popular use cases.

**Pick the type that matches your use case:**

The `type` shown below (`application/email`) is illustrative. Don't copy it verbatim unless your extension is actually for email campaigns. Pick the type from the supported types table below that best describes what your extension does. A mismatched type means Sidekick won't reliably invoke your extension when merchants need it.

If none of the supported types fit your scenario, let us know on the [Shopify Developer Community](https://community.shopify.dev/) so we can extend the list. Don't pick an unrelated type as a placeholder.

## extensions/open-email/shopify.extension.toml

```toml
[[extensions.targeting.intents]]
type = "application/email"
action = "edit"
schema = "./email-schema.json"
```

The following types are currently supported for app intents. Each type supports both `create` and `edit` actions.

| Type | Description | Schema reference |
| - | - | - |
| `application/ad` | Ad campaigns | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/ad.json` |
| `application/campaign` | Marketing campaigns | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/campaign.json` |
| `application/email` | Email campaigns | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/email.json` |
| `application/faq` | FAQ management | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/faq.json` |
| `application/loyalty-program` | Loyalty programs | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/loyalty-program.json` |
| `application/return` | Returns management | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/return.json` |
| `application/review` | Product reviews | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/review.json` |
| `application/shipment` | Shipment tracking | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/shipment.json` |
| `application/ticket` | Support tickets | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/ticket.json` |

If there's another type you'd like us to support, let us know on the [Shopify Developer Community](https://community.shopify.dev/).

**Unsupported types fail at deploy:**

Declaring an unsupported `type` (for example, `application/my-resource`) causes `shopify app deploy` to reject the extension with `Intent is invalid: type '<value>' is not supported`. There's no silent fallback.

### Declare the extension schema

Declare your schema in the `JSON` file referenced in `shopify.extension.toml`. The full intent schema definition can be inspected at <https://extensions.shopifycdn.com/shopifycloud/schemas/v1/intent.json>.

**Note:**

`inputSchema` is required and must reference a schema matching the `type` defined in `shopify.extension.toml`. For example, `application/email` should reference <https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/email.json>

The intent `inputSchema` must not declare `required` fields (at the top level or nested inside any property). Intents render UI for merchants to fill in missing information, so all fields are treated as optional at invocation time. Use `description` and other constraints (such as `minLength`, `format`, `enum`) to guide input instead.

The schema has two top-level sections that an intent invocation populates:

* `value`: the primary identifier for the resource being acted on (for example, the GID of the email campaign being edited). This becomes the `value` parameter of `intents.invoke({ value })`.
* `inputSchema`: additional data the caller provides (for example, the recipient or subject). Properties under `inputSchema.properties` become the `data` object of `intents.invoke({ data })`.

The `value` field, and each property in `inputSchema.properties`, can declare `mapTo` and `fieldName` to control how the value is transported when Sidekick opens your `url`. See [Map intent values into the URL](#map-intent-values-into-the-url) for the full mechanism.

## ./email-schema.json

```json
{
  "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/intent.json",
  "value": {
    "type": "string",
    "description": "The GID of the email campaign to edit.",
    "mapTo": "param",
    "fieldName": "id"
  },
  "inputSchema": {
    "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/email.json",
    "type": "object",
    "properties": {
      "recipient": {
        "type": "string",
        "description": "Primary recipient email address (e.g., email@example.com)",
        "format": "email"
      },
      "cc": {
        "type": "array",
        "description": "CC recipient email addresses",
        "items": {"type": "string", "format": "email"}
      },
      "subject": {
        "type": "string",
        "description": "Email subject line (1-200 characters)",
        "minLength": 1,
        "maxLength": 200
      },
      "body": {
        "type": "string",
        "description": "Email message body (supports rich text formatting)"
      },
      "template_id": {
        "type": "string",
        "description": "Email template to use",
        "enum": ["blank", "welcome", "promotion"]
      },
      "send_at": {
        "type": "string",
        "description": "Schedule email for future delivery (ISO 8601 date-time format)",
        "format": "date-time"
      },
      "priority": {
        "type": "string",
        "description": "Email priority level",
        "enum": ["low", "normal", "high"],
        "default": "normal"
      },
      "track_opens": {
        "type": "boolean",
        "description": "Enable email open tracking",
        "default": true
      }
    }
  }
}
```

**Common mistakes to avoid:**

#### Leaving the URL placeholder unmapped

If your `url` contains a placeholder such as `{id}`, then something in the schema must map to it. The mapping must be either the top-level `value` field with `mapTo: "param"` and a matching `fieldName`, or an `inputSchema` property with `mapTo: "param"` (whose key matches the placeholder, or which declares a matching `fieldName`). Otherwise you'll get a runtime error such as "Missing ':id' param", which means the URL placeholder is never substituted. See [Map intent values into the URL](#map-intent-values-into-the-url) for the valid patterns.

#### Removing `$ref` or its sibling keywords from `inputSchema`

The `inputSchema` block uses [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/schema), which allows `$ref` alongside `type` and `properties`. This is intentional. Removing `$ref`, or removing the `type`/`properties` siblings alongside it, breaks schema validation and produces a deploy-time error: `Intent is invalid: a $ref for the inputSchema matching the intent type must be present`.

#### Adding `required` to the intent `inputSchema`

Don't add a `required` array anywhere in the intent `inputSchema`, not at the top level and not nested inside any property (for example, on array items). This produces a deploy-time error (`Intent is invalid: inputSchema must not have required fields`). The `required`-forbidden rule applies only to intent schemas. Tool `inputSchema` allows `required` like normal JSON Schema.

### Write your tools schema

**Tools are required for intents:**

Sidekick only supports invoking intents that have tools. If `tools` isn't set in your `shopify.extension.toml`, or your `tools.json` is empty, then your intent won't be registered with Sidekick.

**Tools here run after the page opens, not before:**

The tools declared in this `tools.json` aren't navigation tools. They execute while the intent's destination page is open.

The tools declared in this `tools.json` execute *while the intent's destination page is open* at the route specified by the `url` for the `admin.app.intent.link` target. Navigation is already owned by `admin.app.intent.link` itself, so don't declare a tool that just duplicates the intent's action (for example, an `edit_email` tool on an `application/email` `edit` intent that only opens the editor).

Tools should expose the ability to read or mutate state *while the merchant is on the page*. Examples: `design_email`, `apply_template`, `schedule_send`. Each tool must be registered at runtime via [`shopify.tools.register`](#bind-tool-handlers-at-runtime) from the route the intent's `url` opens, otherwise Sidekick has no handler to invoke.

Declare your tools in a `JSON` file referenced by the `tools` field in `shopify.extension.toml`. Tools define the actions Sidekick can perform while the intent is open. These should be specific to the intent context. For example, a `design_email` tool updates the visual design of the email campaign the merchant is currently editing.

The tool `inputSchema` is a standard [JSON Schema](https://json-schema.org/). Unlike the intent `inputSchema`, it doesn't require a `$ref` to an `application/*` schema, and it can use `required` to mark mandatory fields just like any normal JSON Schema (see the [data extension example](https://shopify.dev/docs/apps/build/sidekick/build-app-data) for a tool that does this). Keep the two schemas distinct and don't conflate them.

## ./tools.json

```json
[
  {
    "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/tool.json",
    "name": "design_email",
    "description": "Update the visual design of the currently open email campaign, including background color, layout, and styling",
    "inputSchema": {
      "type": "object",
      "properties": {
        "background_color": {
          "type": "string",
          "description": "Background color for the email body (hex code, e.g. #FFFFFF)"
        },
        "layout": {
          "type": "string",
          "description": "Email layout template",
          "enum": ["single-column", "two-column", "hero-image"]
        },
        "font_family": {
          "type": "string",
          "description": "Primary font family for email text"
        }
      }
    }
  }
]
```

**Limits:**

Each tool `name` can be up to 64 characters. Each tool `description` can be up to 512 characters. You can register a maximum of 20 tools for each app, shared across all extensions (data and action).

***

## Map intent values into the URL

When Sidekick invokes an intent, your app receives the request at the `url` declared in `shopify.extension.toml`. The intent schema controls where each value ends up: a URL path segment, the query string, the URL hash, or the request body.

### How placeholder substitution works

A `url` can contain `{placeholder}` segments (for example, `url = "/app/customers/{id}"`). Placeholders are not filled in automatically. For each placeholder, the intent schema must declare a matching field with `mapTo: "param"`. The match is by name:

* For an `inputSchema` property, the property's key is used by default. Declare `fieldName` only when the key doesn't match the placeholder (see [`fieldName`](#fieldname) below).
* For the top-level `value` field, you must always declare `fieldName: "<placeholder>"`, because `value` has no schema key to use as a default.

If nothing in the schema maps to a placeholder, the literal `{id}` (or an empty segment) is sent to your app.

#### Working with GIDs

When the value mapped to a `param` placeholder is a [GID](https://shopify.dev/docs/api/usage/gids) (a string starting with `gid://`), Sidekick takes everything after the last `/` and substitutes that bare tail identifier into the URL path. Both shapes that show up across these docs work the same way:

* `gid://shopify/EmailCampaign/123` becomes `123` in `/app/campaigns/123/edit`.
* `gid://application/email/123` also becomes `123`.

Your route reads that bare identifier from path params (`useParams()` or your router's equivalent), not the full GID. The same parsing applies to any `inputSchema` property mapped to `param`. You don't need a resolver helper.

Non-GID strings are substituted as-is. Values mapped to `query_param`, `hash`, or form data destinations also pass through verbatim, without GID parsing. If you need the full GID at runtime, read it from the [intent payload](#read-the-incoming-intent) instead of the URL.

### `mapTo`

`mapTo` specifies how a value is transported when Sidekick constructs the request to your `url`. It's a string with one of the following values:

| `mapTo` | Effect | Example |
| - | - | - |
| `form_data` | Sends the value in the request body as form data. Rarely needed. This is the default for `inputSchema` properties when no `mapTo` is declared. | — |
| `hash` | Appends the value to the URL's hash fragment. | `/app/campaigns#edit` |
| `param` | Substitutes the value into a `{placeholder}` in the URL path. | `/app/campaigns/{id}` → `/app/campaigns/4353532` |
| `query_param` | Appends the value to the URL's query string. | `/app/campaigns?status=draft` |

`mapTo` is valid on the top-level `value` field and on any property inside `inputSchema.properties`.

### `fieldName`

`fieldName` is the target name at the destination specified by `mapTo`:

* `mapTo: "param"`: the placeholder name in the URL path (the text between `{` and `}`).
* `mapTo: "query_param"`: the key used in the query string.
* `mapTo: "form_data"`: the form field name.

If `fieldName` is omitted, the property key from the schema is used. Declare `fieldName` when your schema key doesn't match the destination name. For example, when an `inputSchema` property is called `reviewId` but needs to fill an `{id}` path placeholder:

```json
"reviewId": {
  "type": "string",
  "mapTo": "param",
  "fieldName": "id"
}
```

The top-level `value` field always needs an explicit `fieldName` when mapped to `param` or `query_param`, because `value` isn't a property key that can be used as a default.

### Example: campaign edit with `{id}` substitution

This example registers an extension for editing a marketing campaign. The URL contains an `{id}` placeholder that's filled from the intent's `value`.

## extensions/open-campaign/shopify.extension.toml

```toml
[[extensions]]
name = "Open campaign"
description = "Edit a marketing campaign"
handle = "open-campaign"
type = "admin_link"


[[extensions.targeting]]
target = "admin.app.intent.link"
url = "/app/campaigns/{id}/edit"
tools = "./tools.json"
instructions = "./instructions.md"


[[extensions.targeting.intents]]
type = "application/campaign"
action = "edit"
schema = "./campaign-schema.json"
```

## ./campaign-schema.json

```json
{
  "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/intent.json",
  "value": {
    "type": "string",
    "description": "The GID of the campaign to edit.",
    "mapTo": "param",
    "fieldName": "id"
  },
  "inputSchema": {
    "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/campaign.json",
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "The display name of the campaign."
      },
      "budget_amount": {
        "type": "number",
        "description": "The total budget for the campaign in the shop's currency.",
        "minimum": 0
      }
    }
  }
}
```

When Sidekick invokes this intent with a campaign GID, the `value` is substituted into the `{id}` placeholder before the request reaches your server. Any `inputSchema` properties (like `name` or `budget_amount`) are sent as form data by default.

### Example: rename a field with `fieldName`

If an `inputSchema` property's key doesn't match the URL placeholder, use `fieldName` to map them. The following schema routes the `reviewId` property into the `{id}` path segment:

## ./review-schema.json

```json
{
  "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/intent.json",
  "inputSchema": {
    "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/review.json",
    "type": "object",
    "properties": {
      "reviewId": {
        "type": "string",
        "description": "The GID of the review.",
        "mapTo": "param",
        "fieldName": "id"
      }
    }
  }
}
```

With `url = "/app/reviews/{id}/edit"`, invocations that supply `reviewId` render as `/app/reviews/<reviewId>/edit`.

***

## Bind tool handlers at runtime

After declaring tools statically in `tools.json`, use the [Tools API](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/tools-api) to bind handler functions at runtime.

The schema in `tools.json` only declares what the tool looks like to Sidekick. The handler is the code that actually runs when Sidekick invokes the tool.

**Where the handler runs:**

For an `admin_link` app extension, the handler is registered from the React component for the route that the extension's `url` navigates to. Sidekick opens that page, the page mounts, and the page registers the handler. This mirrors the [data extension](https://shopify.dev/docs/apps/build/sidekick/build-app-data) flow, where the handler is registered from the JavaScript module declared by `module = "./src/index.js"`.

Use `useEffect` so the handler is bound when the page mounts and unregistered when the merchant navigates away. `shopify.tools.register` returns a cleanup function that handles the unregistration:

```jsx
import {useEffect} from 'react';
import {useParams} from 'react-router';


export default function CampaignEditor() {
  // `id` is the URL path parameter that Sidekick substituted from the
  // intent's `value` via `mapTo: "param"`. It's already the bare
  // identifier — not the full `gid://shopify/EmailCampaign/123` GID.
  const {id: campaignId} = useParams();


  useEffect(() => {
    const cleanup = shopify.tools.register('design_email', async (input) => {
      const response = await fetch(`/api/campaigns/${campaignId}/design`, {
        method: 'PATCH',
        body: JSON.stringify(input),
      });
      return response.json();
    });


    return () => cleanup();
  }, [campaignId]);


  // …render the campaign editor UI
}
```

The handler closure captures the route's state (here, `campaignId`), so re-running the effect when that state changes replaces the handler with one bound to the new campaign. The cleanup function unregisters it when the component unmounts.

See the [Tools API reference](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/tools-api) for the full surface, including `unregister`, `clear`, and additional lifecycle examples.

***

## Read the incoming intent

When your extension opens for an app intent, read the incoming payload from [`shopify.intents.request`](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/intents-api#request). Read the current value synchronously from `shopify.intents.request.value` (it's `null` when your app isn't running inside an intent workflow). The payload contains the `action`, `type`, `value`, and `data` fields for the invocation.

```js
const request = shopify.intents.request?.value;
if (request) {
  // request.action is the operation, for example 'create' or 'edit'
  // request.type matches the type declared in shopify.extension.toml
  // request.data contains the fields defined by your intent's input schema
  hydrateForm(request);
}
```

If your extension stays mounted across intent transitions, use `shopify.intents.request.subscribe(callback)` to react to updates without polling.

The same payload is also appended to the landing URL as an `?intent=<URL-encoded JSON>` query parameter, so you can read it synchronously from `window.location` before App Bridge is ready. See the [`request`](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/intents-api#request) section of the Intents API reference for the full payload shape.

***

## Resolve the intent

When a merchant finishes, fails, or cancels the workflow your extension renders for an app intent, resolve the intent using the [Intents API](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/intents-api#response-methods) `response` methods. This returns control to the surface that invoked your intent and delivers the result.

```js
// On successful completion, pass any data the invoker needs:
await shopify.intents.response.ok({campaignId: 'gid://shopify/EmailCampaign/123'});


// On failure, return an error message (and optional validation issues):
await shopify.intents.response.error('Could not save the email campaign.');


// If the merchant cancels without completing:
await shopify.intents.response.closed();
```

See the [Intents API reference](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/intents-api#response-methods) for the full `response` surface.

***

## Write instructions for using the app extension

Define instructions for how Sidekick should use your app extension in an `instructions.md` file.

**Note:**

`instructions.md` is optional, but is highly recommended for providing context and guidance to Sidekick about your app extension.

## ./instructions.md

```md
## When to Use the Design Email Tool


Use the `design_email` tool when the merchant asks to:
- Change the background color or layout of the email they're editing
- Update the visual styling or font of the current campaign
- Switch to a different email layout template


## Important Guidelines


- Only use `design_email` while the merchant has an email campaign open
- When updating the design, confirm changes with the merchant before applying
- Refer to layouts as "single-column", "two-column", or "hero-image"
```

**Limits:**

The `description` field has a 256-token limit. The `instructions.md` file has a 2,048-token limit.

***

## Navigation constraints

An intent is bound to exactly one pathname — the `url` declared on your extension's `admin.app.intent.link` target. The intent modal represents work happening at that pathname, and the platform enforces this by closing the modal whenever the merchant navigates away from it.

**Intent modals close when the pathname changes:**

Any navigation that changes the pathname inside an intent modal closes it. This applies to every navigation mechanism that produces a different pathname, including:

* Server-side redirects (for example, an HTTP `302` from a loader or action that points at a different pathname).
* Client-side navigation via `useNavigate()`, `<Link>`, `<Form>`, or equivalent router APIs that target a different pathname.
* Setting `window.location` to a different pathname.

The modal closes silently — no error is surfaced. If your intent disappears immediately after loading, a pathname change is the most likely cause.

Updating the search string or hash on the same pathname (for example, `/app/customers?id=123`) does **not** close the modal. Use that to switch UI state without leaving the intent.

### Render different UI states at the same pathname

Because an intent is pinned to a single pathname, switch between UI states using query parameters, loader data, or component state instead of pathname changes. For example, render a list view and a detail form at the same route, driven by a `?intent=edit&id=123` query string or inline component state:

## app/routes/app.customers.jsx

```jsx
export async function loader({ request }) {
  const url = new URL(request.url);
  const id = url.searchParams.get('id');
  return {
    id,
    customer: id ? await fetchCustomer(id) : null,
  };
}


export default function Customers() {
  const { id, customer } = useLoaderData();
  // Render the detail view inline when `id` is set, otherwise the list.
  return id ? <CustomerForm customer={customer} /> : <CustomerList />;
}
```

When the merchant finishes their work, call [`shopify.intents.response.ok(data)`](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/intents-api#response-methods) to resolve the intent. The invoking surface closes the modal — you don't need to navigate yourself.

***

## End-to-end example: search, open, and edit an email campaign

This walkthrough connects the two halves of the Sidekick app extensions surface: the [data extension](https://shopify.dev/docs/apps/build/sidekick/build-app-data) that returns resource links, and the action-link extension on this page that opens the editor. It uses the same `application/email` example shown earlier on this page so the moving parts line up with what you've already seen.

The trip has five turns:

1. The merchant asks Sidekick a question. Sidekick decides that an email-related question matches the app's `extensions_summary` and invokes the data extension's `search_campaigns` tool.
2. `search_campaigns` returns resource links with `mimeType: "application/email"`. Sidekick presents the results to the merchant.
3. Because the link's `mimeType` (`application/email`) matches an `edit` intent on the action-link extension, Sidekick offers to edit one of the campaigns and asks the merchant which. After the merchant replies (for example, "edit the first campaign"), Sidekick invokes the intent with that campaign's resource-link `uri` as the `value` (for example, `gid://application/email/123`).
4. Shopify opens the intent's `url` (`/edit/{id}`) in the intent modal. Because the schema declares `mapTo: "param"`, Sidekick strips the GID and substitutes the bare tail, so the route receives `/edit/123`. The page mounts and calls [`shopify.tools.register("design_email", …)`](#bind-tool-handlers-at-runtime).
5. The merchant asks Sidekick to change something about the design. Sidekick invokes `design_email` with the proposed update. The handler stages the change into form state and returns. The merchant clicks **Save** themselves; Sidekick never commits silently.

### 1.​The data extension returns resource links

`search_campaigns` lives in the data extension you built in [the data extension guide](https://shopify.dev/docs/apps/build/sidekick/build-app-data). Its handler returns resource links whose `mimeType` matches the intent type declared in the next step:

## extensions/tools/src/index.js

```js
export default () => {
  shopify.tools.register('search_campaigns', async ({query, status}) => {
    const response = await fetch('/api/campaigns/search', {
      method: 'POST',
      body: JSON.stringify({query, status}),
    });
    const campaigns = await response.json();


    return {
      results: campaigns.map((campaign) => ({
        type: 'resource_link',
        // `campaign.id` is a local identifier like `123`, not a GID. Compose
        // the URI here so it stays a well-formed `gid://` value.
        uri: `gid://application/email/${campaign.id}`,
        name: campaign.subject,
        mimeType: 'application/email',
        _meta: {
          status: campaign.status,
          editedAt: campaign.editedAt,
          openRate: campaign.openRate,
        },
      })),
    };
  });
};
```

The `mimeType` (`application/email`) is what makes each result clickable. Sidekick matches it to the action-link extension's intent `type` in the next step. The `_meta` field carries the small amount of summary data the model needs to reason about the result without a separate fetch.

### 2.​The action-link extension declares the intent and the in-page tool

The `extensions/open-email` extension you scaffolded earlier on this page already has the right shape. Its `shopify.extension.toml` declares the landing URL and intent:

## extensions/open-email/shopify.extension.toml

```toml
[[extensions]]
name = "Open email"
description = "Edit an email campaign"
handle = "open-email"
type = "admin_link"


[[extensions.targeting]]
target = "admin.app.intent.link"
url = "/edit/{id}"
tools = "./tools.json"
instructions = "./instructions.md"


[[extensions.targeting.intents]]
type = "application/email"
action = "edit"
schema = "./email-schema.json"
```

The full schema was shown earlier in [Declare the extension schema](#declare-the-extension-schema), with all the optional `inputSchema.properties` for an email campaign. The piece that matters for this walkthrough is the top-level `value` field, which maps the GID Sidekick passes into the `{id}` placeholder via `mapTo: "param"` and `fieldName: "id"`.

The extension's `tools.json` declares `design_email`, the in-page tool that runs *after* the page is open. It doesn't redeclare navigation; that's already handled by `admin.app.intent.link` and the `url` above. The full tool definition is in [Write your tools schema](#write-your-tools-schema) earlier on this page.

### 3.​The app route registers the in-page tool

When the merchant clicks a search result, Shopify opens `/edit/<id>`. Because `mapTo: "param"` strips the GID before substitution, the route receives the bare tail identifier (for example, `123`), not the full GID. No URL parsing helper is needed; see [Working with GIDs](#working-with-gids) for the contract.

## app/routes/edit.$id.tsx

```tsx
import {useEffect, useState} from 'react';
import {useParams, useLoaderData} from 'react-router';
import type {LoaderFunctionArgs} from 'react-router';
import {authenticate} from '../shopify.server';
import {getCampaign} from '../models/campaign.server';


export async function loader({params, request}: LoaderFunctionArgs) {
  const {cors} = await authenticate.admin(request);
  const campaign = await getCampaign(params.id!);
  return cors(Response.json({campaign}));
}


export default function EditCampaign() {
  // `id` is the bare campaign identifier (for example, `123`) that
  // Sidekick extracted from the intent's `value` GID via mapTo: "param".
  const {id} = useParams();
  const {campaign} = useLoaderData<typeof loader>();
  const [staged, setStaged] = useState(campaign);


  useEffect(() => {
    const cleanup = shopify.tools.register('design_email', async (input) => {
      setStaged((prev) => ({...prev, ...input}));
      return {
        ok: true,
        campaign_id: id,
        staged: input,
        note: 'Changes staged in the form. Awaiting merchant Save.',
      };
    });
    return () => cleanup();
  }, [id]);


  // ...render the staged campaign and a Save button that commits to /api/campaigns/:id
}
```

The tool's response includes `ok: true` and a `note` that tells Sidekick the change is staged, not saved. Sidekick relays that to the merchant so they know to click **Save** themselves.

### Verify the round trip locally

Run this end-to-end check before you ship. Each step builds on the previous one. If a step fails, fix it before moving on.

1. `shopify app dev` starts and prints both extensions as ready.
2. Open the Sidekick preview link printed by `dev` for the `admin.app.tools.data` target. Ask Sidekick a question that should hit `search_campaigns` (for example, "show me my best-performing campaigns from last month").
3. Confirm Sidekick presents the results from your tool (typically as a text summary, not raw JSON). That confirms the tool returned valid resource links.
4. Ask Sidekick to edit one (for example, "edit the first one"). The intent modal opens at `/edit/<id>` with the bare ID substituted into the URL. If you see a literal `{id}` or an empty path segment, your schema's `mapTo` / `fieldName` is misconfigured. See [Map intent values into the URL](#map-intent-values-into-the-url).
5. With the editor open, ask Sidekick to change something about the design (for example, "switch this to the two-column layout"). Sidekick invokes `design_email`; the change appears staged in the form.
6. Click **Save** in the form. The change is committed by your app, not by Sidekick.

***

## Putting it all together

After following this tutorial, your `extensions` folder structure should look like this:

## Folder structure

```toml
extensions/open-email
  ├── email-schema.json // Schema definition for the intent's input parameters
  ├── instructions.md // Guidelines for Sidekick on tool usage
  ├── README.md
  ├── shopify.extension.toml // The config file for the extension
  └── tools.json // Tool definitions for Sidekick actions
```

***

## Import Shopify resources with `shopify/*` intents

The [email content editing example](#example-edit-email-content) uses an application intent (`application/email`), where your app defines the shape of `value` and `inputSchema`, and Sidekick navigates the merchant into your app to complete the action.

App extensions also support Shopify resource intents, where your app fulfills an action against a Shopify-native resource identified by a [Global ID](https://shopify.dev/docs/api/usage/gids) (GID). For `shopify/*` types, apps can register `import` for one resource or `import+bulk` for many resources at once. The `create` and `edit` verbs on `shopify/*` types are reserved for [admin intents](https://shopify.dev/docs/apps/build/admin/admin-intents), which are Shopify's native resource editors.

Use a Shopify resource intent when your app takes an existing Shopify resource as input and produces a (possibly different) Shopify resource as output. The `value` parameter carries the source resource's GID. `inputSchema` carries the rest of the data your app needs, and `outputSchema` describes the GID of the resulting Shopify resource. A typical example is a print-on-demand app. The app takes a generic base product (such as a blank T-shirt) and creates a custom-printed variant of it as a new Shopify Product.

### Choose between `application/*` and `shopify/*` intents

Use this table to choose the right intent family:

| Intent family | Use when | Examples | `$schema` to use |
| - | - | - | - |
| `application/*` | Your app owns the data shape (form fields, content payloads, free-form values) | `application/email`, `application/ticket` | `intent.json` |
| `shopify/*` | Your app operates on a Shopify resource identified by a GID | `shopify/product`, `shopify/customer`, `shopify/order` | `shopify-intent.json` (single) or `shopify-intent-bulk.json` (bulk) |

Intent type names are compared case-insensitively for lookup and duplicate detection. `shopify/Product` and `shopify/product` resolve to the same intent.

### Register a Shopify resource intent

In `shopify.extension.toml`, set `type` to a `shopify/*` resource type and `action` to `import`. Point `schema` at a JSON file that uses the `shopify-intent.json` meta-schema:

## extensions/customize-tshirt/shopify.extension.toml

```toml
[[extensions]]
name = "Customize T-shirt"
description = "Take a blank base T-shirt product and create a custom-printed variant as a new Shopify Product"
handle = "customize-tshirt"
type = "admin_link"


[[extensions.targeting]]
target = "admin.app.intent.link"
url = "/customize/{id}" # {id} is filled with the bare ID parsed from the resource GID.
tools = "./tools.json"
instructions = "./instructions.md"


[[extensions.targeting.intents]]
type = "shopify/product"
action = "import"
schema = "./product-import-schema.json"
```

### Declare the import schema

A Shopify resource intent schema has a fixed shape with three required top-level keys:

* **`value`**: in the schema, a `$ref` to the published GID schema for the resource, with optional `mapTo`/`fieldName` to control URL transport (see [Map intent values into the URL](#map-intent-values-into-the-url)). At runtime, callers pass the GID as a string in `intents.invoke({ value })`.
* **`inputSchema`**: your app's custom input fields. Properties become the `data` object of `intents.invoke({ value, data })`. Don't add `required` fields. Unlike `application/*` intents, the `shopify-intent.json` meta-schema doesn't require a `$ref` on `inputSchema`. The `value` field already pins the resource type via its GID `$ref`.
* **`outputSchema`**: describes the success response. For single intents, declare `properties.id` as a `$ref` to the same GID schema. The merchant (or Sidekick) reads this back using [`shopify.intents.response.ok`](https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/intents-api#response-methods).

The following example uses `shopify/product` as both the source and output resource:

## ./product-import-schema.json

```json
{
  "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify-intent.json",
  "value": {
    "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/product/gid.json",
    "mapTo": "param",
    "fieldName": "id"
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Product title (e.g. 'Custom Graphic Tee')",
        "minLength": 1,
        "maxLength": 255
      },
      "design_url": {
        "type": "string",
        "format": "uri",
        "description": "URL of the custom design image to print on the t-shirt"
      },
      "size": {
        "type": "string",
        "description": "T-shirt size",
        "enum": ["XS", "S", "M", "L", "XL", "XXL"]
      },
      "color": {
        "type": "string",
        "description": "Base t-shirt color",
        "enum": ["white", "black", "navy", "heather_gray"]
      },
      "price": {
        "type": "string",
        "description": "Product price in shop currency (e.g. '29.99')",
        "pattern": "^\\d+\\.\\d{2}$"
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/product/gid.json"
      }
    }
  }
}
```

### Bulk imports with `import+bulk`

To import many resources in a single intent invocation, set `action = "import+bulk"` and use the `shopify-intent-bulk.json` meta-schema. `value` becomes an array whose items are GIDs, and `outputSchema.properties.ids` is the array of GIDs your app returns on success.

The `+bulk` suffix identifies a bulk variant of a verb. For Shopify resource intents, `import+bulk` applies `import` to many resources at once.

A bulk intent's `value` is an array, so it can't fill a single `{id}` URL placeholder. Register the bulk variant on its own target (or its own extension) with a static `url`, and let your handler iterate the array at runtime instead of relying on path substitution. `mapTo` and `fieldName` are still allowed on the array itself. The `shopify-intent-bulk.json` meta-schema accepts them on the `gidArraySchema` node, so you can transport the array as form data or a query param if your handler expects that.

Register the bulk variant with a static `url`:

## extensions/customize-tshirt-bulk/shopify.extension.toml

```toml
[[extensions]]
name = "Customize T-shirts (bulk)"
description = "Take multiple blank base T-shirt products and create custom-printed variants as new Shopify Products in a single workflow"
handle = "customize-tshirt-bulk"
type = "admin_link"


[[extensions.targeting]]
target = "admin.app.intent.link"
url = "/customize/bulk" # Static path. `value` is an array, so there's no single id to substitute.
tools = "./tools.json"
instructions = "./instructions.md"


[[extensions.targeting.intents]]
type = "shopify/product"
action = "import+bulk"
schema = "./product-import-bulk-schema.json"
```

Define the bulk schema with an array of GIDs:

## ./product-import-bulk-schema.json

```json
{
  "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify-intent-bulk.json",
  "value": {
    "type": "array",
    "items": {
      "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/product/gid.json"
    }
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "designs": {
        "type": "array",
        "description": "Per-source-product customization data. One entry per GID in `value`.",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string", "minLength": 1, "maxLength": 255},
            "design_url": {"type": "string", "format": "uri"},
            "price": {"type": "string", "pattern": "^\\d+\\.\\d{2}$"}
          }
        },
        "mapTo": "form_data",
        "fieldName": "designs"
      },
      "collection_id": {
        "type": "string",
        "description": "Optional collection to add all customized products to",
        "mapTo": "query_param",
        "fieldName": "collection_id"
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "ids": {
        "type": "array",
        "items": {
          "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/product/gid.json"
        }
      }
    }
  }
}
```

### Folder structure

With both variants registered, your `extensions` directory has one extension per import variant. The single-resource extension routes to a URL with an `{id}` placeholder filled from `value`. The bulk extension routes to a static path because `value` is an array:

## extensions/

```toml
extensions/customize-tshirt
  ├── instructions.md // Guidelines for Sidekick on tool usage
  ├── product-import-schema.json // Single-resource import schema
  ├── README.md
  ├── shopify.extension.toml // url = "/customize/{id}", action = "import"
  └── tools.json // Tool definitions for Sidekick actions


extensions/customize-tshirt-bulk
  ├── instructions.md
  ├── product-import-bulk-schema.json // Bulk import schema
  ├── README.md
  ├── shopify.extension.toml // url = "/customize/bulk", action = "import+bulk"
  └── tools.json
```

### Supported Shopify resource intents

The following `shopify/*` types are supported. Each supports both `import` and `import+bulk`:

| Type | GID schema |
| - | - |
| `shopify/customer` | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/customer/gid.json` |
| `shopify/order` | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/order/gid.json` |
| `shopify/product` | `https://extensions.shopifycdn.com/shopifycloud/schemas/v1/shopify/product/gid.json` |

The single-resource and bulk meta-schemas (`shopify-intent.json` and `shopify-intent-bulk.json`) are inspectable at the same `extensions.shopifycdn.com` host as the existing `intent.json` schema.

### Common mistakes to avoid

Review these common schema and configuration mistakes before you deploy. Each mistake causes a deploy-time error that points to the mismatched field or schema.

#### Wrong meta-schema for the action

`action = "import"` requires `"$schema": ".../v1/shopify-intent.json"`, and `action = "import+bulk"` requires `"$schema": ".../v1/shopify-intent-bulk.json"`. Mixing them produces a deploy-time error such as `Shopify resource type 'shopify/product' requires $schema to be shopify-intent.json` or `... with bulk action requires $schema to be shopify-intent-bulk.json`.

#### `value.$ref` doesn't match `type`

`value.$ref` (or `value.items.$ref` for bulk) must point to the GID schema for the same resource declared as `type` in `shopify.extension.toml`. Pointing `shopify/product` at `shopify/order/gid.json`, or at a non-GID schema like `application/email.json`, fails with `value.$ref '...' does not match the configured resource type 'shopify/product'` or `value.$ref '...' is not a valid GID schema`.

#### Referencing a GID schema that isn't published

Only the resources in [Supported Shopify resource intents](#supported-shopify-resource-intents) have GID schemas you can `$ref`. Pointing at, for example, `shopify/widget/gid.json` fails with `value.$ref '...' does not reference a registered GID schema`.

#### Forgetting the GID `$ref` on `outputSchema`

`outputSchema.properties.id.$ref` (single) or `outputSchema.properties.ids.items.$ref` (bulk) is required and must use the same GID schema as `value`. Returning a bare string instead produces an error like `outputSchema.properties.id.$ref must contain a $ref to a Shopify GID schema`.

#### Using `application/*` and shopify-intent meta-schemas together

`application/*` types must use `intent.json`. Setting `"$schema": ".../v1/shopify-intent.json"` on an `application/email` intent produces `application type 'application/email' requires $schema to be intent.json`. The reverse is also enforced.

***