--- title: Discounts API description: >- 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. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/discounts-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/discounts-api.md --- # 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. ### Use 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 * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) 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. * **discountAllocations** **SubscribableSignalLike\** **required** The discount allocations applied to the entire cart, including automatic discounts, code-based discounts, and custom discounts from [Shopify Functions](https://shopify.dev/docs/apps/build/functions). Each allocation indicates how much was discounted and how the discount was triggered. * **discountCodes** **SubscribableSignalLike\** **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. ```ts 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. ```ts () => Promise ``` * 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. ```ts (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. ```ts 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). ```ts CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation ``` ### CartCodeDiscountAllocation * code The discount code string that the buyer entered during checkout, such as \`"SAVE10"\` or \`"FREESHIP"\`. ```ts string ``` * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * type Identifies this as a code-based discount, triggered by a discount code the buyer entered at checkout. ```ts 'code' ``` ### Money * amount The decimal amount of the price. For example, \`29.99\` represents twenty-nine dollars and ninety-nine cents. ```ts number ``` * currencyCode The three-letter currency code in \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) format. ```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 value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * title The merchant-defined title of the automatic discount as displayed to the buyer, such as "Summer Sale 10% Off". ```ts string ``` * type Identifies this as an automatic discount, applied based on merchant-configured rules without a code. ```ts 'automatic' ``` ### CartCustomDiscountAllocation * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * title The title of the custom discount, typically applied by a \[Shopify Function]\(/docs/api/functions/latest/discount). ```ts string ``` * type Identifies this as a custom discount applied by a \[Shopify Function]\(/docs/api/functions/latest/discount). ```ts '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. ```ts string ``` ### Methods The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides methods to modify discount data. Access the following methods on `shopify` to apply or remove discount codes. Available to `purchase.checkout` extension targets. * **applyDiscountCodeChange** **(change: DiscountCodeChange) => 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`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/discounts#properties-propertydetail-discountcodes) property updates with the new state. **Caution:** \> See \security considerations\ if your extension retrieves discount codes through a network call. **Note:** This method returns an error if the \cart instruction\ \\discounts.can\Update\Discount\Codes\\ 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. ```ts 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. ```ts string ``` * type Identifies this as a discount code addition. Set this when creating a change to apply a discount code to the checkout. ```ts '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. ```ts string ``` * type Identifies this as a discount code removal. Set this when creating a change to remove a discount code from the checkout. ```ts 'removeDiscountCode' ``` ### DiscountCodeChangeResult The result of calling \`applyDiscountCodeChange()\`. Use the \`type\` property to determine whether the change succeeded or failed. ```ts 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. ```ts '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. ```ts string ``` * type Indicates that the discount code change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` Examples ### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const discountCodes = shopify.discountCodes.value; if (discountCodes.length === 0) { return null; } return ( Applied discount codes: {discountCodes.map((discount) => ( {discount.code} ))} ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useState} from 'preact/hooks'; export default function extension() { render(, 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 ( Discount code applied! ); } return ( Use code SAVE10 for 10% off Apply discount ); } ``` *** ## Best 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. *** ## Limitations * 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. ***