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 represents a single discount applied to a specific line item or the overall order. When a discount applies to an order, Shopify splits the total discount amount across the affected line items as individual allocations. For example, a "10% off your order" discount is distributed proportionally across each line item rather than appearing as one lump sum. There are three types of discount allocations: - `CartCodeDiscountAllocation`: A discount applied using a code the buyer entered at checkout (for example, "SAVE10"). - `CartAutomaticDiscountAllocation`: A discount the merchant configured in Shopify admin to apply automatically without a code. - `CartCustomDiscountAllocation`: A discount created programmatically by a [Shopify Function](/docs/apps/build/functions).

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

A discount allocation for a discount that was applied using a code the buyer entered at checkout.

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
The type of this discount allocation. Always `'code'` for discounts applied using a code entered by the buyer.
```
'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

A discount allocation for a discount that the merchant configured to apply automatically in Shopify admin, without the buyer needing to enter a code.

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
The type of this discount allocation. Always `'automatic'` for discounts configured to apply automatically without a code.
```
'automatic'
```

CartCustomDiscountAllocation

A discount allocation for a discount created by a [Shopify Function](/docs/apps/build/functions), such as a custom discount logic app.

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 as defined by the Shopify Function that created it.
```
string
```
type
The type of this discount allocation. Always `'custom'` for discounts created by a Shopify Function.
```
'custom'
```

CartDiscountCode

code
The discount code string that the buyer entered during checkout, such as "SAVE10" or "FREESHIP". Use this to display which discount codes were applied to the order.
```
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

Display applied discount codes

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

Show discount savings

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

Identify discount types

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?