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.

Discounts

Discount details pages display information about a specific discount, including its type, value, conditions, and usage limits. Extensions on these pages help merchants manage promotional campaigns and customize discount workflows.

Anchor to Use casesUse cases

  • Sync discounts externally: Push discount codes and rules to external marketing platforms, email services, or affiliate networks.
  • Validate discount rules: Check discount configurations against business rules or inventory levels before activation.
  • Generate discount reports: Create performance reports showing discount usage, revenue impact, and customer redemption patterns.
  • Bulk discount management: Apply changes to multiple discounts at once, such as extending expiration dates or adjusting values.
  • Schedule promotions: Set up automated discount activation and deactivation based on marketing calendars or inventory triggers.
Shopify admin discount pages showing all available extension target locations.

Anchor to Discount details targetsDiscount details targets

Use action targets to extend the discount details page with workflows. Action targets open as modal overlays from the More actions menu.

The examples demonstrate fetching data from Shopify's direct API or your app's backend.

Anchor to Discount details action ,[object Object]Discount details action target

admin.discount-details.action.render

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

Extensions at this target can access discount 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, { useState, useEffect } from 'react';
import {
reactExtension,
useApi,
AdminAction,
Banner,
BlockStack,
Box,
Button,
Checkbox,
ChoiceList,
Divider,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.discount-details.action.render';

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

function App() {
const { data, close, query } = useApi(TARGET);
const [loading, setLoading] = useState(false);
const [success, setSuccess] = useState(false);
const [error, setError] = useState('');
const [posLocations, setPosLocations] = useState(['all']);
const [syncOptions, setSyncOptions] = useState({
includeUsageLimits: true,
notifyStaff: false,
});

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

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

try {
const response = await fetch('https://your-app.com/api/pos/sync-discount', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
discountId,
locations: posLocations,
includeUsageLimits: syncOptions.includeUsageLimits,
notifyStaff: syncOptions.notifyStaff,
}),
});

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 discount to POS');
} finally {
setLoading(false);
}
};

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

<ChoiceList
title="POS Locations"
name="locations"
value={posLocations}
onChange={setPosLocations}
choices={[
{ label: 'All locations', value: 'all' },
{ label: 'Main Store', value: 'main-store' },
{ label: 'Downtown Branch', value: 'downtown' },
{ label: 'Mall Kiosk', value: 'mall-kiosk' },
]}
/>

<Divider />

<Box padding="base">
<BlockStack gap="base">
<Checkbox
checked={syncOptions.includeUsageLimits}
onChange={(checked) =>
setSyncOptions((prev) => ({ ...prev, includeUsageLimits: checked }))
}
>
Include usage limits
</Checkbox>
<Checkbox
checked={syncOptions.notifyStaff}
onChange={(checked) =>
setSyncOptions((prev) => ({ ...prev, notifyStaff: checked }))
}
>
Notify store staff
</Checkbox>
</BlockStack>
</Box>
</BlockStack>
</AdminAction>
);
}

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

admin.discount-details.action.should-render

Controls the render state of an admin action extension on the discounts details page. Use this target to conditionally show or hide your action extension based on the discount'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.discount-details.action.should-render',
async ({data}) => {
const discountId = data.selected[0].id;

try {
// Check with app backend if discount has performance data
const response = await fetch('https://your-app.com/api/discount-analytics/check', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
discountId,
}),
});

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

const analyticsData = await response.json();

// Only show performance action if discount has been redeemed
// and has meaningful data to display
const hasRedemptions = analyticsData.totalRedemptions > 0;
const hasRevenueData = analyticsData.revenueImpact !== null;
const isTrackingEnabled = analyticsData.trackingEnabled === true;

return {
display: hasRedemptions && hasRevenueData && isTrackingEnabled,
};
} catch (err) {
// Don't show action if we can't verify analytics availability
return {display: false};
}
}
);

Anchor to Discount index targetsDiscount index targets

Use action targets to extend the discount index page with bulk operations and workflows that help merchants manage multiple discounts efficiently.

Anchor to Discount index action ,[object Object]Discount index action target

admin.discount-index.action.render

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

Extensions at this target can access discount 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, { useState } from 'react';
import {
reactExtension,
useApi,
AdminAction,
Banner,
BlockStack,
Box,
Button,
Checkbox,
ChoiceList,
Divider,
} from '@shopify/ui-extensions-react/admin';

const TARGET = 'admin.discount-index.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 [selectedLocations, setSelectedLocations] = useState<string[]>(['all']);
const [overwriteExisting, setOverwriteExisting] = useState(true);

const selectedDiscounts = data.selected.map(item => item.id);

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

try {
const response = await fetch('https://your-app.com/api/pos/sync-discounts', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
discountIds: selectedDiscounts,
locations: selectedLocations,
overwriteExisting,
}),
});

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

return (
<AdminAction
title="Sync Discounts to POS"
primaryAction={
<Button onPress={handleSync} disabled={loading || success}>
{loading ? 'Syncing...' : `Sync ${selectedDiscounts.length} Discount(s)`}
</Button>
}
secondaryAction={<Button onPress={close}>Cancel</Button>}
>
<BlockStack gap="base">
{success && (
<Banner tone="success">
Successfully synced {selectedDiscounts.length} discount(s) to POS!
</Banner>
)}
{error && <Banner tone="critical">{error}</Banner>}

<Box padding="base">
<BlockStack gap="base">
<ChoiceList
name="locations"
title="POS Locations"
choices={[
{ id: 'all', label: 'All locations' },
{ id: 'store-1', label: 'Main Store' },
{ id: 'store-2', label: 'Downtown Location' },
{ id: 'store-3', label: 'Mall Kiosk' },
]}
value={selectedLocations}
onChange={setSelectedLocations}
/>

<Divider />

<Checkbox
checked={overwriteExisting}
onChange={setOverwriteExisting}
>
Overwrite existing discounts in POS
</Checkbox>
</BlockStack>
</Box>
</BlockStack>
</AdminAction>
);
}

Anchor to Discount index action (should render) ,[object Object]Discount index action (should render) target

admin.discount-index.action.should-render

Controls the render state of an admin action extension on the discounts index page. Use this target to conditionally show or hide your action extension based on the discount'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.discount-index.action.should-render',
async ({data}) => {
const selectedIds = data.selected.map((item) => item.id);

if (selectedIds.length === 0) {
return {display: false};
}

try {
// Check with app backend if discounts have performance data
const response = await fetch('https://your-app.com/api/discounts/has-analytics', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({discountIds: selectedIds}),
});

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

const result = await response.json();

// Show action only if at least one discount has redemption data
// Backend returns: { hasAnalytics: boolean, minRedemptions: number }
return {
display: result.hasAnalytics && result.minRedemptions >= 5,
};
} catch (err) {
console.error('Failed to check discount analytics availability:', err);
return {display: false};
}
}
);

Anchor to Best practicesBest practices

  • Differentiate discount types: Discounts come in multiple types (basic, BXGY, free shipping, automatic vs code-based). Before displaying discount actions, check the discount type using GraphQL to ensure your extension supports it. For example, POS sync may only work with certain discount types.
  • Validate discount dates: Always check startsAt and endsAt when displaying or syncing discounts. Syncing expired or not-yet-active discounts to external systems can create customer confusion and needs special handling or filtering.
  • Provide clear feedback: Discounts workflows often involve external systems. Always provide clear success and error messages, and help merchants understand what happened and what to do next if something goes wrong.
  • Handle discount combinations: Shopify has complex discount combination rules. If your extension recommends or creates discounts, validate that they're compatible with existing discount configurations to avoid conflicts that prevent customers from completing checkouts.
  • Account for attribution delays: Discount usage counts (asyncUsageCount) update asynchronously and may lag by several minutes. When displaying real-time analytics, indicate that counts are approximate and mention the last update time if available from your system.

Anchor to LimitationsLimitations

Was this page helpful?