--- title: Gift Cards API description: >- The Gift Cards API provides read-only access to the gift cards applied to an order on the Order status page. Use this API to display the masked gift card code, amount applied, and remaining balance for each card. api_version: 2026-04 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/gift-cards-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/gift-cards-api.md --- # Gift Cards API The Gift Cards API provides read-only access to the gift cards applied to an order on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status). Use this API to display the masked gift card code, amount applied, and remaining balance for each card. Gift card balance reflects the remaining amount at the time the order was placed. It doesn't update if the gift card is used for subsequent purchases. ### Use cases * **Display applied gift cards**: Show the buyer which gift cards were used for the order, identified by the last four characters of each code. * **Show amounts used**: Display how much of each gift card was applied to the order total. * **Show remaining balances**: Display the remaining balance on each gift card after the order was placed. ### Support Targets (10) ### Supported targets * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the gift cards applied to the order. Access the following properties on `shopify` to read which gift cards were used, how much was applied, and the remaining balance. * **appliedGiftCards** **SubscribableSignalLike\** **required** The gift cards that were applied to the order. Each gift card includes the last four characters of the code, the amount used for this order, and the 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' ``` Examples ### Examples * #### ##### Description Show which gift cards were used for the order, identified by the last four characters of each code. This example reads \`shopify.appliedGiftCards\` and renders the masked code alongside the amount used. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const giftCards = shopify.appliedGiftCards.value; if (giftCards.length === 0) { return null; } return ( Applied gift cards {giftCards.map((card) => ( Gift card ending in •••• {card.lastCharacters} —{' '} {card.amountUsed.amount}{' '} {card.amountUsed.currencyCode} ))} ); } ``` * #### ##### Description Display the amount used and remaining balance for each applied gift card. This example reads both \`amountUsed\` and \`balance\` on each gift card entry and formats them as currency values. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const giftCards = shopify.appliedGiftCards.value; if (giftCards.length === 0) { return null; } return ( {giftCards.map((card) => ( Gift card ••••{card.lastCharacters} Used: {card.amountUsed.amount}{' '} {card.amountUsed.currencyCode} Remaining: {card.balance.amount}{' '} {card.balance.currencyCode} ))} ); } ``` * #### ##### Description Display gift card deductions alongside the order total in a payment summary layout. This example combines gift card data from \`shopify.appliedGiftCards\` with the order total from \`shopify.cost.totalAmount\`. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const giftCards = shopify.appliedGiftCards.value; const totalAmount = shopify.cost.totalAmount.value; const giftCardTotal = giftCards.reduce( (sum, card) => sum + Number(card.amountUsed.amount), 0, ); return ( Payment summary {giftCards.map((card) => ( Gift card ••••{card.lastCharacters} -{card.amountUsed.amount}{' '} {card.amountUsed.currencyCode} ))} {giftCards.length > 0 && } Total {totalAmount.amount}{' '} {totalAmount.currencyCode} ); } ``` *** ## Best practices * **Show gift cards alongside other payment methods**: Gift cards are applied before other payment methods. Display gift card information in your payment summary to give buyers a complete view of how their order was paid. *** ## Limitations * The full gift card code is never exposed. Only the last four characters are available through `lastCharacters`. ***