Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Discounts API

The API for interacting with discounts.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

Anchor to discountAllocations discountAllocations StatefulRemoteSubscribable<[]> required: Discounts that have been applied to the entire cart.
Anchor to discountCodes discountCodes StatefulRemoteSubscribable<[]> required: A list of discount codes currently applied to the checkout.

CartDiscountAllocation

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The code for the discount
```
string
```
discountedAmount
The money amount that has been discounted from the order
```
Money
```
type
The type of the code discount
```
'code'
```

Money

amount
The price amount.
```
number
```
currencyCode
The ISO 4217 format for the currency.
```
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 money amount that has been discounted from the order
```
Money
```
title
The title of the automatic discount
```
string
```
type
The type of the automatic discount
```
'automatic'
```

CartCustomDiscountAllocation

discountedAmount
The money amount that has been discounted from the order
```
Money
```
title
The title of the custom discount
```
string
```
type
The type of the custom discount
```
'custom'
```

CartDiscountCode

code
The code for the discount
```
string
```

Anchor to checkoutapiCheckoutApi

The API object provided to purchase.checkout extension targets.

Anchor to applyDiscountCodeChange applyDiscountCodeChange (change: ) => Promise<> required: Performs an update on the discount codes. It resolves when the new discount codes have been negotiated and results in an update to the value retrieved through the discountCodes property.

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

DiscountCodeChange

DiscountCodeAddChange | DiscountCodeRemoveChange

DiscountCodeAddChange

code
The code for the discount (case-insensitive)
```
string
```
type
The type of the `DiscountCodeChange` API.
```
'addDiscountCode'
```

DiscountCodeRemoveChange

code
The code for the discount (case-insensitive)
```
string
```
type
The type of the `DiscountCodeChange` API.
```
'removeDiscountCode'
```

DiscountCodeChangeResult

DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError

DiscountCodeChangeResultSuccess

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

DiscountCodeChangeResultError

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
Indicates that the discount code change failed.
```
'error'
```

Anchor to useApplyDiscountCodeChange
useApplyDiscountCodeChange()

Returns a function to add or remove discount codes.

Anchor to useApplyDiscountCodeChange-returnsReturns

(change: ) => Promise<>