Discounts API
The API for interacting with discounts.
Supported targets
- purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. chat. render - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. chat. render - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Supported targets
- purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. chat. render - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. chat. render - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Anchor to standardapiStandardApi
The base API object provided to purchase extension targets.
- Anchor to discountAllocationsdiscountAllocationsdiscountAllocationsSubscribableSignalLike<CartDiscountAllocation[]>SubscribableSignalLike<CartDiscountAllocation[]>requiredrequired
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 discountCodesdiscountCodesdiscountCodesSubscribableSignalLike<CartDiscountCode[]>SubscribableSignalLike<CartDiscountCode[]>requiredrequired
The discount codes currently applied to the checkout. The list is empty if no discount codes have been applied. Use
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 | CartCustomDiscountAllocationCartCodeDiscountAllocation
- 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 checkoutapiCheckoutApi
The API object provided to purchase.checkout extension targets.
- Anchor to applyDiscountCodeChangeapplyDiscountCodeChangeapplyDiscountCodeChange(change: DiscountCodeChange) => Promise<DiscountCodeChangeResult>(change: DiscountCodeChange) => Promise<DiscountCodeChangeResult>requiredrequired
Adds or removes a discount code on the checkout. The returned promise resolves when the change has been applied by the server, and the
property updates with the new state.Caution> See security considerations if your extension retrieves discount codes through a network call.
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.
NoteThis method returns an error if the cart instruction
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 cart instruction
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#standardapi-propertydetail-instructions">cart instruction</a> <code><span class="PreventFireFoxApplyingGapToWBR">discounts.can<wbr/>Update<wbr/>Discount<wbr/>Codes</span></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 | DiscountCodeRemoveChangeDiscountCodeAddChange
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 | DiscountCodeChangeResultErrorDiscountCodeChangeResultSuccess
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'
Anchor to useApplyDiscountCodeChangeuse Apply Discount Code Change()
Returns a function to add or remove discount codes.
Anchor to useDiscountAllocationsuse Discount Allocations()
Returns the current discount allocations applied to the cart.
Anchor to useDiscountCodesuse Discount Codes()
Returns the current discount codes applied to the cart.