Migrate to Polaris

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.

Choose a version:

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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

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.

Anchor to appliedGiftCards 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.
```
Money
```
balance
The remaining balance on the gift card after the applied amount is deducted.
```
Money
```
lastCharacters
The last four characters of the gift card code, used to identify the card without exposing the full code.
```
string
```

Money

amount
The decimal money amount, such as `29.99`.
```
number
```
currencyCode
The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
```
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'

Examples

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',

() => <Extension />,

);

function Extension() {

const giftCards = useAppliedGiftCards();

if (giftCards.length === 0) {

return null;

}

return (

<Text emphasis="bold">Gift cards applied</Text>

{giftCards.map((card) => (

•••• {card.lastCharacters} — Used:{' '}

{card.amountUsed.amount}{' '}

{card.amountUsed.currencyCode}

</Text>

))}

</BlockStack>

);

}

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

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',
  () => <Extension />,
);

function Extension() {
  const giftCards = useAppliedGiftCards();

  if (giftCards.length === 0) {
    return null;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Gift cards applied</Text>
      {giftCards.map((card) => (
        <Text key={card.lastCharacters}>
          •••• {card.lastCharacters} — Used:{' '}
          {card.amountUsed.amount}{' '}
          {card.amountUsed.currencyCode}
        </Text>
      ))}
    </BlockStack>
  );
}

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

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',
  () => <Extension />,
);

function Extension() {
  const giftCards = useAppliedGiftCards();
  const i18n = useI18n();

  if (giftCards.length === 0) {
    return null;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Gift card balances</Text>
      {giftCards.map((card) => {
        const currency = card.balance.currencyCode;
        return (
          <Text key={card.lastCharacters}>
            •••• {card.lastCharacters} — Remaining:{' '}
            {i18n.formatCurrency(card.balance.amount, {
              currency,
            })}
          </Text>
        );
      })}
    </BlockStack>
  );
}

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

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',
  () => <Extension />,
);

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 (
    <Banner status="info">
      <Text>
        {giftCards.length} gift card
        {giftCards.length !== 1 ? 's' : ''} applied
        for a total of{' '}
        {i18n.formatCurrency(totalUsed, {currency})}.
      </Text>
    </Banner>
  );
}

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);
  },
);

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?