--- 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. **Coming soon:** Support for intents without tools (pure navigation) is not yet available. Currently, Sidekick only supports invoking activities that have activity tools. Navigation-only intents will be supported in the near future. **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 '' 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 . **Note:** `inputSchema` is required and must reference a schema matching the `type` defined in `shopify.extension.toml`. For example, `application/email` should reference 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 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: ""`, 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//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=` 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()`, ``, `
`, 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 ? : ; } ``` 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/`. 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(); 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/` 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 ``` ***