Choose a version:

Gift Cards API

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.

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.

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 shopify global object 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.

Anchor to appliedGiftCards appliedGiftCards <[]> 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.
```
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.
```
() => Promise<void>
```
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.
```
(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.
```
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.
```
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.
```
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.
```
string
```

Money

amount
The decimal amount of the price. For example, `29.99` represents twenty-nine dollars and ninety-nine cents.
```
number
```
currencyCode
The three-letter currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
```
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

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const giftCards =

shopify.appliedGiftCards.value;

if (giftCards.length === 0) {

return null;

}

return (

<s-box>

<s-text type="strong">

Applied gift cards

</s-text>

{giftCards.map((card) => (

<s-text key={card.lastCharacters}>

Gift card ending in ••••

{card.lastCharacters} —{' '}

{card.amountUsed.amount}{' '}

{card.amountUsed.currencyCode}

</s-text>

))}

</s-box>

);

}

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

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const giftCards =
    shopify.appliedGiftCards.value;

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

  return (
    <s-box>
      <s-text type="strong">
        Applied gift cards
      </s-text>
      {giftCards.map((card) => (
        <s-text key={card.lastCharacters}>
          Gift card ending in ••••
          {card.lastCharacters} —{' '}
          {card.amountUsed.amount}{' '}
          {card.amountUsed.currencyCode}
        </s-text>
      ))}
    </s-box>
  );
}

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

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const giftCards =
    shopify.appliedGiftCards.value;

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

  return (
    <s-box>
      {giftCards.map((card) => (
        <s-box key={card.lastCharacters}>
          <s-text type="strong">
            Gift card ••••{card.lastCharacters}
          </s-text>
          <s-stack direction="inline">
            <s-text>
              Used: {card.amountUsed.amount}{' '}
              {card.amountUsed.currencyCode}
            </s-text>
            <s-text color="subdued">
              Remaining: {card.balance.amount}{' '}
              {card.balance.currencyCode}
            </s-text>
          </s-stack>
        </s-box>
      ))}
    </s-box>
  );
}

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

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, 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 (
    <s-box>
      <s-text type="strong">
        Payment summary
      </s-text>
      <s-divider />
      {giftCards.map((card) => (
        <s-stack
          key={card.lastCharacters}
          direction="inline"
        >
          <s-text>
            Gift card ••••{card.lastCharacters}
          </s-text>
          <s-text>
            -{card.amountUsed.amount}{' '}
            {card.amountUsed.currencyCode}
          </s-text>
        </s-stack>
      ))}
      {giftCards.length > 0 && <s-divider />}
      <s-stack direction="inline">
        <s-text type="strong">
          Total
        </s-text>
        <s-text type="strong">
          {totalAmount.amount}{' '}
          {totalAmount.currencyCode}
        </s-text>
      </s-stack>
    </s-box>
  );
}

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

Anchor to LimitationsLimitations

The full gift card code is never exposed. Only the last four characters are available through lastCharacters.

Was this page helpful?