--- title: Gift Cards API description: >- The Gift Cards API provides access to gift cards applied to the checkout. Use this API to display applied gift cards, apply new gift card codes, and show the amount deducted from each card. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/gift-cards-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/gift-cards-api.md --- # Gift Cards API The Gift Cards API provides access to gift cards applied to the checkout. Use this API to display applied gift cards, apply new gift card codes, and show the amount deducted from each card. ### Use cases * **Display applied gift cards**: Show each gift card's last four characters and the amount deducted. * **Apply a gift card**: Let buyers enter a gift card code and submit it during checkout. * **Show gift card deductions**: Display how much each gift card contributes to the checkout total. ### Support Targets (31) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides gift card data for the current checkout. Access the following properties on `shopify` to read applied gift cards. Available to `purchase` extension targets. * **appliedGiftCards** **SubscribableSignalLike\** **required** The gift cards that have been applied to the checkout. Each entry includes the last four characters of the gift card code, the amount used at checkout, and the card's remaining balance. ### 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 ``` ### AppliedGiftCard * amountUsed The amount of the applied gift card that's used when the checkout is completed. This might be less than \`balance\` if the order total is lower than the card's remaining balance. ```ts Money ``` * balance The current balance of the applied gift card before checkout completion. This reflects the full remaining value on the card, not just the amount being applied to this order. ```ts Money ``` * lastCharacters The last four characters of the applied gift card's code. The full code isn't exposed for security reasons. Use this value to display which card is applied. ```ts string ``` ### 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' ``` ### Methods The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides methods to modify gift card data. Access the following methods on `shopify` to apply or remove gift cards. Available to `purchase.checkout` extension targets. * **applyGiftCardChange** **(change: GiftCardChange) => Promise\** **required** Adds or removes a gift card from the checkout. The returned promise resolves when the change has been applied by the server, and the [`appliedGiftCards`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/gift-cards#properties-propertydetail-appliedgiftcards) property updates with the new state. Unlike other write operations, gift card changes aren't gated by a cart instruction flag. **Caution:** \> See \security considerations\ if your extension retrieves gift card codes through a network call. **Note:** This method returns an error if the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay. ### GiftCardChange The input for \`applyGiftCardChange()\`. Pass either a \`GiftCardAddChange\` (with \`type: 'addGiftCard'\`) to apply a gift card or a \`GiftCardRemoveChange\` (with \`type: 'removeGiftCard'\`) to remove it. ```ts GiftCardAddChange | GiftCardRemoveChange ``` ### GiftCardAddChange Applies a gift card to the checkout. Pass this to \`applyGiftCardChange()\` to add a gift card. * code The full gift card code to apply to the checkout. ```ts string ``` * type Identifies this as a gift card addition. Set this when creating a change to apply a gift card to the checkout. ```ts 'addGiftCard' ``` ### GiftCardRemoveChange Removes a gift card from the checkout. Pass this to \`applyGiftCardChange()\` to remove a gift card. * code The gift card code to remove. You can pass either the full code or just the last four characters. ```ts string ``` * type Identifies this as a gift card removal. Set this when creating a change to remove a gift card from the checkout. ```ts 'removeGiftCard' ``` ### GiftCardChangeResult The result of calling \`applyGiftCardChange()\`. Use the \`type\` property to determine whether the change succeeded or failed. ```ts GiftCardChangeResultSuccess | GiftCardChangeResultError ``` ### GiftCardChangeResultSuccess The result of a successful gift card change. The \`type\` property is \`'success'\`. * type Indicates that the gift card change was applied successfully. ```ts 'success' ``` ### GiftCardChangeResultError The result of a failed gift card 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. Render your own localized error text rather than displaying this message to the buyer. ```ts string ``` * type Indicates that the gift card change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` Examples ### Examples * #### ##### Description List each gift card applied to the checkout. This example displays the last four characters and amount deducted for each card. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const giftCards = shopify.appliedGiftCards.value; if (giftCards.length === 0) { return null; } return ( Applied gift cards: {giftCards.map((card) => ( •••• {card.lastCharacters} -{card.amountUsed.amount}{' '} {card.amountUsed.currencyCode} ))} ); } ``` * #### ##### Description Redeem a gift card code during checkout. This example calls \`shopify.applyGiftCardChange\` with a code and displays a success banner when the card is accepted. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useState} from 'preact/hooks'; export default function extension() { render(, document.body); } function Extension() { const [applied, setApplied] = useState(false); async function applyGiftCard() { const result = await shopify.applyGiftCardChange({ type: 'addGiftCard', code: 'SHOP-1234-5678-9012', }); if (result.type === 'error') { console.error(result.message); } else { setApplied(true); } } if (applied) { return ( Gift card applied! ); } return ( A gift card is available for this order. Apply gift card ); } ``` *** ## Best practices * **Treat gift card codes as sensitive data**: Gift card codes function as payment credentials. Use caution if your extension retrieves codes from an external source, and avoid logging or transmitting them unnecessarily. * **Show remaining balance for transparency**: Each `AppliedGiftCard` includes both `amountUsed` (the amount deducted at checkout) and `balance` (the card's remaining value before checkout). Display both to help buyers understand their gift card value. * **Protect network-retrieved codes**: If your extension retrieves gift card codes through a network call, review the [security considerations](https://shopify.dev/docs/apps/build/checkout/capabilities#network-access) to protect against code interception. *** ## Limitations * Gift card changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay. ***