--- title: Gift Cards API description: >- The Gift Cards API provides the gift cards applied to the order, including the amount used and remaining balance. Use it to display gift card payment details or summarize gift card usage on the Order status page. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/gift-cards-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/gift-cards-api.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # Gift Cards API The Gift Cards API provides the gift cards applied to the order, including the amount used and remaining balance. Use it to display gift card payment details or summarize gift card usage on the Order status page. ### 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/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) ### Properties The Gift Cards API object provides the gift cards applied to the order. Access the following properties on the API object to read gift card data. * **appliedGiftCards** **StatefulRemoteSubscribable\** **required** Gift cards that have been applied to the order. Each entry includes the amount used and the remaining balance. ### AppliedGiftCard * amountUsed The amount of the gift card that was applied to this order. ```ts Money ``` * balance The remaining balance on the gift card after the applied amount is deducted. ```ts Money ``` * lastCharacters The last four characters of the gift card code, used to identify the card without exposing the full code. ```ts string ``` ### Money * amount The decimal money amount, such as \`29.99\`. ```ts number ``` * currencyCode The \[ISO 4217]\(https://www\.iso.org/iso-4217-currency-codes.html) currency code. ```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 Read the applied gift cards from the order and display each card with its last four characters and amount used. This example uses the \`useAppliedGiftCards\` hook and iterates over the gift card array. ##### React ```tsx import { reactExtension, useAppliedGiftCards, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const giftCards = useAppliedGiftCards(); if (giftCards.length === 0) { return null; } return ( Gift cards applied {giftCards.map((card) => ( •••• {card.lastCharacters} — Used:{' '} {card.amountUsed.amount}{' '} {card.amountUsed.currencyCode} ))} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const giftCards = api.appliedGiftCards.current; if (giftCards.length === 0) return; const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent(Text, {emphasis: 'bold'}, 'Gift cards applied'), ); for (const card of giftCards) { stack.appendChild( root.createComponent( Text, {}, `•••• ${card.lastCharacters} — Used: ${card.amountUsed.amount} ${card.amountUsed.currencyCode}`, ), ); } root.appendChild(stack); }, ); ``` * #### ##### Description Read each applied gift card and display the remaining balance after the order. This example uses \`useAppliedGiftCards\` to access the \`balance\` property on each gift card. ##### React ```tsx import { reactExtension, useAppliedGiftCards, useI18n, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const giftCards = useAppliedGiftCards(); const i18n = useI18n(); if (giftCards.length === 0) { return null; } return ( Gift card balances {giftCards.map((card) => { const currency = card.balance.currencyCode; return ( •••• {card.lastCharacters} — Remaining:{' '} {i18n.formatCurrency(card.balance.amount, { currency, })} ); })} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const giftCards = api.appliedGiftCards.current; if (giftCards.length === 0) return; const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent(Text, {emphasis: 'bold'}, 'Gift card balances'), ); for (const card of giftCards) { const currency = card.balance.currencyCode; stack.appendChild( root.createComponent( Text, {}, `•••• ${card.lastCharacters} — Remaining: ${api.i18n.formatCurrency(card.balance.amount, {currency})}`, ), ); } root.appendChild(stack); }, ); ``` * #### ##### Description Calculate the total amount paid with gift cards and display a summary. This example sums the \`amountUsed\` property across all applied gift cards. ##### React ```tsx import { reactExtension, useAppliedGiftCards, useI18n, } from '@shopify/ui-extensions-react/customer-account'; import { Banner, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const giftCards = useAppliedGiftCards(); const i18n = useI18n(); if (giftCards.length === 0) { return null; } const totalUsed = giftCards.reduce( (sum, card) => sum + card.amountUsed.amount, 0, ); const currency = giftCards[0].amountUsed.currencyCode; return ( {giftCards.length} gift card {giftCards.length !== 1 ? 's' : ''} applied for a total of{' '} {i18n.formatCurrency(totalUsed, {currency})}. ); } ``` ##### TS ```ts import { extension, Banner, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const giftCards = api.appliedGiftCards.current; if (giftCards.length === 0) return; const totalUsed = giftCards.reduce( (sum, card) => sum + card.amountUsed.amount, 0, ); const currency = giftCards[0].amountUsed.currencyCode; const banner = root.createComponent(Banner, {status: 'info'}); banner.appendChild( root.createComponent( Text, {}, `${giftCards.length} gift card${giftCards.length !== 1 ? 's' : ''} applied for a total of ${api.i18n.formatCurrency(totalUsed, {currency})}.`, ), ); root.appendChild(banner); }, ); ``` *** ## Best practices * **Only show the last four characters**: The `lastCharacters` property provides a safe identifier for display. Don't attempt to display or store full gift card codes. * **Show remaining balance**: Display the `balance` alongside the `amountUsed` so buyers know how much is left on their gift card. *** ## Limitations * The full gift card code is never exposed. Only the last four characters are available through `lastCharacters`. * The `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. ***