Skip to main content
Migrate to Polaris

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

Product Variant Details Configuration API

Requires the AdminBlock component.

The Product Variant Details Configuration API lets you build product configuration extensions for bundles that define variant relationships and manage bundle compositions. Use this API to build configuration interfaces for bundle and component product experiences at the variant level.

Anchor to Use casesUse cases

  • Variant configuration: Configure individual product variant details and relationships.
  • Bundle variants: Set up variant-level bundle configurations for complex products.
  • Variant settings: Manage variant-specific settings and properties.
  • Component selection: Select component products at the variant level for bundles.
Support
Targets (1)

Supported targets

Anchor to PropertiesProperties

The Product Variant Details Configuration API object provides access to product variant configuration data. Access the following properties on the API object to interact with the current product variant context, navigate within the admin, and select resources in the admin.product-variant-details.configuration.render target.

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
& { variant: ; app: { launchUrl: string; applicationUrl: string; }; }
required

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.

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 Picker API dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.

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 API modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.

Anchor to Best practicesBest practices

  • Store configuration keyed by variant GID: Save bundle relationships in metafields on the variant or in your app database using the variant GID as the key for precise variant-level configuration.
  • Use type: "variant" in Resource Picker for precision: When selecting component variants, use type: "variant" in the Resource Picker API for precise variant selection rather than product-level selection.
  • Implement cart transforms to enforce bundles: Configuration only defines relationships. Use Shopify Functions cart transforms to enforce variant-level bundling at checkout based on saved configuration.

Anchor to LimitationsLimitations

  • Configuration extensions only render in the admin. They don't affect storefront or checkout behavior. You must implement separate logic for storefront bundle display and checkout enforcement.
  • Bundles aren't enforced automatically. Configuration doesn't automatically create bundles. You must implement cart transforms to enforce bundling when variants are added to cart.
  • Your extension can't directly modify variant properties. The API is read-only for variant data. Use GraphQL mutations like productVariantsBulkUpdate if you need to update variants.
Was this page helpful?