Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Standard API

The Standard API provides core functionality available to all admin UI extension types. Use this API to authenticate with your app backend, query the GraphQL Admin API, translate content, and handle intent-based navigation.

Anchor to Use casesUse cases

GraphQL queries: Query the GraphQL Admin API to fetch product, order, or customer data.
Internationalization: Display translated content in the merchant's preferred language.
Admin navigation: Navigate programmatically to other admin pages or resource details.
Intent handling: Handle navigation requests from other extensions to open your action modals.

Anchor to PropertiesProperties

The Standard API object provides core properties available to all extension targets. Access the following properties on the API object to identify your extension target, authenticate with your app backend, query the GraphQL Admin API, translate content, and handle intents from other extensions.

Anchor to auth auth required: Provides methods for authenticating calls to your app backend. Use the idToken() method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
Anchor to extension extension { target: ; } required: The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
Anchor to i18n i18n required: Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
Anchor to intents intents required: Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
Anchor to query query < = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<, "2023-04">; }) => Promise<{ data?: ; errors?: []; }> required: Executes GraphQL queries against the GraphQL Admin API. Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.

Auth

The `Auth` object provides authentication methods for secure communication with your app backend.

idToken
Retrieves a [Shopify OpenID Connect ID token](/docs/api/app-home/apis/id-token) for the current user. Use this token to authenticate requests to your app backend and verify the user's identity. The token is a signed JWT that contains user information and can be validated using Shopify's public keys. Returns `null` if the token can't be retrieved.
```
() => Promise<string>
```

ExtensionTarget

A string literal union of all valid extension target identifiers. Use this type to specify where your admin UI extension should render, such as `admin.product-details.block.render` for a block on product details pages or `admin.order-details.action.render` for an action on order details pages. The target determines the extension's location, available APIs, and UI components.

keyof ExtensionTargets

ExtensionTargets

admin.abandoned-checkout-details.action.render
An action target that appears in the **More actions** menu on the abandoned checkout details page. Use this to create workflows for cart recovery, customer engagement, or checkout analysis.
```
RenderExtension<
    ActionExtensionApi<'admin.abandoned-checkout-details.action.render'>,
    AllComponents
  >
```
admin.abandoned-checkout-details.action.should-render
A non-rendering target that controls whether the abandoned checkout details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on checkout properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.abandoned-checkout-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.abandoned-checkout-details.block.render
A block target that displays inline content within the abandoned checkout details page. Use this to show cart recovery tools, abandonment analysis, or customer re-engagement options.
```
RenderExtension<
    BlockExtensionApi<'admin.abandoned-checkout-details.block.render'>,
    AllComponents
  >
```
admin.catalog-details.action.render
An action target that appears in the **More actions** menu on the catalog details page. Use this to create workflows for catalog management, market synchronization, or data exports.
```
RenderExtension<
    ActionExtensionApi<'admin.catalog-details.action.render'>,
    AllComponents
  >
```
admin.catalog-details.action.should-render
A non-rendering target that controls whether the catalog details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on catalog properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.catalog-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.catalog-details.block.render
A block target that displays inline content within the catalog details page. Use this to show catalog-specific settings, market information, or synchronization tools.
```
RenderExtension<
    BlockExtensionApi<'admin.catalog-details.block.render'>,
    AllComponents
  >
```
admin.collection-details.action.render
An action target that appears in the **More actions** menu on the collection details page. Use this to create workflows for collection management, product operations, or merchandising tools.
```
RenderExtension<
    ActionExtensionApi<'admin.collection-details.action.render'>,
    AllComponents
  >
```
admin.collection-details.action.should-render
A non-rendering target that controls whether the collection details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on collection properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.collection-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.collection-details.block.render
A block target that displays inline content within the collection details page. Use this to show collection analytics, bulk product operations, or collection-specific tools.
```
RenderExtension<
    BlockExtensionApi<'admin.collection-details.block.render'>,
    AllComponents
  >
```
admin.collection-index.action.render
An action target that appears in the **More actions** menu on the collection index page. Use this to create workflows for collection management, bulk operations, or catalog organization.
```
RenderExtension<
    ActionExtensionApi<'admin.collection-index.action.render'>,
    AllComponents
  >
```
admin.collection-index.action.should-render
A non-rendering target that controls whether the collection index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.collection-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.company-details.action.render
An action target that appears in the **More actions** menu on the company details page. Use this to create workflows for B2B customer management, credit operations, or company data synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.company-details.action.render'>,
    AllComponents
  >
```
admin.company-details.action.should-render
A non-rendering target that controls whether the company details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on company properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.company-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.company-details.block.render
A block target that displays inline content within the company details page. Use this to show B2B customer information, credit limits, or company-specific data.
```
RenderExtension<
    BlockExtensionApi<'admin.company-details.block.render'>,
    AllComponents
  >
```
admin.company-location-details.block.render
A block target that displays inline content within the company location details page. Use this to show location-specific information, shipping preferences, or location management tools.
```
RenderExtension<
    BlockExtensionApi<'admin.company-location-details.block.render'>,
    AllComponents
  >
```
admin.customer-details.action.render
An action target that appears in the **More actions** menu on the customer details page. Use this to create workflows for customer data management, loyalty operations, or CRM integrations.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-details.action.render'>,
    AllComponents
  >
```
admin.customer-details.action.should-render
A non-rendering target that controls whether the customer details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on customer properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customer-details.block.render
A block target that displays inline content within the customer details page. Use this to show customer-specific information, loyalty data, or custom customer actions.
```
RenderExtension<
    BlockExtensionApi<'admin.customer-details.block.render'>,
    AllComponents
  >
```
admin.customer-index.action.render
An action target that appears in the **More actions** menu on the customer index page. Use this to create workflows for customer management, marketing operations, or bulk data processing.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-index.action.render'>,
    AllComponents
  >
```
admin.customer-index.action.should-render
A non-rendering target that controls whether the customer index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customer-index.selection-action.render
A selection action target that appears in the **More actions** menu on the customer index page when multiple customers are selected. Use this to create workflows for bulk customer operations, mass email campaigns, or batch data updates.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-index.selection-action.render'>,
    AllComponents
  >
```
admin.customer-index.selection-action.should-render
A non-rendering target that controls whether the customer index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customer-segment-details.action.render
An action target that appears from the **Use segment** button on the customer segment details page. Use this to create workflows for marketing campaigns, email operations, or segment-based actions.
```
RenderExtension<
    ActionExtensionApi<'admin.customer-segment-details.action.render'>,
    AllComponents
  >
```
admin.customer-segment-details.action.should-render
A non-rendering target that controls whether the customer segment details action appears from the **Use segment** button. Use this to conditionally show or hide your action based on segment properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.customer-segment-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.customers.segmentation-templates.render
A render target that provides [customer segment templates](/docs/apps/build/marketing-analytics/customer-segments/build-a-template-extension) in the [customer segment editor](https://help.shopify.com/manual/customers/customer-segmentation/create-customer-segments). Use this target to provide pre-built segment templates that merchants can use as starting points for creating targeted customer groups based on custom criteria.
```
RenderExtension<
    CustomerSegmentTemplateApi<'admin.customers.segmentation-templates.render'>,
    CustomerSegmentTemplateComponent
  >
```
admin.discount-details.action.render
An action target that appears in the **More actions** menu on the discount details page. Use this to create workflows for discount management, promotion analysis, or discount synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.discount-details.action.render'>,
    AllComponents
  >
```
admin.discount-details.action.should-render
A non-rendering target that controls whether the discount details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on discount properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.discount-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.discount-details.function-settings.render
A function settings target that appears when merchants create or edit a discount powered by your discount function, allowing them to configure function-specific settings. Use this to build custom configuration interfaces for discount function parameters.
```
RenderExtension<
    DiscountFunctionSettingsApi<'admin.discount-details.function-settings.render'>,
    AllComponents
  >
```
admin.discount-index.action.render
An action target that appears in the **More actions** menu on the discount index page. Use this to create workflows for discount management, promotional operations, or bulk discount updates.
```
RenderExtension<
    ActionExtensionApi<'admin.discount-index.action.render'>,
    AllComponents
  >
```
admin.discount-index.action.should-render
A non-rendering target that controls whether the discount index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.discount-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.draft-order-details.action.render
An action target that appears in the **More actions** menu on the draft order details page. Use this to create workflows for draft order processing, custom pricing, or order preparation tools.
```
RenderExtension<
    ActionExtensionApi<'admin.draft-order-details.action.render'>,
    AllComponents
  >
```
admin.draft-order-details.action.should-render
A non-rendering target that controls whether the draft order details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on draft order properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.draft-order-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.draft-order-details.block.render
A block target that displays inline content within the draft order details page. Use this to show custom pricing calculations, special order handling tools, or order-specific information.
```
RenderExtension<
    BlockExtensionApi<'admin.draft-order-details.block.render'>,
    AllComponents
  >
```
admin.draft-order-index.action.render
An action target that appears in the **More actions** menu on the draft order index page. Use this to create workflows for draft order management, bulk operations, or order conversion tools.
```
RenderExtension<
    ActionExtensionApi<'admin.draft-order-index.action.render'>,
    AllComponents
  >
```
admin.draft-order-index.action.should-render
A non-rendering target that controls whether the draft order index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.draft-order-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.draft-order-index.selection-action.render
A selection action target that appears in the **More actions** menu on the draft order index page when multiple draft orders are selected. Use this to create workflows for bulk draft order operations, batch conversions, or mass order processing.
```
RenderExtension<
    ActionExtensionApi<'admin.draft-order-index.selection-action.render'>,
    AllComponents
  >
```
admin.draft-order-index.selection-action.should-render
A non-rendering target that controls whether the draft order index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.draft-order-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.gift-card-details.action.render
An action target that appears in the **More actions** menu on the gift card details page. Use this to create workflows for gift card processing, balance adjustments, or custom gift card operations.
```
RenderExtension<
    ActionExtensionApi<'admin.gift-card-details.action.render'>,
    AllComponents
  >
```
admin.gift-card-details.action.should-render
A non-rendering target that controls whether the gift card details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on gift card properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.gift-card-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.gift-card-details.block.render
A block target that displays inline content within the gift card details page. Use this to show gift card balance tracking, usage history, or custom gift card metadata.
```
RenderExtension<
    BlockExtensionApi<'admin.gift-card-details.block.render'>,
    AllComponents
  >
```
admin.order-details.action.render
An action target that appears in the **More actions** menu on the order details page. Use this to create workflows for order processing, fulfillment operations, or external system integrations.
```
RenderExtension<
    ActionExtensionApi<'admin.order-details.action.render'>,
    AllComponents
  >
```
admin.order-details.action.should-render
A non-rendering target that controls whether the order details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on order properties, fulfillment status, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-details.block.render
A block target that displays inline content within the order details page. Use this to show order-specific information, fulfillment tools, or custom order actions.
```
RenderExtension<
    BlockExtensionApi<'admin.order-details.block.render'>,
    AllComponents
  >
```
admin.order-details.print-action.render
A print action target that appears in the **Print** menu on the order details page. Use this to generate custom documents such as packing slips, shipping labels, or invoices.
```
RenderExtension<
    PrintActionExtensionApi<'admin.order-details.print-action.render'>,
    AllComponents
  >
```
admin.order-details.print-action.should-render
A non-rendering target that controls whether the order details print action appears in the **Print** menu. Use this to conditionally show or hide your print action based on order properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-details.print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-fulfilled-card.action.render
An action target that appears in the actions menu inside the order fulfilled card, visible only on orders fulfilled by your app. Use this to create workflows for fulfillment operations, tracking updates, or post-fulfillment actions.
```
RenderExtension<
    ActionExtensionApi<'admin.order-fulfilled-card.action.render'>,
    AllComponents
  >
```
admin.order-fulfilled-card.action.should-render
A non-rendering target that controls whether the order fulfilled card action appears in the actions menu. Use this to conditionally show or hide your action based on fulfillment properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-fulfilled-card.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-index.action.render
An action target that appears in the **More actions** menu on the order index page. Use this to create workflows for order management, reporting, or fulfillment operations.
```
RenderExtension<
    ActionExtensionApi<'admin.order-index.action.render'>,
    AllComponents
  >
```
admin.order-index.action.should-render
A non-rendering target that controls whether the order index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-index.selection-action.render
A selection action target that appears in the **More actions** menu on the order index page when multiple orders are selected. Use this to create workflows for bulk order operations, batch fulfillment, or mass order processing.
```
RenderExtension<
    ActionExtensionApi<'admin.order-index.selection-action.render'>,
    AllComponents
  >
```
admin.order-index.selection-action.should-render
A non-rendering target that controls whether the order index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.order-index.selection-print-action.render
A print action target that appears in the **Print** menu on the order index page when multiple orders are selected. Use this to generate batch documents such as combined packing slips, shipping manifests, or bulk invoices.
```
RenderExtension<
    PrintActionExtensionApi<'admin.order-index.selection-print-action.render'>,
    AllComponents
  >
```
admin.order-index.selection-print-action.should-render
A non-rendering target that controls whether the order index selection print action appears in the **Print** menu. Use this to conditionally show or hide your bulk print action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.order-index.selection-print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-details.action.render
An action target that appears in the **More actions** menu on the product details page. Use this to create workflows for processing products, syncing data, or integrating with external systems.
```
RenderExtension<
    ActionExtensionApi<'admin.product-details.action.render'>,
    AllComponents
  >
```
admin.product-details.action.should-render
A non-rendering target that controls whether the product details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on product properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-details.block.render
A block target that displays inline content within the product details page. Use this to show product-specific information, tools, or actions directly on the product page.
```
RenderExtension<
    BlockExtensionApi<'admin.product-details.block.render'>,
    AllComponents
  >
```
admin.product-details.configuration.render
A configuration target that renders product configuration settings for [product bundles](/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui) and customizable products on the product details page. Use this to define bundle component selections, customization options, or product configuration rules.
```
RenderExtension<
    ProductDetailsConfigurationApi<'admin.product-details.configuration.render'>,
    AllComponents
  >
```
admin.product-details.print-action.render
A print action target that appears in the **Print** menu on the product details page. Use this to generate custom documents such as product labels, barcode sheets, or specification sheets.
```
RenderExtension<
    PrintActionExtensionApi<'admin.product-details.print-action.render'>,
    AllComponents
  >
```
admin.product-details.print-action.should-render
A non-rendering target that controls whether the product details print action appears in the **Print** menu. Use this to conditionally show or hide your print action based on product properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-details.print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-details.reorder.render
A block target that provides custom reordering functionality on the product details page. Use this to help merchants rearrange product data.
```
RenderExtension<
    BlockExtensionApi<'admin.product-details.reorder.render'>,
    AllComponents
  >
```
admin.product-index.action.render
An action target that appears in the **More actions** menu on the product index page. Use this to create workflows for product management, catalog operations, or inventory synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.product-index.action.render'>,
    AllComponents
  >
```
admin.product-index.action.should-render
A non-rendering target that controls whether the product index action appears in the **More actions** menu. Use this to conditionally show or hide your action based on user permissions, store configuration, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-index.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-index.selection-action.render
A selection action target that appears in the **More actions** menu on the product index page when multiple products are selected. Use this to create workflows for bulk product operations, batch updates, or mass data processing.
```
RenderExtension<
    ActionExtensionApi<'admin.product-index.selection-action.render'>,
    AllComponents
  >
```
admin.product-index.selection-action.should-render
A non-rendering target that controls whether the product index selection action appears in the **More actions** menu. Use this to conditionally show or hide your bulk action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-index.selection-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-index.selection-print-action.render
A print action target that appears in the **Print** menu on the product index page when multiple products are selected. Use this to generate batch documents such as combined product labels, barcode sheets, or catalog pages.
```
RenderExtension<
    PrintActionExtensionApi<'admin.product-index.selection-print-action.render'>,
    AllComponents
  >
```
admin.product-index.selection-print-action.should-render
A non-rendering target that controls whether the product index selection print action appears in the **Print** menu. Use this to conditionally show or hide your bulk print action based on selection criteria, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-index.selection-print-action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-purchase-option.action.render
An action target that appears in the **Purchase Options** card on the product details page when a selling plan group is present. Use this to create workflows for subscription management, selling plan configuration, or purchase option operations.
```
RenderExtension<
    PurchaseOptionsCardConfigurationApi<'admin.product-purchase-option.action.render'>,
    AllComponents
  >
```
admin.product-variant-details.action.render
An action target that appears in the **More actions** menu on the product variant details page. Use this to create workflows for variant management, inventory operations, or data synchronization.
```
RenderExtension<
    ActionExtensionApi<'admin.product-variant-details.action.render'>,
    AllComponents
  >
```
admin.product-variant-details.action.should-render
A non-rendering target that controls whether the product variant details action appears in the **More actions** menu. Use this to conditionally show or hide your action based on variant properties, user permissions, or external data.
```
RunnableExtension<
    ShouldRenderApi<'admin.product-variant-details.action.should-render'>,
    ShouldRenderOutput
  >
```
admin.product-variant-details.block.render
A block target that displays inline content within the product variant details page. Use this to show variant-specific data, inventory tools, or variant configuration options.
```
RenderExtension<
    BlockExtensionApi<'admin.product-variant-details.block.render'>,
    AllComponents
  >
```
admin.product-variant-details.configuration.render
A configuration target that renders product variant configuration settings for [product bundles](/docs/apps/build/product-merchandising/bundles/product-configuration-extension/add-merchant-config-ui) and customizable products on the product variant details page. Use this to define variant-specific bundle components, customization options, or configuration rules.
```
RenderExtension<
    ProductVariantDetailsConfigurationApi<'admin.product-variant-details.configuration.render'>,
    AllComponents
  >
```
admin.product-variant-purchase-option.action.render
An action target that appears in the **Purchase Options** card on the product variant details page when a selling plan group is present. Use this to create workflows for variant-specific subscription management, selling plan configuration, or purchase option operations.
```
RenderExtension<
    PurchaseOptionsCardConfigurationApi<'admin.product-variant-purchase-option.action.render'>,
    AllComponents
  >
```
admin.settings.internal-order-routing-rule.render
A function settings target that renders within order routing settings, allowing merchants to configure order routing rule functions.
```
RenderExtension<
    OrderRoutingRuleApi<'admin.settings.internal-order-routing-rule.render'>,
    AllComponents | OrderRoutingComponents
  >
```
admin.settings.order-routing-rule.render
A function settings target that renders within order routing settings, allowing merchants to configure order routing rule functions. Use this to build custom configuration interfaces for order routing function parameters.
```
RenderExtension<
    OrderRoutingRuleApi<'admin.settings.order-routing-rule.render'>,
    AllComponents
  >
```
admin.settings.validation.render
A function settings target that renders within a validation's add and edit views, allowing merchants to configure validation function settings. Use this to build custom configuration interfaces for validation function parameters and rules.
```
RenderExtension<
    ValidationSettingsApi<'admin.settings.validation.render'>,
    AllComponents
  >
```

Playground

RenderExtension<StandardApi<'Playground'>, AllComponents>

RenderExtension

Defines a render extension that displays UI in the Shopify admin. Your extension receives a connection object with UI components and an API object with extension capabilities. Use this to build extensions that render visual interfaces in various admin contexts.

ActionExtensionApi

The `ActionExtensionApi` object provides methods for action extensions that render in modal overlays. Access the following properties on the `ActionExtensionApi` object to interact with the current context, control the modal, and display picker dialogs.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
close
Closes the extension modal. Use this when your extension completes its task or the merchant wants to exit. Equivalent to clicking the close button in the overlay corner.
```
() => void
```
data
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
picker
Opens a custom [Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

Data

The `Data` object provides access to currently viewed or selected resources in the admin context.

selected
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
```
{ id: string; }[]
```

I18n

Internationalization utilities for formatting and translating content according to the user's locale. Use these methods to display numbers, currency, dates, and translated strings that match the merchant's language and regional preferences.

formatCurrency
Returns a localized currency value formatted according to the user's locale and currency conventions. Use this to display prices, totals, or financial amounts in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. Uses the current user's locale by default.
```
(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string
```
formatDate
Returns a localized date value formatted according to the user's locale and date conventions. Use this to display dates and times in the appropriate format for the merchant's region, such as order dates, timestamps, or schedule information. This function behaves like the standard `Intl.DateTimeFormat()` and uses the current user's locale by default. Formatting options can be passed to customize the date display style.
```
(date: Date, options?: { inExtensionLocale?: boolean; } & DateTimeFormatOptions) => string
```
formatNumber
Returns a localized number formatted according to the user's locale. Use this to display numbers like quantities, percentages, or measurements in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `decimal` applied. Uses the current user's locale by default.
```
(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string
```
translate
Returns translated content in the user's locale, as supported by the extension. Use this to display localized strings from your extension's locale files. The special `options.count` property enables pluralization. Other option keys and values are treated as replacements for interpolation in your translation strings. Returns a single string when replacements are primitives, or an array when replacements contain UI components.
```
I18nTranslate
```

I18nTranslate

The translation function signature for internationalization. Use this to translate string keys defined in your locale files into localized content for the current user's language.

Intents

Information provided to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.

launchUrl
The URL that was used to launch the intent. Use this to understand how your extension was invoked or to pass context between extensions.
```
string | URL
```

PickerApi

The `picker` function opens a custom selection dialog with your app-specific data. It accepts configuration options to define the picker's heading, items, headers, and selection behavior. It returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.

options
```
PickerOptions
```

returns

Promise<Picker>

PickerOptions

The configuration options for the custom picker dialog. Define the picker's appearance, selection behavior, and data structure.

headers
The column headers for the picker table. Define headers to label and organize the data columns displayed for each item. The header order determines the column layout.
```
Header[]
```
heading
The heading displayed at the top of the picker modal. Use a clear, descriptive title that tells merchants what they're selecting.
```
string
```
items
The list of items that merchants can select from. Each item appears as a row in the picker table.
```
Item[]
```
multiple
The selection mode for the picker. Pass `true` to allow unlimited selections, `false` for single-item selection only, or a number to set a maximum selection limit (for example, `3` allows up to three items).
```
boolean | number
```

Header

The configuration for a table column header in the picker. Each header creates a labeled column that displays corresponding data from items.

content
The label text displayed at the top of the table column. Use clear, concise labels that describe the data in that column (for example, "Price", "Status", "Last Updated").
```
string
```
type
The data type that controls column formatting and text alignment. Use `'number'` for currency, prices, or numeric values (displays right-aligned), or `'string'` for text content (displays left-aligned).
```
'string' | 'number'
```

Item

An individual item that merchants can select in the picker. Each item appears as a row in the picker table.

badges
Status or context badges displayed next to the heading in the first column. Use badges to highlight item state, completion status, or other important attributes (for example, "Draft", "Published", "Incomplete").
```
Badge[]
```
data
Additional data displayed in subsequent columns after the heading. Each value appears in its own column, and the order must match the `headers` array. For example, if headers are `["Price", "Status"]`, then data would be `[19.99, "Active"]`.
```
DataPoint[]
```
disabled
Whether the item can be selected. When `true`, the item is disabled and can't be selected. Disabled items appear grayed out and merchants can't choose them. Use this for items that are unavailable or don't meet selection criteria.
```
boolean
```
heading
The primary text displayed in the first column. This is typically the item's name or title and is the most prominent text in the row.
```
string
```
id
The unique identifier for this item. This ID is returned in the selection array when the merchant selects this item. Use an ID that helps you identify the item in your system (for example, template IDs, review IDs, or custom option keys).
```
string
```
selected
Whether the item is preselected when the picker opens. When `true`, the item appears selected by default. Merchants can still deselect preselected items. Use this to show current selections or suggest default choices.
```
boolean
```
thumbnail
A small preview image or icon displayed at the start of the row. Thumbnails help merchants visually identify items at a glance. Provide a URL to the image file.
```
{ url: string; }
```

Badge

A badge displayed next to an item in the picker to show status or progress. Use badges to highlight important item attributes or states that affect selection decisions.

content
The text content of the badge. Keep this short and descriptive (for example, "Draft", "Active", "Incomplete").
```
string
```
progress
The progress indicator for the badge. Use this to show completion status for items that have progress states.
```
Progress
```
tone
The visual tone indicating status or importance. Choose a tone that matches the badge's meaning.
```
Tone
```

Progress

The progress state for picker badges showing completion status. Use this to indicate how complete an item is: `'incomplete'` for not started, `'partiallyComplete'` for in progress, or `'complete'` for finished.

'incomplete' | 'partiallyComplete' | 'complete'

Tone

The tone communicates the intent or status of a message to the user. - `info`: Neutral informational content with no implied urgency. - `success`: Indicates a successful action or a positive state. - `warning`: Indicates something that requires the user's attention but isn't blocking. - `critical`: Indicates a serious problem or error that needs immediate action.

'info' | 'success' | 'warning' | 'critical'

DataPoint

A single data point that can appear in a picker table cell. Can be text, a number, or undefined if the cell should be empty.

string | number | undefined

Picker

A handle returned when opening a picker dialog. Use this to access the merchant's selection after they confirm or cancel the picker.

selected
A Promise that resolves with an array of selected item IDs when the merchant presses the **Select** button, or `undefined` if they cancel. Await this Promise to handle the selection result.
```
Promise<string[] | undefined>
```

ApiVersion

The supported GraphQL Admin API versions. Use this to specify which API version your GraphQL queries should execute against. Each version includes specific features, bug fixes, and breaking changes. The `unstable` version provides access to the latest features, and can change without notice because it's not subject to versioning guarantees.

'2023-04' | '2023-07' | '2023-10' | '2024-01' | '2024-04' | '2024-07' | '2024-10' | '2025-01' | '2025-04' | 'unstable'

GraphQLError

The GraphQL error returned by the [GraphQL Admin API](/docs/api/admin-graphql).

locations
The location in the GraphQL query where the error occurred. Provides the line number and column position to help identify the exact source of the error in your query string.
```
{ line: number; column: string; }
```
message
A human-readable error message describing what went wrong with the GraphQL query. Use this to understand the cause of the error and how to fix your query.
```
string
```

ResourcePickerApi

Opens the resource picker modal for selecting products, variants, or collections. Returns a Promise that resolves to the selected resources when the merchant confirms, or `undefined` if they cancel. The returned selection includes full resource data with properties like title, price, images, and IDs.

options
```
ResourcePickerOptions
```

returns

Promise<SelectPayload<ResourcePickerOptions['type']> | undefined>

ResourcePickerOptions

The `ResourcePickerOptions` object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items. Access the following properties on the `ResourcePickerOptions` object to configure the resource picker's appearance and functionality.

action
The action verb that appears in the picker's title and primary button. Use `'add'` for actions that add new items (for example, "Add products") or `'select'` for choosing existing items (for example, "Select products"). This helps merchants understand the picker's purpose.
```
'add' | 'select'
```
filter
Filtering options that control which resources appear in the picker. Use filters to restrict resources by publication status, include or exclude variants, or apply custom search criteria. This helps merchants find relevant items faster.
```
Filters
```
multiple
The selection mode for the picker. Pass `true` to allow unlimited selections, `false` for single-item selection only, or a number to set a maximum selection limit (for example, `5` allows up to five items). When `type` is `'product'`, merchants can still select multiple variants from a single product even if `multiple` is `false`.
```
boolean | number
```
query
An initial search query that appears in the picker's search bar when it opens. Merchants can see and edit this query. See [search syntax](/docs/api/usage/search-syntax) for the query format. For most use cases, use `filter.query` instead, which filters results without exposing the query to merchants.
```
string
```
selectionIds
Resources that should be preselected when the picker opens. Pass an array of resource objects with IDs (and optional variant IDs) to show which items are already selected. Merchants can deselect these preselected items. Use this to show current selections or default choices.
```
BaseResource[]
```
type
The type of Shopify resource to select: `'product'` for products, `'variant'` for specific product variants, or `'collection'` for collections. This determines what appears in the picker and what data structure is returned.
```
'product' | 'variant' | 'collection'
```

Filters

Filter options that control which resources appear in the resource picker. Use filters to restrict the available resources based on publication status, resource type, or custom search criteria.

archived
Whether to include archived products in the picker. When `false`, archived products are hidden. When `undefined`, archived products appear with an archived badge. Only applies when `type` is `'product'`. Use this to prevent selecting discontinued products.
```
boolean | undefined
```
draft
Whether to include draft products in the picker. When `false`, draft products are hidden. When `undefined`, draft products appear with a draft badge. Only applies when `type` is `'product'`. Use this to prevent selecting products that aren't ready for use.
```
boolean | undefined
```
hidden
Whether to include products that aren't published on any sales channels. When `false`, only products published to at least one sales channel appear in the picker. Use this to ensure merchants only select products that customers can purchase.
```
boolean
```
query
A GraphQL search query that filters the available resources without showing the query in the picker's search bar. Merchants won't see or edit this filter. See [search syntax](/docs/api/usage/search-syntax) for the query format. Use this to programmatically restrict resources based on attributes like tags, vendor, or product type (for example, `"tag:featured"` or `"vendor:Acme"`).
```
string
```
variants
Whether to show product variants in the picker. When `false`, merchants can only select products, not individual variants. Only applies when `type` is `'product'`. Use this to simplify selection when you only need product-level data.
```
boolean
```

BaseResource

A resource that can have associated variants. Products and collections extend this interface.

id
The resource's unique global identifier (GID) in GraphQL format (for example, `'gid://shopify/Product/1'`). Use this to reference the resource in GraphQL queries.
```
string
```
variants
An array of variant resources associated with this resource. Use this for products that have multiple variants with different options.
```
Resource[]
```

Resource

A base resource with a unique identifier. All Shopify resources extend from this interface.

id
The resource's unique global identifier (GID) in GraphQL format (for example, `'gid://shopify/Product/1'`). Use this to reference the resource in GraphQL queries.
```
string
```

SelectPayload

The payload returned when resources are selected from the picker.

SelectPayload<Type>

AllComponents

The set of UI components available for all admin UI extension targets. This includes all standard Polaris components except for specialized components used in specific contexts. Use this type to define which components can be rendered in your extension.

any

RunnableExtension

Defines a runnable extension that executes logic and returns data without rendering UI. Your extension receives an API object with extension capabilities and returns a result. Use this for extensions that perform data operations, validation checks, or conditional logic like should-render targets.

ShouldRenderApi

The `ShouldRenderApi` object provides methods for controlling action extension visibility. Access the following properties on the `ShouldRenderApi` object to determine whether an associated action should appear based on the current context.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
An array of currently viewed or selected resource identifiers. Use this data to determine whether the action extension should appear based on the current context.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

ShouldRenderOutput

The output returned by `should-render` extension targets to control action visibility. Return `{display: true}` to show the action or `{display: false}` to hide it based on your conditional logic.

display
Whether to display the associated action extension. Set to `true` to show the action, `false` to hide it.
```
boolean
```

BlockExtensionApi

The `BlockExtensionApi` object provides methods for block extensions that render inline content on admin pages. Access the following properties on the `BlockExtensionApi` object to interact with the current context, navigate to other extensions, and display picker dialogs.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

Navigation

The `Navigation` object provides methods for navigating between extensions and admin pages.

navigate
Navigates to a specific extension or admin route. Currently supports navigating from a block extension to an action extension on the same resource page.
```
(url: string | URL) => void
```

CustomerSegmentTemplateApi

The `CustomerSegmentTemplateApi` object provides methods for creating customer segment templates. Access the following properties on the `CustomerSegmentTemplateApi` object to build templates with translated content.

__enabledFeatures
```
string[]
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating template content into the merchant's language.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

CustomerSegmentTemplateComponent

The specialized set of components available for customer segment template extensions. This includes only the CustomerSegmentTemplate component used for defining segment query templates in the customer segmentation editor.

any

DiscountFunctionSettingsApi

The `DiscountFunctionSettingsApi` object provides methods for configuring discount functions. Access the following properties on the `DiscountFunctionSettingsApi` object to manage function settings and metafields.

applyMetafieldChange
Updates or removes [metafields](/docs/apps/build/metafields) that store discount function configuration. Use this to save merchant settings for your discount function.
```
ApplyMetafieldChange
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
The discount being configured and its associated [metafields](/docs/apps/build/metafields) storing function settings.
```
DiscountFunctionSettingsData
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

ApplyMetafieldChange

A function that applies metafield changes to discount function settings. Call this function with an update or removal operation, then await the Promise to receive a result indicating success or failure. Use the result to provide feedback or handle errors in your settings interface.

change
```
MetafieldChange
```

returns

Promise<MetafieldChangeResult>

MetafieldChange

A metafield change operation that can either update or remove a metafield. Pass this to `applyMetafieldChange` to modify discount settings stored in metafields.

MetafieldUpdateChange | MetafieldRemoveChange

MetafieldUpdateChange

A metafield update or creation operation. Use this to set or modify metafield values that store discount function configuration data.

key
The unique key identifying the metafield within its namespace. Use descriptive keys that indicate the setting's purpose (for example, `'min_purchase_amount'` or `'eligible_customer_tags'`).
```
string
```
namespace
The namespace that organizes related metafields. When omitted, a default namespace is assigned. Use consistent namespaces to group related settings.
```
string
```
type
Identifies this as an update operation. Always set to `'updateMetafield'` for updates.
```
'updateMetafield'
```
value
The metafield value to store. Can be a string or number depending on your configuration needs.
```
string | number
```
valueType
The [data type](/docs/apps/build/metafields/list-of-data-types) that defines how the value is formatted and validated. When omitted, preserves the existing type for updates or uses a default for new metafields. Choose a type that matches your value format.
```
SupportedDefinitionType
```

SupportedDefinitionType

The supported [metafield definition types](/docs/apps/build/metafields/list-of-data-types) for storing extension configuration data. Use these types to specify how metafield values should be formatted, validated, and displayed. Types prefixed with `list.` store arrays of values, while other types store single values. Choose a type that matches your data format (for example, use `'number_integer'` for whole numbers, `'single_line_text_field'` for short text, or `'json'` for complex structured data).

'boolean' | 'collection_reference' | 'color' | 'date' | 'date_time' | 'dimension' | 'file_reference' | 'json' | 'metaobject_reference' | 'mixed_reference' | 'money' | 'multi_line_text_field' | 'number_decimal' | 'number_integer' | 'page_reference' | 'product_reference' | 'rating' | 'rich_text_field' | 'single_line_text_field' | 'product_taxonomy_value_reference' | 'url' | 'variant_reference' | 'volume' | 'weight' | 'list.collection_reference' | 'list.color' | 'list.date' | 'list.date_time' | 'list.dimension' | 'list.file_reference' | 'list.metaobject_reference' | 'list.mixed_reference' | 'list.number_decimal' | 'list.number_integer' | 'list.page_reference' | 'list.product_reference' | 'list.rating' | 'list.single_line_text_field' | 'list.url' | 'list.variant_reference' | 'list.volume' | 'list.weight'

MetafieldRemoveChange

A metafield removal operation. Use this to delete metafields that are no longer needed for your discount configuration.

key
The unique key of the metafield to remove. Must match the key used when the metafield was created.
```
string
```
namespace
The namespace containing the metafield to remove. Required to ensure the correct metafield is targeted, as the same key can exist in different namespaces.
```
string
```
type
Identifies this as a removal operation. Always set to `'removeMetafield'` for deletions.
```
'removeMetafield'
```

MetafieldChangeResult

The result returned after attempting to change a metafield. Check the `type` property to determine if the operation succeeded (`'success'`) or failed (`'error'`), then handle the result appropriately in your extension.

MetafieldChangeSuccess | MetafieldChangeResultError

MetafieldChangeSuccess

A successful metafield change operation result. The metafield was updated or removed as requested and the changes are now saved.

type
Indicates the operation succeeded. When this value is `'success'`, the metafield change was applied successfully.
```
'success'
```

MetafieldChangeResultError

A failed metafield change operation result. Use the error message to understand what went wrong and fix the issue, such as validation errors, permission problems, or invalid metafield types.

message
A human-readable error message explaining why the operation failed. Use this to debug issues or display feedback to merchants.
```
string
```
type
Indicates the operation failed. Check this value to determine if you need to handle an error.
```
'error'
```

DiscountFunctionSettingsData

The `data` object exposed to discount function settings extensions in the `admin.discount-details.function-settings.render` target. Use this to access the current discount configuration and populate your settings interface with existing values.

id
The discount being configured by the merchant. Use this ID to associate configuration changes with the correct discount.
```
Discount
```
metafields
An array of [metafields](/docs/apps/build/metafields) that store the discount function's configuration values. Use these metafields to populate your settings UI with the current discount configuration and display existing settings to merchants.
```
Metafield[]
```

Discount

A discount that is being configured by the merchant. Use this to access the discount's unique identifier when saving configuration changes or making GraphQL queries.

id
The discount's unique global identifier (GID) in the [GraphQL Admin API](/docs/api/admin-graphql) format (for example, `gid://shopify/DiscountAutomaticApp/123`). Use this ID to associate settings with the correct discount or query discount data.
```
string
```

Metafield

A [metafield](/docs/apps/build/metafields) that stores discount function configuration data. Use metafields to persist settings that control how your discount function behaves, such as discount thresholds, eligibility rules, or custom discount logic parameters.

description
A human-readable description explaining the metafield's purpose and how it affects discount behavior. Use this to document your settings for other developers.
```
string
```
id
The unique global identifier (GID) for this metafield. Use this ID to reference the metafield in GraphQL queries or updates.
```
string
```
key
The unique key identifying this metafield within its namespace. This key determines how you access the metafield value (for example, `'min_purchase_amount'` or `'eligible_customer_tags'`).
```
string
```
namespace
The namespace that organizes related metafields together. All metafields for a discount should use a consistent namespace to group related settings.
```
string
```
type
The metafield [definition type](/docs/apps/build/metafields/list-of-data-types) that specifies the value format and validation rules. Use this to determine how to parse and display the value.
```
string
```
value
The metafield value stored as a string. Parse this value according to the metafield type to use it in your settings UI.
```
string
```

PrintActionExtensionApi

The `PrintActionExtensionApi` object provides methods for print action extensions that generate custom printable documents. Access the following properties on the `PrintActionExtensionApi` object to access selected resources and display picker dialogs for print configuration.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
An array of currently viewed or selected resource identifiers. Use this to access the IDs of items to include in the print document, such as selected orders or products.
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose print settings or document configurations.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose additional resources to include in the print document.
```
ResourcePickerApi
```

ProductDetailsConfigurationApi

The `ProductDetailsConfigurationApi` object provides methods for configuring product bundles and relationships. Access the following properties on the `ProductDetailsConfigurationApi` object to build product configuration interfaces.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
Product configuration data including the current product, selected items, and app URLs. Use this to access the product being configured and build your configuration interface.
```
Data & { product: Product; app: { launchUrl: string; applicationUrl: string; }; }
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

Product

A product configuration.

handle
The URL-friendly unique identifier used in product URLs (for example, `'blue-t-shirt'`).
```
string
```
hasOnlyDefaultVariant
Whether the product has only the default variant with no custom options. When `true`, the product has no size, color, or other option variations.
```
boolean
```
id
The product's unique global identifier (GID).
```
string
```
onlineStoreUrl
The URL to view this product on the online store. Use this to create "View in store" links.
```
string
```
options
Product options that define how variants differ (for example, Size, Color, Material). Each option has an ID, name, position, and array of possible values.
```
{ id: string; name: string; position: number; values: string[]; }[]
```
productCategory
The standardized product category taxonomy. Use this for product classification in search and organization.
```
string
```
productComponents
An array of component products that make up this bundle. Each component represents a product included in the bundle configuration.
```
ProductComponent[]
```
productType
The product category or type used for organization (for example, "T-Shirt", "Shoes").
```
string
```
status
The publication status indicating whether the product is active (published), archived (discontinued), or draft (unpublished).
```
'ACTIVE' | 'ARCHIVED' | 'DRAFT'
```
title
The product's display name shown to merchants and customers.
```
string
```
totalInventory
The total available inventory summed across all variants and locations.
```
number
```
totalVariants
The total number of variants this product has.
```
number
```

ProductComponent

A component product that is part of a bundle. Represents an individual product included in a bundle configuration.

componentVariantsCount
The count of variants from this product that are used as bundle components. Use this to understand how many variants are configured in bundles.
```
number
```
featuredImage
The featured image displayed for this component product with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces.
```
{
    id?: string | null;
    url?: string | null;
    altText?: string | null;
  } | null
```
id
The component product's unique global identifier (GID).
```
string
```
nonComponentVariantsCount
The count of variants from this product that aren't used in any bundles. Use this to identify available variants for adding to bundle configurations.
```
number
```
productUrl
The admin URL for this component product. Use this to create links to the product's details page in the admin.
```
string
```
title
The product's display name. Use this to show which product is included in the bundle.
```
string
```
totalVariants
The total number of variants this component product has. Use this to determine if variant selection is needed for this component.
```
number
```

PurchaseOptionsCardConfigurationApi

The `PurchaseOptionsCardConfigurationApi` object provides methods for action extensions that interact with purchase options and selling plans. Access the following properties on the `PurchaseOptionsCardConfigurationApi` object to work with selected products and their associated subscription configurations.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
close
Closes the extension modal. Use this when your extension completes its task or the merchant wants to exit. Equivalent to clicking the close button in the overlay corner.
```
() => void
```
data
Selected purchase option data including product and selling plan identifiers.
```
{ selected: { id: string; sellingPlanId?: string; }[]; }
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
picker
Opens a custom [Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

ProductVariantDetailsConfigurationApi

The `ProductVariantDetailsConfigurationApi` object provides methods for configuring product variant bundles and relationships. Access the following properties on the `ProductVariantDetailsConfigurationApi` object to build variant configuration interfaces.

auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
Variant configuration data including the current variant, selected items, and app URLs. Use this to access the variant being configured and build your configuration interface.
```
Data & { variant: ProductVariant; app: { launchUrl: string; applicationUrl: string; }; }
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
navigation
Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
```
Navigation
```
picker
Opens a custom [Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
```
PickerApi
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```
resourcePicker
Opens the [Resource Picker API](/docs/api/admin-extensions/2025-07/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
```
ResourcePickerApi
```

ProductVariant

A product variant configuration.

barcode
The barcode value for the variant (for example, UPC, ISBN, or other barcode standards).
```
string
```
compareAtPrice
The compare-at (original) price as a decimal string, shown for sale pricing (for example, `"29.99"`).
```
string
```
displayName
The display name showing variant options (for example, "Blue / M").
```
string
```
id
The variant's unique global identifier (GID).
```
string
```
price
The variant's price as a decimal string (for example, `"19.99"`).
```
string
```
productVariantComponents
An array of component variants that make up this bundle variant. Each component represents a variant included in the bundle configuration.
```
ProductVariantComponent[]
```
selectedOptions
The selected option values that define this variant (for example, `[{name: "Color", value: "Blue"}, {name: "Size", value: "M"}]`).
```
{ name: string; value: string; }[]
```
sku
The stock keeping unit (SKU) identifier for inventory tracking.
```
string
```
taxable
Whether the variant is taxable. When `true`, taxes are calculated for this variant at checkout.
```
boolean
```
taxCode
The tax code used for calculating taxes (for example, HS codes or other jurisdiction-specific codes).
```
string
```
title
The variant's full title including option values (for example, "Blue T-Shirt - Size M").
```
string
```
weight
The variant's weight as a number. Use with weight units to calculate shipping costs.
```
number
```

ProductVariantComponent

A component variant that is part of a bundle variant. Represents an individual variant included in a bundle configuration.

displayName
The display name showing variant options (for example, "Blue / M").
```
string
```
id
The component variant's unique global identifier (GID).
```
string
```
image
The image displayed for this component variant with ID, URL, and alt text properties. Use this for showing component previews in bundle configuration interfaces.
```
{
    id?: string | null;
    url?: string | null;
    altText?: string | null;
  } | null
```
productVariantUrl
The admin URL for this component variant. Use this to create links to the variant's details page in the admin.
```
string
```
selectedOptions
The selected option values that define this component variant (for example, `[{name: "Color", value: "Blue"}, {name: "Size", value: "M"}]`).
```
{ name: string; value: string; }[]
```
sku
The stock keeping unit (SKU) identifier for inventory tracking, or undefined if not set.
```
string
```
title
The variant's full title including product and option values.
```
string
```

OrderRoutingRuleApi

The `OrderRoutingRuleApi` object provides methods for configuring order routing rules. Access the following properties on the `OrderRoutingRuleApi` object to manage rule settings and metafields.

applyMetafieldsChange
Updates or removes [metafields](/docs/apps/build/metafields) that store order routing rule configuration.
```
ApplyMetafieldsChange
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
The order routing rule being configured, including its metadata and associated [metafields](/docs/apps/build/metafields).
```
Data
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

ApplyMetafieldsChange

A function that applies metafield changes to order routing rule settings. Call this function with one or more change operations to update or remove metafields in batch. Use batch operations to apply multiple configuration changes efficiently.

changes
```
MetafieldsChange[]
```

returns

void

MetafieldsChange

One or more metafield change operations to apply to order routing rule settings. Can be a single change or an array of changes for batch operations. Use arrays to apply multiple changes at once.

MetafieldUpdateChange | MetafieldRemoveChange | MetafieldUpdateChange[] | MetafieldRemoveChange[]

ValidationSettingsApi

The `ValidationSettingsApi` object provides methods for configuring cart and checkout validation functions. Access the following properties on the `ValidationSettingsApi` object to manage validation settings and metafields.

applyMetafieldChange
Updates or removes [metafields](/docs/apps/build/metafields) that store validation function configuration. Use this to save merchant settings for your validation function.
```
ApplyMetafieldChange
```
auth
Provides methods for authenticating calls to your app backend. Use the `idToken()` method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.
```
Auth
```
data
The validation being configured and its associated [metafields](/docs/apps/build/metafields) storing function settings.
```
ValidationData
```
extension
The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.
```
{ target: ExtensionTarget; }
```
i18n
Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.
```
I18n
```
intents
Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.
```
Intents
```
query
Executes GraphQL queries against the [GraphQL Admin API](/docs/api/admin-graphql). Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.
```
<Data = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<ApiVersion, "2023-04">; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>
```

ValidationData

The `data` object exposed to validation settings extensions in the `admin.settings.validation.render` target. Use this to access the current validation configuration and populate your settings interface with existing values.

shopifyFunction
The [Shopify Function](/docs/apps/build/functions) that implements the validation logic. Use this ID to associate configuration changes with the correct function.
```
ShopifyFunction
```
validation
The validation configuration containing the validation ID and metafields. Present when editing an existing validation, absent when creating a new validation. Use the presence of this value to determine if you're in create or edit mode.
```
Validation
```

ShopifyFunction

A [Shopify Function](/docs/apps/build/functions) that implements cart and checkout validation logic. This identifies which function the settings interface is configuring.

id
The [Shopify Function's](/docs/apps/build/functions) unique global identifier (GID). Use this ID to associate settings changes with the correct function.
```
string
```

Validation

A validation configuration that exists and is active in the shop. Use this object to access the validation's current settings and metafields when merchants edit an existing validation.

id
The validation's unique global identifier (GID). Use this ID to reference the validation in GraphQL operations or when saving updated settings.
```
string
```
metafields
An array of [metafields](/docs/apps/build/metafields) that store the validation's configuration values. Use these metafields to populate your settings UI with the current validation configuration.
```
Metafield[]
```

Examples

import React, {useState} from 'react';

import {

reactExtension,

useApi,

Button,

Text,

} from '@shopify/ui-extensions-react/admin';

const AuthenticateBackendRequest = () => {

const {auth} = useApi<'admin.product-details.block.render'>();

const [products, setProducts] = useState<any[]>([]);

const [loading, setLoading] = useState(false);

const handleFetch = async () => {

setLoading(true);

const token = await auth.idToken();

const response = await fetch('https://my-app.com/api/products', {

method: 'GET',

headers: {

'Authorization': `Bearer ${token}`,

'Content-Type': 'application/json',

});

const data = await response.json();

setProducts(data);

setLoading(false);

};

return (

<Button

title={loading ? 'Loading...' : 'Fetch from Backend'}

onPress={handleFetch}

disabled={loading}

{products.length > 0 && <Text>{products.length} products loaded</Text>}

</>

);

};

export default reactExtension(

'admin.product-details.block.render',

() => <AuthenticateBackendRequest />,

);

Examples

Authenticate backend requests

Description

Retrieve an authentication token and use it to fetch data from your app backend. This example gets the ID token, adds it to request headers, and displays loading states while fetching.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  Button,
  Text,
} from '@shopify/ui-extensions-react/admin';

const AuthenticateBackendRequest = () => {
  const {auth} = useApi<'admin.product-details.block.render'>();
  const [products, setProducts] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);

  const handleFetch = async () => {
    setLoading(true);

    const token = await auth.idToken();

    const response = await fetch('https://my-app.com/api/products', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
    });

    const data = await response.json();
    setProducts(data);
    setLoading(false);
  };

  return (
    <>
      <Button
        title={loading ? 'Loading...' : 'Fetch from Backend'}
        onPress={handleFetch}
        disabled={loading}
      />
      {products.length > 0 && <Text>{products.length} products loaded</Text>}
    </>
  );
};

export default reactExtension(
  'admin.product-details.block.render',
  () => <AuthenticateBackendRequest />,
);

TS

import {extension, Button, Text} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root, api) => {
    const {auth} = api;

    let productsText;
    let loadingState = false;

    const button = root.createComponent(Button, {
      title: 'Fetch from Backend',
      onPress: async () => {
        if (loadingState) return;
        
        loadingState = true;
        button.updateProps({title: 'Loading...', disabled: true});

        const token = await auth.idToken();

        const response = await fetch('https://my-app.com/api/products', {
          method: 'GET',
          headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json',
          },
        });

        const data = await response.json();
        
        if (productsText) {
          root.removeChild(productsText);
        }
        
        productsText = root.createComponent(
          Text,
          {},
          `${data.length} products loaded`,
        );
        root.appendChild(productsText);
        
        loadingState = false;
        button.updateProps({title: 'Fetch from Backend', disabled: false});
      },
    });

    root.appendChild(button);
  },
);

Query and mutate product data

Description

Query products using the [GraphQL Admin API](/docs/api/admin-graphql/), then update the first product with new tags. This example demonstrates chaining a query and mutation, handling the response data, and showing success feedback.

React

import React, {useState} from 'react';
import {
  reactExtension,
  useApi,
  Button,
  Text,
  BlockStack,
} from '@shopify/ui-extensions-react/admin';

const QueryAndMutate = () => {
  const {query} = useApi<'admin.product-details.block.render'>();
  const [products, setProducts] = useState<any[]>([]);
  const [updated, setUpdated] = useState(false);

  const handleQuery = async () => {
    const {data: productsData} = await query(
      `query GetProducts {
        products(first: 10) {
          edges {
            node {
              id
              title
              totalInventory
            }
          }
        }
      }`,
    );

    setProducts(productsData.products.edges);
  };

  const handleUpdate = async () => {
    const productId = products[0]?.node.id;

    if (!productId) return;

    const {data: updateData} = await query(
      `mutation UpdateProduct($id: ID!, $input: ProductInput!) {
        productUpdate(id: $id, product: $input) {
          product {
            id
            tags
          }
          userErrors {
            field
            message
          }
        }
      }`,
      {
        variables: {
          id: productId,
          input: {tags: ['processed', 'reviewed']},
        },
      },
    );

    if (updateData.productUpdate.product) {
      setUpdated(true);
    }
  };

  return (
    <BlockStack>
      <Button title="Query Products" onPress={handleQuery} />
      {products.length > 0 && (
        <>
          <Text>{products.length} products found</Text>
          <Button title="Update First Product" onPress={handleUpdate} />
        </>
      )}
      {updated && <Text>Product tags updated!</Text>}
    </BlockStack>
  );
};

export default reactExtension(
  'admin.product-details.block.render',
  () => <QueryAndMutate />,
);

TS

import {extension, Button, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root, api) => {
    const {query} = api;

    let products = [];
    let productsText;
    let updateButton;
    let updatedText;

    const stack = root.createComponent(BlockStack);

    const queryButton = root.createComponent(Button, {
      title: 'Query Products',
      onPress: async () => {
        const {data: productsData} = await query(
          `query GetProducts {
            products(first: 10) {
              edges {
                node {
                  id
                  title
                  totalInventory
                }
              }
            }
          }`,
        );

        products = productsData.products.edges;

        if (productsText) {
          stack.removeChild(productsText);
        }
        
        productsText = root.createComponent(
          Text,
          {},
          `${products.length} products found`,
        );
        stack.appendChild(productsText);

        if (!updateButton && products.length > 0) {
          updateButton = root.createComponent(Button, {
            title: 'Update First Product',
            onPress: handleUpdate,
          });
          stack.appendChild(updateButton);
        }
      },
    });

    const handleUpdate = async () => {
      const productId = products[0]?.node.id;
      if (!productId) return;

      const {data: updateData} = await query(
        `mutation UpdateProduct($id: ID!, $input: ProductInput!) {
          productUpdate(id: $id, product: $input) {
            product {
              id
              tags
            }
            userErrors {
              field
              message
            }
          }
        }`,
        {
          variables: {
            id: productId,
            input: {tags: ['processed', 'reviewed']},
          },
        },
      );

      if (updateData.productUpdate.product) {
        if (updatedText) {
          stack.removeChild(updatedText);
        }
        updatedText = root.createComponent(Text, {}, 'Product tags updated!');
        stack.appendChild(updatedText);
      }
    };

    stack.appendChild(queryButton);
    root.appendChild(stack);
  },
);

Persist settings

Description

Save and retrieve user preferences from browser storage. This example loads saved preferences on mount, displays current values, and lets merchants update settings that persist across sessions.

React

import React, {useState, useEffect} from 'react';
import {
  reactExtension,
  useApi,
  Button,
  Text,
  BlockStack,
} from '@shopify/ui-extensions-react/admin';

const PersistSettings = () => {
  const {storage} = useApi<'admin.product-details.block.render'>();
  const [preferences, setPreferences] = useState<any>(null);

  useEffect(() => {
    const loadPreferences = async () => {
      const prefs = await storage.get('userPreferences');
      setPreferences(prefs);
    };

    loadPreferences();
  }, [storage]);

  const handleSave = async () => {
    await storage.set('userPreferences', {
      theme: 'dark',
      notifications: true,
      defaultView: 'grid',
    });

    const updated = await storage.get('userPreferences');
    setPreferences(updated);
  };

  return (
    <BlockStack>
      <Button title="Save Preferences" onPress={handleSave} />
      {preferences && (
        <BlockStack>
          <Text>Theme: {preferences.theme}</Text>
          <Text>Notifications: {String(preferences.notifications)}</Text>
          <Text>View: {preferences.defaultView}</Text>
        </BlockStack>
      )}
    </BlockStack>
  );
};

export default reactExtension(
  'admin.product-details.block.render',
  () => <PersistSettings />,
);

TS

import {extension, Button, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root, api) => {
    const {storage} = api;

    let preferencesText;
    const stack = root.createComponent(BlockStack);

    const loadPreferences = async () => {
      const prefs = await storage.get('userPreferences');
      
      if (prefs && preferencesText) {
        stack.removeChild(preferencesText);
      }

      if (prefs) {
        preferencesText = root.createComponent(BlockStack);
        const themeText = root.createComponent(Text, {}, `Theme: ${prefs.theme}`);
        const notifText = root.createComponent(Text, {}, `Notifications: ${String(prefs.notifications)}`);
        const viewText = root.createComponent(Text, {}, `View: ${prefs.defaultView}`);
        
        preferencesText.appendChild(themeText);
        preferencesText.appendChild(notifText);
        preferencesText.appendChild(viewText);
        
        stack.appendChild(preferencesText);
      }
    };

    loadPreferences();

    const saveButton = root.createComponent(Button, {
      title: 'Save Preferences',
      onPress: async () => {
        await storage.set('userPreferences', {
          theme: 'dark',
          notifications: true,
          defaultView: 'grid',
        });

        await loadPreferences();
      },
    });

    stack.appendChild(saveButton);
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Handle GraphQL partial data: Check both errors and data in query responses. GraphQL returns partial data with errors when some fields fail but others succeed.
Batch GraphQL queries: Combine multiple queries in a single GraphQL request using aliases to reduce roundtrips and improve performance under rate limits.

Anchor to LimitationsLimitations

GraphQL queries share rate limits with your app's overall Admin API usage and are subject to the shop's installed access scopes.
ID tokens from auth.idToken() are short-lived JWTs. They expire quickly and shouldn't be stored long-term.

Was this page helpful?