---
title: Discounts API
description: >-
  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.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/discounts-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/discounts-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# 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.

### Use 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

* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)

### Properties

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

* **discountAllocations**

  **StatefulRemoteSubscribable\<CartDiscountAllocation\[]>**

  **required**

  The order-level discount allocations, including code-based, automatic, and custom discounts. Each allocation includes the discounted amount and the discount source.

* **discountCodes**

  **StatefulRemoteSubscribable\<CartDiscountCode\[]>**

  **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.

```ts
CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation
```

### CartCodeDiscountAllocation

* code

  The discount code that the buyer entered at checkout.

  ```ts
  string
  ```

* discountedAmount

  The monetary amount deducted from the order by this discount allocation.

  ```ts
  Money
  ```

* type

  The type of discount allocation. Always \`'code'\` for code-based discounts.

  ```ts
  'code'
  ```

### Money

* amount

  The decimal money amount, such as \`29.99\`.

  ```ts
  number
  ```

* currencyCode

  The \[ISO 4217]\(https://www\.iso.org/iso-4217-currency-codes.html) currency code.

  ```ts
  CurrencyCode
  ```

### CurrencyCode

```ts
'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.

  ```ts
  Money
  ```

* title

  The merchant-defined title of the automatic discount, such as "Buy 2 Get 1 Free".

  ```ts
  string
  ```

* type

  The type of discount allocation. Always \`'automatic'\` for automatic discounts.

  ```ts
  'automatic'
  ```

### CartCustomDiscountAllocation

* discountedAmount

  The monetary amount deducted from the order by this discount allocation.

  ```ts
  Money
  ```

* title

  The title of the custom discount applied by a Shopify Script or discount function.

  ```ts
  string
  ```

* type

  The type of discount allocation. Always \`'custom'\` for custom discounts.

  ```ts
  'custom'
  ```

### CartDiscountCode

* code

  The discount code string entered by the buyer at checkout.

  ```ts
  string
  ```

Examples

### 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

  ```tsx
  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

  ```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

  ```tsx
  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

  ```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

  ```tsx
  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

  ```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);
    },
  );
  ```

***

## Best 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.

***

## Limitations

* Per-line discount allocations are available on individual cart lines through the [Cart Lines API](https://shopify.dev/docs/api/customer-account-ui-extensions/target-apis/order-apis/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.

***