Choose a version:

Discounts API

The Discounts API provides access to discount codes and allocations applied to the checkout. Use this API to display active discounts, apply new discount codes, and remove existing ones.

Anchor to Use casesUse cases

Display applied discount codes: Show the buyer which discount codes are currently active on the checkout.
Apply a discount code: Let buyers enter a discount code and submit it programmatically.
Show discount breakdowns: Display how discounts are distributed across individual line items.

Support

Targets (31)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides discount data for the current checkout. Access the following properties on shopify to read applied discount codes and allocations. Available to purchase extension targets.

Anchor to discountAllocations discountAllocations <[]> required: The discount allocations applied to the entire cart, including automatic discounts, code-based discounts, and custom discounts from Shopify Functions. Each allocation indicates how much was discounted and how the discount was triggered.
Anchor to discountCodes discountCodes <[]> required: The discount codes currently applied to the checkout. The list is empty if no discount codes have been applied. Use applyDiscountCodeChange() to add or remove codes.

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

Anchor to MethodsMethods

The shopify global object provides methods to modify discount data. Access the following methods on shopify to apply or remove discount codes. Available to purchase.checkout extension targets.

Anchor to applyDiscountCodeChange applyDiscountCodeChange (change: ) => Promise<> required: Adds or removes a discount code on the checkout. The returned promise resolves when the change has been applied by the server, and the discountCodes property updates with the new state.

Caution
> See security considerations if your extension retrieves discount codes through a network call.
Caution: > See <a href="/docs/api/checkout-ui-extensions/latest/configuration#network-access">security considerations</a> if your extension retrieves discount codes through a network call.
Note
This method returns an error if the cart instruction discounts.canUpdateDiscountCodes is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
Note: This method returns an error if the <a href="/docs/api/checkout-ui-extensions/latest/apis/cart-instructions#properties-propertydetail-instructions">cart instruction</a> <code>discounts.canUpdateDiscountCodes</code> is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

DiscountCodeChange

The input for `applyDiscountCodeChange()`. Pass either a `DiscountCodeAddChange` (with `type: 'addDiscountCode'`) to apply a code or a `DiscountCodeRemoveChange` (with `type: 'removeDiscountCode'`) to remove it.

DiscountCodeAddChange | DiscountCodeRemoveChange

DiscountCodeAddChange

Applies a discount code to the checkout. Pass this to `applyDiscountCodeChange()` to add a code.

code
The discount code to apply. Codes are case-insensitive.
```
string
```
type
Identifies this as a discount code addition. Set this when creating a change to apply a discount code to the checkout.
```
'addDiscountCode'
```

DiscountCodeRemoveChange

Removes a discount code from the checkout. Pass this to `applyDiscountCodeChange()` to remove a code.

code
The discount code to remove. Codes are case-insensitive.
```
string
```
type
Identifies this as a discount code removal. Set this when creating a change to remove a discount code from the checkout.
```
'removeDiscountCode'
```

DiscountCodeChangeResult

The result of calling `applyDiscountCodeChange()`. Use the `type` property to determine whether the change succeeded or failed.

DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError

DiscountCodeChangeResultSuccess

The result of a successful discount code change. The `type` property is `'success'`.

type
Indicates that the discount code change was applied successfully.
```
'success'
```

DiscountCodeChangeResultError

The result of a failed discount code change. Check the `message` property for details about what went wrong.

message
A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer.
```
string
```
type
Indicates that the discount code change couldn't be applied. Check the `message` property for details.
```
'error'
```

Examples

jsx

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

import {render} from 'preact';

export default function extension() {

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

}

function Extension() {

const discountCodes = shopify.discountCodes.value;

if (discountCodes.length === 0) {

return null;

}

return (

<s-stack>

<s-text type="strong">

Applied discount codes:

</s-text>

{discountCodes.map((discount) => (

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

{discount.code}

</s-text>

))}

</s-stack>

);

}

Examples

Description

List all active discount codes on the checkout. This example renders each active code in a stack, returning nothing when no codes are applied.

jsx

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

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

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

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

  return (
    <s-stack>
      <s-text type="strong">
        Applied discount codes:
      </s-text>
      {discountCodes.map((discount) => (
        <s-text key={discount.code}>
          {discount.code}
        </s-text>
      ))}
    </s-stack>
  );
}

Description

Let the buyer enter a promo code and submit it programmatically. This example calls `shopify.applyDiscountCodeChange` after checking [`instructions.discounts.canUpdateDiscountCodes`](/docs/api/checkout-ui-extensions/apis/cart-instructions), and shows a success banner when the code is accepted.

jsx

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

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

function Extension() {
  const [applied, setApplied] = useState(false);

  const canUpdate =
    shopify.instructions.value.discounts
      .canUpdateDiscountCodes;

  async function applyDiscount() {
    const result =
      await shopify.applyDiscountCodeChange({
        type: 'addDiscountCode',
        code: 'SAVE10',
      });

    if (result.type === 'error') {
      console.error(result.message);
    } else {
      setApplied(true);
    }
  }

  if (!canUpdate) {
    return null;
  }

  if (applied) {
    return (
      <s-banner tone="success">
        Discount code applied!
      </s-banner>
    );
  }

  return (
    <s-stack>
      <s-banner heading="Special offer">
        Use code SAVE10 for 10% off
      </s-banner>
      <s-button onClick={applyDiscount}>
        Apply discount
      </s-button>
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Provide your own feedback on errors: applyDiscountCodeChange resolves with a type of 'success' or 'error'. The error message is for debugging only and isn't localized, so display your own buyer-facing feedback (for example, "That code didn't work. Check the code and try again.").
Treat discount codes as case-insensitive: The discount system treats SAVE10 and save10 as the same code. Normalize the display in your UI to avoid confusion.

Anchor to LimitationsLimitations

Discount code changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay.
Extensions can add or remove discount codes, but can't modify automatic discounts or custom discounts applied by Shopify Scripts.

Was this page helpful?