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 upgrade guide to upgrade your extension.

Product variants

Product variant pages display information about individual product variations, including SKU, price, inventory levels, and option values like size or color. Extensions on these pages help merchants manage variant-specific workflows, sync inventory with external systems, and configure purchase options.

Anchor to Use casesUse cases

  • Inventory synchronization: Sync variant inventory levels with external warehouse management systems, 3PLs, or ERP platforms to maintain accurate stock counts across multiple locations and sales channels.
  • Pricing and cost management: Display cost information from suppliers, calculate margins, apply bulk pricing rules, or sync variant prices with external pricing engines and wholesale platforms.
  • Marketplace publishing: Push variant data to external marketplaces like Amazon, eBay, or Google Shopping, including SKU mappings, inventory levels, and marketplace-specific attributes.
  • Subscription and purchase options: Configure variant-specific subscription settings, bundle configurations, or pre-order options through external subscription management platforms.
  • Variant analytics: Display variant-level performance metrics, sales velocity, or demand forecasting data from external analytics platforms to help merchants optimize inventory.
Shopify admin product variant pages showing all available extension target locations.

Anchor to Product variant details targetsProduct variant details targets

Use action and block targets to extend the product variant details page with workflows and contextual information.

Extensions can query and mutate Shopify data using the direct API, or call your app's backend for custom business logic and external integrations.

Anchor to Product variant details action ,[object Object]Product variant details action target

admin.product-variant-details.action.render

Renders an admin action extension on the product variants details page. Merchants can access this extension from the More actions menu. Use this target to provide workflows that operate on product variants data, such as syncing with external systems, exporting product variants information, or managing credit terms.

Extensions at this target can access product variants data through the data property in the Action Extension API. The action renders in a modal overlay, providing space for multi-step workflows, forms, and confirmations.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React from 'react';
import { useState, useEffect } from 'react';
import {
reactExtension,
useApi,
AdminAction,
Banner,
BlockStack,
Box,
Button,
Checkbox,
Divider,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.product-variant-details.action.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const { data, close } = useApi(TARGET);
const [loading, setLoading] = useState(false);
const [success, setSuccess] = useState(false);
const [error, setError] = useState<string | null>(null);
const [warehouseData, setWarehouseData] = useState<any>(null);
const [updateShopify, setUpdateShopify] = useState(true);
const [notifyLowStock, setNotifyLowStock] = useState(false);

const variantId = data.selected[0].id;

useEffect(() => {
fetchWarehouseData();
}, []);

const fetchWarehouseData = async () => {
setLoading(true);
try {
const response = await fetch('https://your-app.com/api/warehouse/inventory', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ variantId }),
});
if (response.ok) {
const result = await response.json();
setWarehouseData(result);
} else {
setError('Failed to fetch warehouse data');
}
} catch (err) {
setError('Connection error');
} finally {
setLoading(false);
}
};

const handleSync = async () => {
setLoading(true);
setError(null);

try {
const response = await fetch('https://your-app.com/api/warehouse/sync', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
variantId,
updateShopify,
notifyLowStock,
}),
});

if (response.ok) {
setSuccess(true);
close();
} else {
const result = await response.json();
setError(result.message || 'Sync failed');
}
} catch (err) {
setError('Failed to sync inventory');
} finally {
setLoading(false);
}
};

return (
<AdminAction
title="Sync Inventory from Warehouse"
primaryAction={
<Button onPress={handleSync} disabled={loading || success || !warehouseData}>
{loading ? 'Syncing...' : 'Sync Now'}
</Button>
}
secondaryAction={<Button onPress={close}>Cancel</Button>}
>
<BlockStack gap="base">
{success && <Banner tone="success">Inventory synced successfully!</Banner>}
{error && <Banner tone="critical">{error}</Banner>}

{warehouseData && (
<Banner tone="info">
Warehouse stock: {warehouseData.quantity} units at {warehouseData.location}
</Banner>
)}

<Divider />

<Box padding="base">
<BlockStack gap="base">
<Checkbox
checked={updateShopify}
onChange={setUpdateShopify}
>
Update Shopify inventory levels
</Checkbox>
<Checkbox
checked={notifyLowStock}
onChange={setNotifyLowStock}
>
Send alert if stock is below threshold
</Checkbox>
</BlockStack>
</Box>
</BlockStack>
</AdminAction>
);
}

Anchor to Product variant details action (should render) ,[object Object]Product variant details action (should render) target

admin.product-variant-details.action.should-render

Controls the render state of an admin action extension on the product variants details page. Use this target to conditionally show or hide your action extension based on the product variant's properties, such as status, configuration, or specific business requirements.

This target returns a boolean value that determines whether the corresponding action extension appears in the More actions menu. The extension evaluates each time the page loads.

Support
Components (0)
APIs (1)

Supported components

-

Available APIs

Examples
import {extension} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-variant-details.action.should-render',
async ({data}) => {
const variantId = data.selected[0].id;

try {
const response = await fetch('https://your-app.com/api/variant-price-review', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({variantId}),
});

if (!response.ok) {
return {display: false};
}

const result = await response.json();
// Display action if variant needs price review based on:
// - Margin below threshold
// - Price hasn't been reviewed recently
// - Competitor price changes detected
return {display: result.needsPriceReview === true};
} catch (err) {
console.error('Failed to check price review status:', err);
return {display: false};
}
}
);

Anchor to Product variant details block ,[object Object]Product variant details block target

admin.product-variant-details.block.render

Renders an admin block extension inline on the product variants details page. Use this target to display contextual information, analytics, or status updates related to the product variants without requiring merchant interaction to open a modal.

Extensions at this target can access product variants data through the data property in the Block Extension API. Blocks appear as cards on the page and can show real-time data, insights, or quick actions, providing persistent visibility for information merchants need to see at a glance.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React, { useState, useEffect } from 'react';
import {
reactExtension,
useApi,
AdminBlock,
Banner,
BlockStack,
Box,
Button,
Divider,
Heading,
Icon,
Text,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.product-variant-details.block.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const { data } = useApi(TARGET);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
const [competitors, setCompetitors] = useState([]);
const [variantPrice, setVariantPrice] = useState(null);

const fetchCompetitorPricing = async () => {
setLoading(true);
setError(null);
const variantId = data.selected[0].id;

try {
const response = await fetch('https://your-app.com/api/competitor-pricing', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ variantId }),
});

if (!response.ok) throw new Error('Failed to fetch pricing');

const result = await response.json();
setCompetitors(result.competitors);
setVariantPrice(result.yourPrice);
} catch (err) {
setError('Unable to load competitor pricing');
} finally {
setLoading(false);
}
};

useEffect(() => {
fetchCompetitorPricing();
}, []);

const getPriceTone = (competitorPrice) => {
if (!variantPrice) return 'info';
if (competitorPrice > variantPrice) return 'success';
if (competitorPrice < variantPrice) return 'critical';
return 'info';
};

return (
<AdminBlock title="Competitor Pricing">
{error && (
<Banner tone="critical" dismissible onDismiss={() => setError(null)}>
{error}
</Banner>
)}

<BlockStack gap="base">
{loading ? (
<Text>Loading competitor data...</Text>
) : (
<>
<Box padding="base" background="subdued" borderRadius="base">
<BlockStack gap="tight">
<Text emphasis="bold">Your Price</Text>
<Heading size="large">${variantPrice?.toFixed(2) || 'N/A'}</Heading>
</BlockStack>
</Box>

<Divider />

<Heading size="small">Market Comparison</Heading>
{competitors.map((competitor, index) => (
<Box key={index} padding="base" border="base" borderRadius="base">
<BlockStack gap="tight">
<Text emphasis="bold">{competitor.name}</Text>
<Text tone={getPriceTone(competitor.price)}>
${competitor.price.toFixed(2)}
{competitor.price < variantPrice && ' (Lower)'}
{competitor.price > variantPrice && ' (Higher)'}
</Text>
<Text appearance="subdued" size="small">
Last updated: {competitor.lastUpdated}
</Text>
</BlockStack>
</Box>
))}

<Button onPress={fetchCompetitorPricing}>
Refresh Pricing
</Button>
</>
)}
</BlockStack>
</AdminBlock>
);
}

Anchor to Product variant details configuration ,[object Object]Product variant details configuration target

admin.product-variant-details.configuration.render

Renders a configuration interface for product bundles on product variant details pages. This target allows merchants to configure component products, quantities, and pricing for bundle configurations directly from the variant editor. Use this target when your app needs to provide merchant-facing configuration UI for bundle components and options.

Learn how to add a product configuration extension.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React from 'react';
import { useState, useEffect } from 'react';
import {
reactExtension,
useApi,
AdminAction,
Banner,
BlockStack,
Box,
Button,
Checkbox,
ChoiceList,
Divider,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.product-variant-details.configuration.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const { data, close } = useApi(TARGET);
const [loading, setLoading] = useState(false);
const [success, setSuccess] = useState(false);
const [error, setError] = useState('');
const [warehouseData, setWarehouseData] = useState(null);
const [syncLocation, setSyncLocation] = useState(['primary']);
const [updateThreshold, setUpdateThreshold] = useState(false);

const variantId = data.selected[0].id;

useEffect(() => {
fetchWarehouseData();
}, []);

const fetchWarehouseData = async () => {
try {
const response = await fetch('https://your-app.com/api/warehouse/inventory', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ variantId }),
});
if (response.ok) {
const result = await response.json();
setWarehouseData(result);
}
} catch (err) {
setError('Failed to fetch warehouse data');
}
};

const handleSync = async () => {
setLoading(true);
setError('');

try {
const response = await fetch('https://your-app.com/api/warehouse/sync', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
variantId,
locations: syncLocation,
updateThreshold,
}),
});

if (response.ok) {
setSuccess(true);
close();
} else {
const result = await response.json();
setError(result.message || 'Sync failed');
}
} catch (err) {
setError('Connection error. Please try again.');
} finally {
setLoading(false);
}
};

return (
<AdminAction
title="Sync Inventory from Warehouse"
primaryAction={
<Button onPress={handleSync} disabled={loading || success || !warehouseData}>
{loading ? 'Syncing...' : 'Sync Now'}
</Button>
}
secondaryAction={<Button onPress={close}>Cancel</Button>}
>
<BlockStack gap="base">
{success && (
<Banner tone="success">Inventory synced successfully!</Banner>
)}
{error && <Banner tone="critical">{error}</Banner>}

{warehouseData && (
<Banner tone="info">
Warehouse stock: {warehouseData.quantity} units available
</Banner>
)}

<Divider />

<Box paddingBlockStart="base">
<ChoiceList
title="Sync to location"
choices={[
{ id: 'primary', label: 'Primary warehouse' },
{ id: 'secondary', label: 'Secondary warehouse' },
{ id: 'all', label: 'All locations' },
]}
value={syncLocation}
onChange={setSyncLocation}
/>
</Box>

<Divider />

<Box paddingBlockStart="base">
<Checkbox
checked={updateThreshold}
onChange={setUpdateThreshold}
>
Update low stock threshold based on warehouse data
</Checkbox>
</Box>
</BlockStack>
</AdminAction>
);
}

Anchor to Product variant purchase option targetsProduct variant purchase option targets

Use action targets to extend the product variant purchase option page with workflows and operations.

Extensions can query and mutate Shopify data using the direct API, or call your app's backend for custom business logic and external integrations.

Anchor to Product variant purchase option action ,[object Object]Product variant purchase option action target

admin.product-variant-purchase-option.action.render

Renders an admin action extension on the product variants details page. Merchants can access this extension from the More actions menu. Use this target to provide workflows that operate on product variants data, such as syncing with external systems, exporting product variants information, or managing credit terms.

Extensions at this target can access product variants data through the data property in the Action Extension API. The action renders in a modal overlay, providing space for multi-step workflows, forms, and confirmations.

Support
Components (35)
APIs (1)

Supported components

Available APIs

Examples
import React from 'react';
import { useState } from 'react';
import {
reactExtension,
useApi,
AdminAction,
Banner,
BlockStack,
Box,
Button,
Checkbox,
ChoiceList,
Divider,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.product-variant-purchase-option.action.render';

export default reactExtension(TARGET, () => <App />);

function App() {
const { data, close } = useApi(TARGET);
const [loading, setLoading] = useState(false);
const [success, setSuccess] = useState(false);
const [error, setError] = useState<string | null>(null);
const [warehouse, setWarehouse] = useState(['primary']);
const [overwriteExisting, setOverwriteExisting] = useState(true);
const [syncReserved, setSyncReserved] = useState(false);

const handleSync = async () => {
setLoading(true);
setError(null);
const variantId = data.selected[0].id;

try {
const response = await fetch('https://your-app.com/api/inventory/sync', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
variantId,
warehouse: warehouse[0],
overwriteExisting,
includeReserved: syncReserved,
}),
});

if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.message || 'Sync failed');
}

setSuccess(true);
close();
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to sync inventory');
} finally {
setLoading(false);
}
};

return (
<AdminAction
title="Sync Inventory from Warehouse"
primaryAction={
<Button onPress={handleSync} disabled={loading || success}>
{loading ? 'Syncing...' : 'Sync Now'}
</Button>
}
secondaryAction={<Button onPress={close}>Cancel</Button>}
>
<BlockStack gap="base">
{success && (
<Banner tone="success">Inventory synced successfully!</Banner>
)}
{error && (
<Banner tone="critical">{error}</Banner>
)}

<Box>
<ChoiceList
title="Select Warehouse"
name="warehouse"
value={warehouse}
onChange={setWarehouse}
choices={[
{ label: 'Primary Warehouse (US-East)', value: 'primary' },
{ label: 'Secondary Warehouse (US-West)', value: 'secondary' },
{ label: 'European Distribution Center', value: 'europe' },
]}
/>
</Box>

<Divider />

<BlockStack gap="base">
<Checkbox
checked={overwriteExisting}
onChange={setOverwriteExisting}
>
Overwrite existing inventory counts
</Checkbox>
<Checkbox
checked={syncReserved}
onChange={setSyncReserved}
>
Include reserved stock in available count
</Checkbox>
</BlockStack>
</BlockStack>
</AdminAction>
);
}

Anchor to Best practicesBest practices

  • Display variant context clearly: Always show which product a variant belongs to (product title) alongside variant-specific details (option values, SKU). Merchants often view variants out of context and need this information to make decisions.
  • Aggregate inventory across locations: When displaying variant inventory, show total inventory by default but allow filtering by location. Merchants with multi-location setups need location-specific visibility for fulfillment decisions.
  • Validate marketplace requirements: Before publishing variants to external marketplaces, validate that required variant fields (SKU, barcode, weight, dimensions) are populated. Many marketplaces reject variants missing these fields, and early validation prevents failed sync attempts.
  • Handle option combinations carefully: Variants are defined by option combinations (for example, Size: Large, Color: Red). When building extensions that manipulate variants, preserve the option structure and validate that option combinations remain unique within the product.
  • Check inventory tracking status: Use inventoryItem.tracked to determine if a variant tracks inventory before displaying inventory-related actions. Extensions that assume all variants track inventory will fail for digital products or services.

Anchor to LimitationsLimitations

  • Single target per module: Each [[extensions.targeting]] entry in your TOML configuration maps one target to one module file.
  • Purchase option target visibility: The admin.product-variant-purchase-option.action.render target only appears when the product variant has a selling plan group associated with it.
  • Configuration target availability: The admin.product-variant-details.configuration.render target only appears for product variants configured as bundles.
  • Block target visibility: Block extensions must be manually added and pinned by merchants before they appear.
  • Block collapse behavior: Returning null from a block extension collapses the block rather than removing it from the page. Blocks can't be fully hidden at runtime.
Was this page helpful?