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.

Purchase Options Card Configuration API

Requires the AdminAction component.

The Purchase Options Card Configuration API provides access to purchase option selection data for products with subscription and selling plan configurations. Use this API to build action extensions that interact with selected purchase options on product and product variant details pages.

Anchor to Use casesUse cases

  • Subscription configuration: Configure purchase options card for subscription products.
  • Selling plan UI: Build interfaces for managing selling plan configurations.
  • Purchase options: Customize purchase options displayed on product pages.
  • Card settings: Configure how purchase options cards appear to customers.
Support
Targets (2)

Supported targets

Anchor to PropertiesProperties

The Purchase Options Card Configuration API object provides access to selected purchase option data. Access the following properties on the API object to interact with currently selected products and selling plans in the admin.product-purchase-option.action.render and admin.product-variant-purchase-option.action.render targets.

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 close
close
() => void
required

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.

Anchor to data
data
{ selected: { id: string; sellingPlanId?: string; }[]; }
required

Selected purchase option data including product and selling plan identifiers.

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 picker
picker
required

Opens a custom Picker 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 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

  • Handle operations based on selling plan selection: Items in api.data.selected have an optional sellingPlanId property. When present, perform subscription-specific operations. When absent, treat it as a one-time purchase.

Anchor to LimitationsLimitations

  • The action only appears when selling plan groups exist on the product or variant. The action is hidden for products without subscription options, even if your extension is installed.
  • Items in api.data.selected have an optional sellingPlanId property. When present, the merchant selected a specific selling plan. When absent, they selected the product/variant without a specific plan.
  • Your extension can't modify selling plan configurations. The API is read-only for selling plan data. Use GraphQL mutations to update selling plans if needed.
  • Selection data only includes IDs. You must query GraphQL for full product, variant, and selling plan details like billing policy and pricing adjustments. Selling plan group data is also unavailable. Your extension only receives individual selling plan IDs but not the parent selling plan group structure.
Was this page helpful?