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.

Choose a version:

Discounts API

The Discounts API provides the discount codes and discount allocations applied to the order. Use it to display applied discounts or calculate total savings on the Order status page.

Anchor to Use casesUse cases

Display applied discount codes: Show the discount codes the buyer entered during checkout.
Show discount breakdowns: Display the amount saved through each discount, whether it was a code, an automatic discount, or a custom discount from a Shopify Function.

Support

Targets (10)

Supported targets

Anchor to PropertiesProperties

The Discounts API object provides discount codes and allocations from the order. Access the following properties on the API object to read discount data.

Anchor to discountAllocations discountAllocations StatefulRemoteSubscribable<[]> required: The order-level discount allocations, including code-based, automatic, and custom discounts. Each allocation includes the discounted amount and the discount source.
Anchor to discountCodes discountCodes StatefulRemoteSubscribable<[]> required: The discount codes that the buyer applied to the order at checkout.

CartDiscountAllocation

A discount allocation applied to the order or a line item. There are three types: - `CartCodeDiscountAllocation`: A discount applied via a code entered by the buyer. - `CartAutomaticDiscountAllocation`: An automatic discount applied by Shopify based on merchant-configured rules. - `CartCustomDiscountAllocation`: A custom discount applied by a Shopify Script or discount function.

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The discount code that the buyer entered at checkout.
```
string
```
discountedAmount
The monetary amount deducted from the order by this discount allocation.
```
Money
```
type
The type of discount allocation. Always `'code'` for code-based discounts.
```
'code'
```

Money

amount
The decimal money amount, such as `29.99`.
```
number
```
currencyCode
The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
```
CurrencyCode
```

CurrencyCode

'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'

CartAutomaticDiscountAllocation

discountedAmount
The monetary amount deducted from the order by this discount allocation.
```
Money
```
title
The merchant-defined title of the automatic discount, such as "Buy 2 Get 1 Free".
```
string
```
type
The type of discount allocation. Always `'automatic'` for automatic discounts.
```
'automatic'
```

CartCustomDiscountAllocation

discountedAmount
The monetary amount deducted from the order by this discount allocation.
```
Money
```
title
The title of the custom discount applied by a Shopify Script or discount function.
```
string
```
type
The type of discount allocation. Always `'custom'` for custom discounts.
```
'custom'
```

CartDiscountCode

code
The discount code string entered by the buyer at checkout.
```
string
```

Examples

import {

reactExtension,

useDiscountCodes,

} from '@shopify/ui-extensions-react/customer-account';

import {

Banner,

Text,

} from '@shopify/ui-extensions/customer-account';

export default reactExtension(

'customer-account.order-status.block.render',

() => <Extension />,

);

function Extension() {

const discountCodes = useDiscountCodes();

if (discountCodes.length === 0) {

return null;

}

return (

{discountCodes.map((discount) => (

<Text key={discount.code}>Code: {discount.code}</Text>

))}

</Banner>

);

}

Examples

Description

Read the discount codes applied to the order and display each code. This example uses the `useDiscountCodes` hook and lists the `code` property from each entry.

React

import {
  reactExtension,
  useDiscountCodes,
} from '@shopify/ui-extensions-react/customer-account';
import {
  Banner,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const discountCodes = useDiscountCodes();

  if (discountCodes.length === 0) {
    return null;
  }

  return (
    <Banner status="success" title="Discounts applied">
      {discountCodes.map((discount) => (
        <Text key={discount.code}>Code: {discount.code}</Text>
      ))}
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const discountCodes = api.discountCodes.current;

    if (discountCodes.length === 0) return;

    const banner = root.createComponent(
      Banner,
      {status: 'success', title: 'Discounts applied'},
    );
    for (const discount of discountCodes) {
      banner.appendChild(
        root.createComponent(Text, {}, `Code: ${discount.code}`),
      );
    }
    root.appendChild(banner);
  },
);

Description

Calculate the total savings from all discount allocations and display the amount. This example uses `useDiscountAllocations` to sum the `discountedAmount` across all allocations.

React

import {
  reactExtension,
  useDiscountAllocations,
  useI18n,
} from '@shopify/ui-extensions-react/customer-account';
import {
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const allocations = useDiscountAllocations();
  const i18n = useI18n();

  if (allocations.length === 0) {
    return null;
  }

  const totalSavings = allocations.reduce(
    (sum, alloc) => sum + alloc.discountedAmount.amount,
    0,
  );

  const currency = allocations[0].discountedAmount.currencyCode;

  return (
    <BlockStack>
      <Text emphasis="bold">
        You saved {i18n.formatCurrency(totalSavings, {currency})}
      </Text>
      {allocations.map((alloc, index) => (
        <Text key={index} appearance="subdued">
          {alloc.type === 'code'
            ? `Code "${alloc.code}"`
            : alloc.title}{' '}
          — {i18n.formatCurrency(
            alloc.discountedAmount.amount,
            {currency},
          )}
        </Text>
      ))}
    </BlockStack>
  );
}

TS

import {
  extension,
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const allocations = api.discountAllocations.current;

    if (allocations.length === 0) return;

    const totalSavings = allocations.reduce(
      (sum, alloc) => sum + alloc.discountedAmount.amount,
      0,
    );
    const currency = allocations[0].discountedAmount.currencyCode;

    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(
      root.createComponent(
        Text,
        {emphasis: 'bold'},
        `You saved ${api.i18n.formatCurrency(totalSavings, {currency})}`,
      ),
    );

    for (const alloc of allocations) {
      const label =
        alloc.type === 'code' ? `Code "${alloc.code}"` : alloc.title;
      stack.appendChild(
        root.createComponent(
          Text,
          {appearance: 'subdued'},
          `${label} — ${api.i18n.formatCurrency(alloc.discountedAmount.amount, {currency})}`,
        ),
      );
    }
    root.appendChild(stack);
  },
);

Description

Group discount allocations by type and display each category separately. This example filters allocations by their `type` field into code, automatic, and custom groups.

React

import {
  reactExtension,
  useDiscountAllocations,
} from '@shopify/ui-extensions-react/customer-account';
import {
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const allocations = useDiscountAllocations();

  const codeDiscounts = allocations.filter(
    (a) => a.type === 'code',
  );
  const automaticDiscounts = allocations.filter(
    (a) => a.type === 'automatic',
  );

  if (allocations.length === 0) {
    return null;
  }

  return (
    <BlockStack>
      {codeDiscounts.length > 0 && (
        <>
          <Text emphasis="bold">Code discounts</Text>
          {codeDiscounts.map((d, i) => (
            <Text key={i}>
              {d.code}: -{d.discountedAmount.amount}{' '}
              {d.discountedAmount.currencyCode}
            </Text>
          ))}
        </>
      )}
      {automaticDiscounts.length > 0 && (
        <>
          <Text emphasis="bold">Automatic discounts</Text>
          {automaticDiscounts.map((d, i) => (
            <Text key={i}>
              {d.title}: -{d.discountedAmount.amount}{' '}
              {d.discountedAmount.currencyCode}
            </Text>
          ))}
        </>
      )}
    </BlockStack>
  );
}

TS

import {
  extension,
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const allocations = api.discountAllocations.current;

    if (allocations.length === 0) return;

    const codeDiscounts = allocations.filter((a) => a.type === 'code');
    const automaticDiscounts = allocations.filter(
      (a) => a.type === 'automatic',
    );

    const stack = root.createComponent(BlockStack, {});

    if (codeDiscounts.length > 0) {
      stack.appendChild(
        root.createComponent(Text, {emphasis: 'bold'}, 'Code discounts'),
      );
      for (const d of codeDiscounts) {
        stack.appendChild(
          root.createComponent(
            Text,
            {},
            `${d.code}: -${d.discountedAmount.amount} ${d.discountedAmount.currencyCode}`,
          ),
        );
      }
    }

    if (automaticDiscounts.length > 0) {
      stack.appendChild(
        root.createComponent(
          Text,
          {emphasis: 'bold'},
          'Automatic discounts',
        ),
      );
      for (const d of automaticDiscounts) {
        stack.appendChild(
          root.createComponent(
            Text,
            {},
            `${d.title}: -${d.discountedAmount.amount} ${d.discountedAmount.currencyCode}`,
          ),
        );
      }
    }

    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Distinguish discount types: Use the type field on each allocation to differentiate between 'code', 'automatic', and 'custom' discounts.
Use allocations for savings totals: Sum the discountedAmount across all allocations to calculate total savings. Don't rely on discount codes alone, as automatic and custom discounts don't have codes.

Anchor to LimitationsLimitations

Per-line discount allocations are available on individual cart lines through the Cart Lines API, not through this API. The discountAllocations property on the Discounts API returns only order-level discounts.
Discount allocations show the discounted amount, but not the original discount configuration. You can't determine whether a discount was a percentage or fixed amount from the allocation alone.

Was this page helpful?