Choose a version:

Discounts API

The Discounts API provides read-only access to discount codes and discount allocations applied to an order on the Order status page. Use this API to read which discounts were applied, how much was discounted, and whether each was a code, automatic, or custom discount from a Shopify Function.

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 shopify global object provides the discount codes and discount allocations applied to the order. Access the following properties on shopify to read which discounts were applied and how much was discounted.

Anchor to discountAllocations discountAllocations <[]> required: The cart-level discount allocations applied to the order. A discount allocation represents how a discount is distributed across the order. Each allocation includes the discounted amount and one of the following types:

CartCodeDiscountAllocation: A discount the buyer applied by entering a code at checkout.

CartAutomaticDiscountAllocation: A discount the merchant configured in Shopify admin to apply automatically.

CartCustomDiscountAllocation: A discount created programmatically by a Shopify Function.

Returns order-level discounts only. For per-line discount allocations, read from individual cart lines via the Cart Lines API.
Anchor to discountCodes discountCodes <[]> required: A list of discount codes that the buyer entered during checkout and that were applied to the order.

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

CartDiscountAllocation

A discount allocation applied to the cart. Use the `type` property to determine how the discount was triggered: - `CartCodeDiscountAllocation` (`type: 'code'`): Triggered by a discount code the buyer entered. - `CartAutomaticDiscountAllocation` (`type: 'automatic'`): Applied automatically based on merchant-configured rules. - `CartCustomDiscountAllocation` (`type: 'custom'`): Applied by a [Shopify Function](/docs/api/functions/latest/discount).

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The discount code string that the buyer entered during checkout, such as `"SAVE10"` or `"FREESHIP"`.
```
string
```
discountedAmount
The monetary value that was deducted from the line item or order total by this discount allocation.
```
Money
```
type
Identifies this as a code-based discount, triggered by a discount code the buyer entered at checkout.
```
'code'
```

Money

amount
The decimal amount of the price. For example, `29.99` represents twenty-nine dollars and ninety-nine cents.
```
number
```
currencyCode
The three-letter currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
```
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 value that was deducted from the line item or order total by this discount allocation.
```
Money
```
title
The merchant-defined title of the automatic discount as displayed to the buyer, such as "Summer Sale 10% Off".
```
string
```
type
Identifies this as an automatic discount, applied based on merchant-configured rules without a code.
```
'automatic'
```

CartCustomDiscountAllocation

discountedAmount
The monetary value that was deducted from the line item or order total by this discount allocation.
```
Money
```
title
The title of the custom discount, typically applied by a [Shopify Function](/docs/api/functions/latest/discount).
```
string
```
type
Identifies this as a custom discount applied by a [Shopify Function](/docs/api/functions/latest/discount).
```
'custom'
```

CartDiscountCode

code
The discount code string entered by the buyer during checkout or applied programmatically, such as `"SAVE10"` or `"FREESHIP"`. Use this to display which discount codes were applied.
```
string
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const discountCodes =

shopify.discountCodes.value;

if (discountCodes.length === 0) {

return null;

}

return (

<s-box>

<s-text color="subdued">

Applied discount codes

</s-text>

{discountCodes.map((discount) => (

<s-text key={discount.code}>

{discount.code}

</s-text>

))}

</s-box>

);

}

Examples

Description

Show the discount codes the buyer entered during checkout. This example reads `shopify.discountCodes` and renders each code in a styled list.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const discountCodes =
    shopify.discountCodes.value;

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

  return (
    <s-box>
      <s-text color="subdued">
        Applied discount codes
      </s-text>
      {discountCodes.map((discount) => (
        <s-text key={discount.code}>
          {discount.code}
        </s-text>
      ))}
    </s-box>
  );
}

Description

Calculate and display the total savings from all discount allocations. This example iterates over `shopify.discountAllocations` to sum the discounted amounts and shows a per-discount breakdown.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const allocations =
    shopify.discountAllocations.value;

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

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

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

  return (
    <s-box>
      <s-text type="strong">
        You saved {totalSavings.toFixed(2)}{' '}
        {currencyCode}
      </s-text>
      <s-divider />
      {allocations.map((allocation, index) => (
        <s-text key={index}>
          -{allocation.discountedAmount.amount}{' '}
          {
            allocation.discountedAmount
              .currencyCode
          }
        </s-text>
      ))}
    </s-box>
  );
}

Description

Label each discount by its type: code, automatic, or custom. This example reads the `type` field on each allocation and maps it to a human-readable label using a lookup object.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

const DISCOUNT_LABELS = {
  code: 'Discount code',
  automatic: 'Automatic discount',
  custom: 'Custom discount',
};

function Extension() {
  const allocations =
    shopify.discountAllocations.value;

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

  return (
    <s-box>
      <s-text type="strong">
        Applied discounts
      </s-text>
      {allocations.map((allocation, index) => (
        <s-stack key={index} direction="inline">
          <s-text color="subdued">
            {DISCOUNT_LABELS[allocation.type]}
          </s-text>
          <s-text>
            -{allocation.discountedAmount.amount}{' '}
            {
              allocation.discountedAmount
                .currencyCode
            }
          </s-text>
        </s-stack>
      ))}
    </s-box>
  );
}

Anchor to Best practicesBest practices

Check both properties for a complete picture: discountCodes lists the codes entered by the buyer, while discountAllocations shows the actual amounts discounted. A single code can result in multiple allocations across different line items.

Anchor to LimitationsLimitations

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 data alone.

Was this page helpful?