--- title: Use extensions to surface app data description: Use extensions to surface app data source_url: html: 'https://shopify.dev/docs/apps/build/sidekick/build-app-data' md: 'https://shopify.dev/docs/apps/build/sidekick/build-app-data.md' --- # Use extensions to surface app data **Developer preview:** We're selecting developer partners to get limited early access and provide feedback on Sidekick app extensions. [Submit your interest](https://docs.google.com/forms/d/e/1FAIpQLScxM8VQao5GGlIF-8TeiYQp-ucQiTFwSai35oDBzDuIpN5O7g/viewform?usp=dialog) and we'll reach out if you're selected. Use an app extension to expose data in your app to Sidekick. By providing your app's data in an app extension, Sidekick can search your app's data to get tailored results. Merchants can get value from your app just by working with Sidekick, while also staying in their flow. ### Use case example in this guide This guide shows you how to allow Sidekick to search your app's data. You can use this example to build your own app extension for search, and other tasks. In this example, a merchant can ask Sidekick to find the best performing subject lines in their email campaigns. Sidekick searches using the app extension in the email app, then returns the best options. Clicking on an option invokes the email app, navigated right to the correct result. ![Sidekick email search interface](https://shopify.dev/assets/assets/admin/sidekick/email-performance-flow-C00FiYFF.png) *** ## 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. *** ## Allow Sidekick to use your app's data In this example, a merchant can ask Sidekick to find the best performing subject lines in their email campaigns. Sidekick searches using the app extension in the email app, then returns the best options. Clicking on an option invokes the email app, navigated right to the correct result. This app extension is headless, can be run at any point from anywhere, and can be called programmatically for Shopify search in the admin. ### Create an app extension Use `shopify-cli` to create an app extension. ## Terminal ```terminal shopify app generate extension --template app_tools --name tools ``` This will create a UI extension in the `extensions` folder. ## App tools folder structure ```toml extensions/tools ├── README.md ├── package.json ├── shopify.extension.toml // The config file for the extension ├── tsconfig.json ├── shopify.d.ts // Provides types for components and APIs available to the extension ├── src │ └── index.js // The code that powers your app extension └── tools.json // The schema for your app extension (created in the next step) ``` ### Configure your app extension Customize your app's extension in `shopify.extension.toml` to include a `description`. Optionally, you can link to instructions for how Sidekick should use your app extension. ## extensions/tools/shopify.extension.toml ```toml [[extensions]] name = "Email Tools" description = "Tools for working with email, searching email campaigns, and getting email campaign stats" handle = "tools" type = "ui_extension" [[extensions.targeting]] module = "./src/index.js" target = "admin.app.tools.data" tools = "./tools.json" instructions = "./instructions.md" ``` **Note:** `admin.app.tools.data` is a special target that is not tied to a Shopify resource and executes headlessly. The `description` field in `shopify.extension.toml` is required — you'll get a validation error if you leave it blank. Sidekick uses this field to determine when your extension is relevant to a merchant's question. A vague description like "Search extension for your app" won't give Sidekick enough context to invoke your extension reliably. Instead, be specific about the domain and tasks your extension covers. See [Writing effective extension descriptions](https://shopify.dev/docs/apps/build/sidekick#writing-effective-extension-descriptions) for detailed guidance and examples. **Limits:** The `description` field has a 256-token limit. The `instructions.md` file has a 2,048-token limit. ### Write your Java​Script module When your app's extension is invoked, your JavaScript will be called automatically in the Shopify sandbox. The sandbox provides access to [Direct API](https://shopify.dev/docs/api/admin-extensions/latest#direct-api-access) for making GraphQL queries, and [App Authentication](https://shopify.dev/docs/api/admin-extensions/latest#app-authentication) for fetching data from your app's backend. Your app extension must only be used for retrieving data from your app. If you need to perform actions in your app, use an [app extension](https://shopify.dev/docs/apps/build/sidekick/build-app-actions) and see [Resource Links](https://shopify.dev/docs/apps/build/sidekick/build-app-data#data-output-schema-best-practices) for more information. ## extensions/tools/src/index.js ```js export default () => { shopify.tools.register('get_campaigns', async ({name, date}) => { const response = await fetch('/api/campaigns', { method: 'POST', body: JSON.stringify({name, date}) }); return response.json(); }); shopify.tools.register('campaign_stats', async ({campaign_id}) => { const response = await fetch(`/api/campaigns/${campaign_id}/stats`); return response.json(); }); } ``` **Limits:** Your app extension must return a response of 4,000 tokens or less. Responses that exceed either limit will be rejected. Responses should be returned within 400ms. Extensions that consistently exceed this threshold may be skipped by Sidekick. ### Write your tools schema Declare your schema in the `JSON` file referenced in `shopify.extension.toml`. ## ./tools.json ```json [ { "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/tool.json", "name": "get_campaigns", "description": "Search email marketing campaigns", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "Perform a full text search" }, "after": { "type": "string", "description": "Cursor for pagination" }, "before": { "type": "string", "description": "Cursor for pagination" }, "first": { "type": "integer", "description": "Number of results to return" }, "last": { "type": "integer", "description": "Number of results from the end" }, "creationPeriod": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "editedAtPeriod": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "effectiveStatusDatePeriod": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "marketingActivityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "CANCELLED", "DELETED", "DRAFT", "FAILED", "INACTIVE", "PAUSED", "PENDING", "SCHEDULED" ] } }, "sortKey": { "type": "string", "enum": [ "CREATED_AT", "EDITED_AT", "EFFECTIVE_STATUS_DATE", "STATUS_UPDATED_AT", "SUBJECT", "UPDATED_AT" ] }, "sortOrder": { "type": "string", "enum": [ "ASC", "DESC" ] }, "contentType": { "type": "string", "enum": [ "CUSTOM_CODE_BODY", "THEME_INSTANCE" ] } } } }, { "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/tool.json", "name": "campaign_stats", "description": "Get statistics for a specific email marketing campaign", "inputSchema": { "type": "object", "properties": { "campaign_id": { "type": "string", "description": "The unique identifier of the campaign" } }, "required": ["campaign_id"] } } ] ``` **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). ### Write instructions for using the app extension Define instructions for how Sidekick should use your app extension in a `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 Email Tools Use these tools when the merchant asks about: - Email campaigns and newsletters - Subscriber lists and segments - Email automations and flows - Email marketing metrics ## Important Guidelines - Always confirm campaign details before sending - When creating segments, verify the conditions are correct - For campaign metrics, specify the date range if not provided - Email tools uses "flows" for automated email sequences (not "automations") ## Common Workflows ### Sending a Campaign 1. First verify the campaign exists using get_campaign 2. Confirm the target segment with the merchant 3. Use get_campaign_stats with the campaign ID ### Creating a Segment 1. Ask the merchant for the segmentation criteria 2. Translate their request into conditions 3. Create the segment and confirm the name ``` *** ## Putting it all together After following this tutorial, your `extensions` folder structure should look like this: ## Folder structure ```toml extensions/tools ├── instructions.md // The instructions for using the app extension ├── README.md // ├── package.json ├── tools.json // The schema for your tools ├── tsconfig.json ├── shopify.d.ts // Provides types for APIs available to the extension ├── shopify.extension.toml // The config file for the extension └── src └── index.js // The code that powers your app extension ``` ### Data output schema best practices Sidekick is optimized for results that are returned in Model Context Protocol's [Resource Links](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#resource-links) format. Using the Resource Links format ensures Sidekick will know how to invoke your app's [actions](https://shopify.dev/docs/apps/build/sidekick/build-app-actions) on the data returned by your extension. Your tool should return a `results` array containing one or more resource link objects. Each resource link must include the following fields: | Field | Required | Description | | - | - | - | | `type` | Yes | The resource link type identifier. Must be `"resource_link"`. | | `uri` | Yes | A URI that uniquely identifies the resource in your app. For example, `gid:application/email/123`. | | `name` | Yes | A human-readable label for the resource. | | `mimeType` | Yes | The content type of the resource. For example, `application/email`. Must match the `type` declared in your app's [intent configuration](https://shopify.dev/docs/apps/build/sidekick/build-app-actions#register-your-extension-as-an-intent). This is how Sidekick connects a search result to the correct action. | | `_meta` | No | An object containing summary data about the resource. Use this to include key details that Sidekick can reason about without needing a separate fetch. | **Note:** The `mimeType` value in your resource link must match the `type` field in your intent's `shopify.extension.toml` configuration. This is what allows Sidekick to connect a data result to the right app action. For example, if your intent declares `type = "application/email"`, your resource links should use `mimeType: "application/email"`. #### Basic example Use the `uri` field to link directly to a specific resource in your app. ## Example search campaign tool results ```js { results: [ { type: 'resource_link', uri: 'gid:application/email/123', name: 'Sale starts soon!', mimeType: 'application/email' } ] } ``` #### Include summary data with `_meta` You can include summary data in the `_meta` field to give Sidekick context it can reason about immediately, without making additional requests. We recommend this hybrid approach when the model needs to answer questions about the data (for example, filtering by status or reporting on dates) while still providing clickable resource links. ## Example results with summary data ```js { results: [ { type: 'resource_link', uri: 'gid:application/email/123', name: 'Sale starts soon!', mimeType: 'application/email', _meta: { status: 'ACTIVE', editedAt: '2025-01-27T10:00:00Z', openRate: 0.42 } }, { type: 'resource_link', uri: 'gid:application/email/456', name: 'Holiday promo', mimeType: 'application/email', _meta: { status: 'DRAFT', editedAt: '2025-01-25T08:30:00Z' } } ] } ``` #### Best practices for resource links Follow these guidelines to get the best results from Sidekick when returning resource links. *Keep `_meta` concise.* Only include the fields the model is most likely to need, such as status, dates, or key metrics. Large nested structures consume tokens quickly — if a response exceeds the 4,000-token limit, it will be rejected and the merchant won't see any results. *Let the resource link handle full detail.* The `uri` points to the complete resource in your app. Use `_meta` for a summary that helps the model answer the merchant's question, and let the merchant click through for everything else. *Match `mimeType` to your intent type.* If `mimeType` doesn't match the `type` in your [intent configuration](https://shopify.dev/docs/apps/build/sidekick/build-app-actions#register-your-extension-as-an-intent), Sidekick won't be able to connect the search result to the correct action. For example, if your intent declares `type = "application/email"`, every resource link for that intent should use `mimeType: "application/email"`. *Use stable URIs.* The `uri` value should be a stable identifier that won't change over time (for example, a GID). Sidekick may reference these URIs in follow-up actions, so they need to resolve consistently. ***