--- title: Gift Cards API description: The API for interacting with gift cards. 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 API for interacting with gift cards. ### Support Targets (31) ### 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 ## StandardApi The base API object provided 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' ``` ## CheckoutApi The API object provided 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/2026-04/apis/gift-cards#standardapi-propertydetail-appliedgiftcards) property updates with the new state. **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. ```ts string ``` * type Indicates that the gift card change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` ## use​Applied​Gift​Cards() Returns the current gift cards applied to the cart. ### Returns * **AppliedGiftCard\[]** ## use​Apply​Gift​Card​Change() Returns a function to add or remove gift cards. ### Returns * **(change: GiftCardChange) => Promise\** ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)