Skip to main content

Product Variant Details Configuration API

Requires the admin block 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 shopify global object provides access to product variant configuration data. Access the following properties on shopify 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

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.

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.

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?