--- title: Discounts API description: >- 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. api_version: 2026-04 source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/discounts-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/discounts-api.md --- # Discounts API The Discounts API provides read-only access to discount codes and discount allocations applied to an order on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status). 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](https://shopify.dev/docs/apps/build/functions). ### 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/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) 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. * **discountAllocations** **SubscribableSignalLike\** **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](https://shopify.dev/docs/apps/build/functions). Returns order-level discounts only. For per-line discount allocations, read from individual cart lines via the Cart Lines API. * **discountCodes** **SubscribableSignalLike\** **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. ```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 ``` Examples ### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { 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 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, 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 ( You saved {totalSavings.toFixed(2)}{' '} {currencyCode} {allocations.map((allocation, index) => ( -{allocation.discountedAmount.amount}{' '} { allocation.discountedAmount .currencyCode } ))} ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, 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 ( Applied discounts {allocations.map((allocation, index) => ( {DISCOUNT_LABELS[allocation.type]} -{allocation.discountedAmount.amount}{' '} { allocation.discountedAmount .currencyCode } ))} ); } ``` *** ## Best 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. *** ## Limitations * 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. ***