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.
Gift Cards API
The API for interacting with gift cards.
Anchor to standardapiStandardApi
The base API object provided to purchase extension targets.
- Anchor to appliedGiftCardsappliedGiftCardsappliedGiftCardsStatefulRemoteSubscribable<AppliedGiftCard[]>StatefulRemoteSubscribable<AppliedGiftCard[]>requiredrequired
Gift Cards that have been applied to the checkout.
AppliedGiftCard
- amountUsed
The amount of the applied gift card that will be used when the checkout is completed.
Money - balance
The current balance of the applied gift card prior to checkout completion.
Money - lastCharacters
The last four characters of the applied gift card's code.
string
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'Anchor to checkoutapiCheckoutApi
The API object provided to purchase.checkout extension targets.
- Anchor to applyGiftCardChangeapplyGiftCardChangeapplyGiftCardChange(change: GiftCardChange) => Promise<GiftCardChangeResult>(change: GiftCardChange) => Promise<GiftCardChangeResult>requiredrequired
Performs an update on the gift cards. It resolves when gift card change have been negotiated and results in an update to the value retrieved through the
property.Caution> See security considerations if your extension retrieves gift card codes through a network call.
Caution:> See security considerations if your extension retrieves gift card codes through a network call.
Caution: > See <a href="/docs/api/checkout-ui-extensions/configuration#network-access">security considerations</a> if your extension retrieves gift card codes through a network call.
NoteThis method will return an error if 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 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 buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
GiftCardChange
GiftCardAddChange | GiftCardRemoveChangeGiftCardAddChange
- code
Gift card code.
string - type
The type of the `GiftCardChange` API.
'addGiftCard'
GiftCardRemoveChange
- code
The full gift card code, or the last four digits of the code.
string - type
The type of the `GiftCardChange` API.
'removeGiftCard'
GiftCardChangeResult
GiftCardChangeResultSuccess | GiftCardChangeResultErrorGiftCardChangeResultSuccess
- type
Indicates that the gift card change was applied successfully.
'success'
GiftCardChangeResultError
- 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 gift card change failed.
'error'
Anchor to useAppliedGiftCardsuse
Returns the current gift cards applied to the cart.
AppliedGiftCard
- amountUsed
The amount of the applied gift card that will be used when the checkout is completed.
Money - balance
The current balance of the applied gift card prior to checkout completion.
Money - lastCharacters
The last four characters of the applied gift card's code.
string
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'Anchor to useApplyGiftCardChangeuse
Returns a function to add or remove gift cards.
GiftCardChange
GiftCardAddChange | GiftCardRemoveChangeGiftCardAddChange
- code
Gift card code.
string - type
The type of the `GiftCardChange` API.
'addGiftCard'
GiftCardRemoveChange
- code
The full gift card code, or the last four digits of the code.
string - type
The type of the `GiftCardChange` API.
'removeGiftCard'
GiftCardChangeResult
GiftCardChangeResultSuccess | GiftCardChangeResultErrorGiftCardChangeResultSuccess
- type
Indicates that the gift card change was applied successfully.
'success'
GiftCardChangeResultError
- 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 gift card change failed.
'error'
