--- 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: 2027-01 source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/target-apis/order-apis/discounts-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/target-apis/order-apis/discounts-api.md api_name: customer-account-ui-extensions --- # 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/2027-01-rc/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/2027-01-rc/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/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/2027-01-rc/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/2027-01-rc/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/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/2027-01-rc/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/2027-01-rc/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/2027-01-rc#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. * **discount​Allocations** **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. * **discount​Codes** **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 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). ```ts 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". ```ts string ``` * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * type The type of this discount allocation. Always \`'code'\` for discounts applied using a code entered by the buyer. ```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 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. ```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 The type of this discount allocation. Always \`'automatic'\` for discounts configured to apply automatically without a code. ```ts '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. ```ts Money ``` * title The title of the custom discount as defined by the Shopify Function that created it. ```ts string ``` * type The type of this discount allocation. Always \`'custom'\` for discounts created by a Shopify Function. ```ts '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. ```ts string ``` ### 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 ```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} ))} ); } ``` * #### 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 ```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 } ))} ); } ``` * #### 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 ```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. ***