Choose a version:

Discount Function Settings API

Requires the function settings component.

The Discount Function Settings API lets you build UI extensions that provide custom configuration interfaces for discount functions. Use this API to create settings pages for Shopify Functions that implement discount logic.

Anchor to Use casesUse cases

Discount configuration: Build settings interfaces for discount Shopify Functions.
Metafield storage: Store discount function configuration in metafields with proper validation.
Settings UI: Create custom configuration experiences for discount logic and rules.
Function integration: Configure Shopify Functions that implement custom discount behavior.

Support

Targets (1)

Supported targets

admin.discount-details.function-settings.render

Anchor to PropertiesProperties

The shopify global object provides access to discount function configuration and settings. Access the following properties on shopify to interact with the current discount function context in the admin.discount-details.function-settings.render target.

Anchor to applyMetafieldChange applyMetafieldChange required: Updates or removes metafields that store discount function configuration. Use this to save merchant settings for your discount function.
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 data data required: The discount being configured and its associated metafields storing function settings.
Anchor to discounts discounts required: The discounts object provides reactive access to discount configuration, including discount classes and the discount method. Use the signals to read current values and the update functions to modify discount classes in your settings UI. These values automatically update when changed by the merchant or system.
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 navigation navigation required: 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).
Anchor to picker picker required: Opens a custom selection dialog with your app-specific data. Use the Picker API to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a Picker object with a selected property for accessing the merchant's selection.
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.
Anchor to resourcePicker resourcePicker required: Opens the resource picker modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
Anchor to storage storage required: Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.

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'
```

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>
```

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'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
```
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[]
```

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
```

DiscountsApi

The `DiscountsApi` object provides reactive access to discount configuration. Use the signals to read discount classes and method, and the update function to change which parts of the purchase (products, order, or shipping) the discount affects.

discountClasses
A signal that contains the discount classes (Product, Order, or Shipping). Read this to determine where the discount applies in the purchase flow. A discount can apply to multiple classes simultaneously.
```
ReadonlySignalLike<DiscountClass[]>
```
discountMethod
A signal that contains the discount method (`'automatic'` or `'code'`). Read this to determine whether the discount applies automatically at checkout or requires a customer-entered code.
```
ReadonlySignalLike<DiscountMethod>
```
updateDiscountClasses
A function that updates the discount classes to change where the discount applies. Call this function with an array of `DiscountClass` values to set which parts of the purchase (products, order total, or shipping) the discount affects.
```
UpdateSignalFunction<DiscountClass[]>
```

ReadonlySignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern.

subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

DiscountClass

The discount class that determines where the discount applies in the purchase flow. Use this to understand what type of discount the merchant is configuring (product-level, order-level, or shipping).

'product' | 'order' | 'shipping'

DiscountMethod

The method used to apply a discount. Use `'automatic'` for discounts that apply automatically at checkout, or `'code'` for discounts that require a code entered by the customer.

'automatic' | 'code'

UpdateSignalFunction

A function that updates a signal and returns a result indicating success or failure. The function is typically used along with a `ReadonlySignalLike` object.

value
```
T
```

returns

Result<T>

Result

A result type that indicates the success or failure of an operation.

{success: true; value: T} | {success: false; errors: ValidationError[]}

ValidationError

A validation error object that is returned when an operation fails.

code
A code identifier for the error.
```
string
```
issues
Field-level validation issues
```
{ message: string; path: string[]; }[]
```
message
A message describing the error.
```
string
```
type
```
'error'
```

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

Maps extension target identifiers to their corresponding extension types. Each target represents a specific location or context in the Shopify admin where extensions can render or execute. Use these targets to define where your extension appears and what capabilities it has access to.

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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
admin.app.tools.data
A runnable target that enables your app to expose data to [Sidekick](/docs/apps/build/sidekick/build-app-data). Use this target to register tools that Sidekick can invoke to search your app's data and answer merchant questions.
```
RunnableExtension<
    StandardApi<'admin.app.tools.data'>,
    undefined
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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.data
A runnable 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.
```
RunnableExtension<
    CustomerSegmentTemplateApi<'admin.customers.segmentation-templates.data'>,
    {templates: CustomerSegmentTemplate[]}
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    FunctionSettingsComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    PrintActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    PrintActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    PrintActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    PrintActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    BlockExtensionComponents
  >
```
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'>,
    ActionExtensionComponents
  >
```
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'>,
    FunctionSettingsComponents
  >
```
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'>,
    FunctionSettingsComponents
  >
```
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'>,
    FunctionSettingsComponents
  >
```

RenderExtension

Defines the structure of a render extension, which displays UI in the Shopify admin.

api
The API object providing access to extension capabilities, data, and methods. The specific API type depends on the extension target and determines what functionality is available to your extension, such as authentication, storage, data access, and GraphQL querying.
```
Api
```
components
The set of UI components available for rendering your extension. This defines which Polaris components and custom components can be used to build your extension's interface. The available components vary by extension target.
```
ComponentsSet
```
output
The render function output. Your extension's render function should return void or a Promise that resolves to void. Use this to perform any necessary setup, rendering, or async operations when your extension loads.
```
void | Promise<void>
```

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 selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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

The `Intents` object provides methods for launching standardized Shopify workflows to create or edit resources. Intents enable your extension to trigger native admin interfaces for products, customers, discounts, and other resources, then receive the results when merchants complete the workflow.

invoke
Launches an intent workflow for creating or editing Shopify resources. Returns a handle that resolves when the merchant completes, cancels, or encounters an error in the workflow. Use this to initiate resource creation or editing without building custom forms.
```
IntentInvokeApi
```
launchUrl
The URL that launched the current intent workflow, if your extension was opened through an intent. Use this to determine how your extension was invoked and access any parameters passed in the URL.
```
string | URL
```

IntentInvokeApi

The [`invoke` method](/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api#invoke-method) in the Intents API launches a Shopify admin workflow for creating or editing resources, such as products, customers, or discounts. It opens a native admin interface, waits for the merchant to complete the workflow, and returns the result including any created or updated resource data.

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").
```
PickerBadge[]
```
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; }
```

PickerBadge

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 visual tone for picker badges indicating status or importance. Use different tones to communicate urgency or state: `'info'` for neutral information, `'success'` for positive states, `'warning'` for caution, or `'critical'` for urgent issues.

'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 but may change without notice.

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

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 the selected resources when the user confirms their selection, or undefined if they cancel.

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 structure that can optionally include associated variants. Use this type for specifying preselected items in the resource picker when you need to include variant selections.

id
The resource identifier in GraphQL global ID format (for example, `gid://shopify/Product/123`).
```
string
```
variants
An array of variant resources to preselect along with the main resource. Only applicable when the main resource is a product that has variants you want to preselect.
```
Resource[]
```

Resource

The base resource structure with a unique identifier.

id
The resource identifier in GraphQL global ID format (for example, `gid://shopify/Product/123`).
```
string
```

SelectPayload

The payload returned when resources are selected from the picker.

SelectPayload<Type>

Storage

clear
Clears all data from the storage. Use this to reset your extension's storage, such as when implementing a logout flow, clearing cached data, or resetting to defaults. This operation removes all stored key-value pairs.
```
() => Promise<void>
```
delete
Deletes a specific key from the storage. Use this to remove individual data items that are no longer needed, freeing up storage space and maintaining data hygiene.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<boolean>
```
deleteMany
Deletes multiple keys from the storage at once. Use this to efficiently remove several related data items in a single operation, such as clearing expired cache entries or removing a group of related settings.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(keys: Keys[]) => Promise<Record<Keys, boolean>>
```
entries
Gets all the keys and values in the storage. Use this to iterate over all stored data, useful for debugging, data migration, or displaying all stored settings. The returned iterator provides entries as `[key, value]` tuples.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>() => Promise<IterableIterator<[Keys, StorageTypes[Keys]]>>
```
get
Gets the value of a key in the storage. Use this to retrieve previously saved data when your extension loads or when you need to access stored values. The value is automatically deserialized from JSON to its original type.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys) => Promise<StorageTypes[Keys]>
```
getMany
Gets the values of multiple keys in the storage at once. Use this to efficiently retrieve related data in a single operation, reducing overhead when loading multiple stored values. The returned array is in the same order as the provided keys, with `undefined` values for keys that don't exist in storage.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(keys: Keys[]) => Promise<StorageTypes[Keys][]>
```
set
Sets the value of a key in the storage. Use this to save individual data items like user preferences, form state, or cached values. The value is serialized using `JSON.stringify`, so it can be any primitive type, object, or array that JSON supports.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes, Keys extends keyof StorageTypes = keyof StorageTypes>(key: Keys, value: StorageTypes[Keys]) => Promise<void>
```
setMany
Sets multiple key-value pairs in the storage at once. Use this for efficient batch operations when you need to save multiple related values together, such as form data or configuration settings.
```
<StorageTypes extends BaseStorageTypes = BaseStorageTypes>(entries: Partial<StorageTypes>) => Promise<void>
```

ActionExtensionComponents

The components available for building action extensions. Includes all standard components plus the admin action component required for action extension setup.

StandardComponents | 'AdminAction'

StandardComponents

The standard set of UI components available in most admin extensions. These components provide the building blocks for creating extension interfaces including layout elements, form inputs, data display, navigation, and interactive controls. Use these components to build consistent, accessible UIs that match the Shopify admin design system.

'Avatar' | 'Badge' | 'Banner' | 'Box' | 'Button' | 'ButtonGroup' | 'Checkbox' | 'Chip' | 'Choice' | 'ChoiceList' | 'Clickable' | 'ClickableChip' | 'ColorField' | 'ColorPicker' | 'DateField' | 'DatePicker' | 'DropZone' | 'Divider' | 'EmailField' | 'Grid' | 'GridItem' | 'Heading' | 'Icon' | 'Image' | 'Link' | 'ListItem' | 'Menu' | 'MoneyField' | 'NumberField' | 'Option' | 'OptionGroup' | 'OrderedList' | 'Paragraph' | 'PasswordField' | 'QueryContainer' | 'SearchField' | 'Section' | 'Select' | 'Spinner' | 'Stack' | 'Switch' | 'Table' | 'TableBody' | 'TableCell' | 'TableHeader' | 'TableHeaderRow' | 'TableRow' | 'Text' | 'TextArea' | 'TextField' | 'Thumbnail' | 'Tooltip' | 'UnorderedList' | 'URLField'

RunnableExtension

Defines the structure of a runnable extension, which executes logic and returns data without rendering UI.

api
The API object providing access to extension capabilities and methods. The specific API type depends on the extension target and determines what functionality is available to your extension.
```
Api
```
output
The function output. Your extension function should return the expected output type or a Promise that resolves to that type. The output type is determined by your specific extension target and use case.
```
Output | Promise<Output>
```

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[]; }>
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

ShouldRenderOutput

The output returned by `should-render` extensions to control visibility.

display
Whether to display the associated action extension. Return `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 selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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
```

BlockExtensionComponents

The components available for building block extensions. Includes all standard components plus the admin block component required for block extension setup and the form component for creating forms.

StandardComponents | 'AdminBlock' | 'Form'

StandardApi

The `StandardApi` object provides core methods available to all extension targets. Access the following properties on the `StandardApi` object to authenticate users, query the [GraphQL Admin API](/docs/api/admin-graphql), translate content, handle intents, and persist data.

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 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[]; }>
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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[]; }>
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

CustomerSegmentTemplate

Defines a customer segment template that merchants can use to create targeted customer groups.

createdOn
The creation date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Templates created within the last month display a "New" badge.
```
string
```
dependencies
Customer metafields required by this template's query. Declare dependencies so the admin can guide merchants to set up required metafields before using the template.
```
{ standardMetafields?: "facts.birth_date"[]; customMetafields?: string[]; }
```
description
The template description in the merchant's language. Use an array for multiple paragraphs.
```
string | string[]
```
query
The segment query code to display in the template with syntax highlighting. This code is shown to merchants but not validated. Test your queries in the Shopify admin segment editor before including them in templates.
```
string
```
queryToInsert
The segment query code to insert when the merchant selects this template. If omitted, the `query` value is used instead. This code is inserted into the editor but not validated. Test your queries in the Shopify admin segment editor before including them in templates.
```
string
```
title
The template title in the merchant's language.
```
string
```

FunctionSettingsComponents

The components available for building function settings extensions. Includes all form components plus the function settings component required for function settings configuration.

FormExtensionComponents | 'FunctionSettings'

FormExtensionComponents

The components available for building form-based extensions. Includes all standard components plus the form component for creating structured data collection interfaces with submission handling and validation.

StandardComponents | 'Form'

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 selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

PrintActionExtensionComponents

The components available for building print action extensions. Includes all standard components plus the admin print action component required for print action setup.

StandardComponents | 'AdminPrintAction'

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 selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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 selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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
Product 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 selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

ProductVariant

A product variant configuration.

barcode
The barcode, UPC, or ISBN number for the variant.
```
string
```
compareAtPrice
The original price before any discounts or markdowns.
```
string
```
displayName
A human-readable display name that combines the product title with the variant's option values (for example, "T-Shirt - Medium / Blue").
```
string
```
id
The variant's unique global identifier (GID).
```
string
```
price
The current selling price for this variant.
```
string
```
productVariantComponents
An array of component variants that make up this bundle variant. Each component represents a product variant included in the bundle.
```
ProductVariantComponent[]
```
selectedOptions
The option values that define this specific variant with name and value pairs (for example, Size: Large, Color: Blue).
```
{ name: string; value: string; }[]
```
sku
The Stock Keeping Unit (SKU) identifier for inventory tracking.
```
string
```
taxable
Whether this variant is subject to taxes. When `true`, applicable taxes are calculated at checkout.
```
boolean
```
taxCode
The harmonized system (HS) tax code for international shipping and customs.
```
string
```
title
The display name showing only the variant's option values (for example, "Medium / Blue").
```
string
```
weight
The physical weight of the variant as a number.
```
number
```

ProductVariantComponent

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

displayName
A human-readable display name that combines the product title with the variant's option values (for example, "T-Shirt - Medium / Blue").
```
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 product variant. Use this to create links to the variant's details page in the admin.
```
string
```
selectedOptions
The option values that define this specific component variant with name and value pairs (for example, Size: Large, Color: Blue).
```
{ name: string; value: string; }[]
```
sku
The Stock Keeping Unit (SKU) identifier for this component variant.
```
string
```
title
The display name showing only the variant's option values (for example, "Medium / Blue").
```
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
```
picker
Opens a custom selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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
```
picker
Opens a custom selection dialog with your app-specific data. Use the [Picker API](/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api) to define the picker's heading, items, headers, and selection behavior. Returns a Promise that resolves to a `Picker` object with a `selected` property for accessing the merchant's selection.
```
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/latest/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Returns the selected resources when the user confirms their selection, or undefined if they cancel.
```
ResourcePickerApi
```
storage
Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.
```
Storage
```

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

jsx

import {render} from 'preact';

import {useState} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const [threshold, setThreshold] = useState('50.00');

const [saved, setSaved] = useState(false);

const handleSave = async () => {

const result = await shopify.applyMetafieldChange({

type: 'updateMetafield',

namespace: 'discount-config',

key: 'minimum_purchase',

value: threshold,

valueType: 'number_decimal',

});

if (result.type === 'success') {

setSaved(true);

} else {

console.error('Configuration failed:', result.message);

}

};

return (

<s-function-settings>

<s-text-field

label="Minimum purchase amount"

value={threshold}

onChange={(value) => setThreshold(value)}

<s-button onClick={handleSave}>Save Threshold</s-button>

{saved && <s-banner tone="success">Threshold configured!</s-banner>}

</s-function-settings>

);

}

Examples

Description

Save a minimum purchase threshold to a metafield with decimal number validation. This example uses a [text field](/docs/api/admin-extensions/latest/web-components/forms/text-field) for input, calls `applyMetafieldChange`, and displays success or error feedback.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [threshold, setThreshold] = useState('50.00');
  const [saved, setSaved] = useState(false);

  const handleSave = async () => {
    const result = await shopify.applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'discount-config',
      key: 'minimum_purchase',
      value: threshold,
      valueType: 'number_decimal',
    });

    if (result.type === 'success') {
      setSaved(true);
    } else {
      console.error('Configuration failed:', result.message);
    }
  };

  return (
    <s-function-settings>
      <s-text-field
        label="Minimum purchase amount"
        value={threshold}
        onChange={(value) => setThreshold(value)}
      />
      <s-button onClick={handleSave}>Save Threshold</s-button>
      {saved && <s-banner tone="success">Threshold configured!</s-banner>}
    </s-function-settings>
  );
}

Description

Save multiple discount configuration settings in a single operation. This example stores customer tags as JSON and usage limits as an integer, demonstrating how to apply multiple metafield changes sequentially.

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [tags, setTags] = useState('vip, wholesale, premium');
  const [maxUses, setMaxUses] = useState('5');

  const handleSave = async () => {
    await shopify.applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'discount-config',
      key: 'eligible_customer_tags',
      value: JSON.stringify(tags.split(',').map((t) => t.trim())),
      valueType: 'json',
    });

    await shopify.applyMetafieldChange({
      type: 'updateMetafield',
      namespace: 'discount-config',
      key: 'max_uses_per_customer',
      value: maxUses,
      valueType: 'number_integer',
    });
  };

  return (
    <s-function-settings>
      <s-text-field
        label="Eligible customer tags (comma-separated)"
        value={tags}
        onChange={(value) => setTags(value)}
      />
      <s-number-field
        label="Max uses per customer"
        value={maxUses}
        onChange={(value) => setMaxUses(value)}
      />
      <s-button onClick={handleSave}>Save Eligibility Rules</s-button>
    </s-function-settings>
  );
}

Description

Load discount metafields on mount and display current configuration. This example shows reducing metafields into a settings object, checking for missing values, and applying defaults only when needed.

jsx

import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {data} = shopify;
  const [settings, setSettings] = useState({});

  useEffect(() => {
    const initializeSettings = async () => {
      const existingSettings = data.metafields.reduce((acc, field) => {
        acc[field.key] = field.value;
        return acc;
      }, {});

      setSettings(existingSettings);

      if (!existingSettings.eligible_tags) {
        await shopify.applyMetafieldChange({
          type: 'updateMetafield',
          namespace: 'discount-config',
          key: 'eligible_tags',
          value: JSON.stringify(['vip', 'wholesale']),
          valueType: 'json',
        });
      }
    };

    initializeSettings();
  }, [data]);

  return (
    <s-function-settings>
      <s-text>Current settings:</s-text>
      {Object.entries(settings).map(([key, value]) => (
        <s-text key={key}>
          {key}: {String(value)}
        </s-text>
      ))}
    </s-function-settings>
  );
}

Anchor to Best practicesBest practices

Check operation result type: applyMetafieldChange returns { type: 'success' } or { type: 'error', message: string }. Errors don't throw exceptions, so always check the returned type property.

Anchor to LimitationsLimitations

Metafields are subject to size limits. Individual metafield values can't exceed 256KB, and total metafields per resource have storage limits.
The applyMetafieldChange method is sequential. Operations are processed one at a time. Rapid successive calls may lead to race conditions where later updates overwrite earlier ones.
Metafield changes are applied immediately. Unlike some admin forms, metafield changes persist right away without waiting for the merchant to save the discount.

Was this page helpful?