Choose a version:

Gift Cards API

The Gift Cards API provides access to gift cards applied to the checkout. Use this API to display applied gift cards, apply new gift card codes, and show the amount deducted from each card.

Anchor to Use casesUse cases

Display applied gift cards: Show each gift card's last four characters and the amount deducted.
Apply a gift card: Let buyers enter a gift card code and submit it during checkout.
Show gift card deductions: Display how much each gift card contributes to the checkout total.

Support

Targets (31)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides gift card data for the current checkout. Access the following properties on shopify to read applied gift cards. Available to purchase extension targets.

Anchor to appliedGiftCards appliedGiftCards <[]> 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.
```
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'

Anchor to MethodsMethods

The shopify global object provides methods to modify gift card data. Access the following methods on shopify to apply or remove gift cards. Available to purchase.checkout extension targets.

Anchor to applyGiftCardChange applyGiftCardChange (change: ) => 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 property updates with the new state.

Unlike other write operations, gift card changes aren't gated by a cart instruction flag.

Caution
> See security considerations if your extension retrieves gift card codes through a network call.
Caution: > See <a href="/docs/api/checkout-ui-extensions/2025-10/configuration#network-access">security considerations</a> 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.
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.

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.
```
string
```
type
Identifies this as a gift card addition. Set this when creating a change to apply a gift card to the checkout.
```
'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.
```
string
```
type
Identifies this as a gift card removal. Set this when creating a change to remove a gift card from the checkout.
```
'removeGiftCard'
```

GiftCardChangeResult

The result of calling `applyGiftCardChange()`. Use the `type` property to determine whether the change succeeded or failed.

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.
```
'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. Render your own localized error text rather than displaying this message to the buyer.
```
string
```
type
Indicates that the gift card change couldn't be applied. Check the `message` property for details.
```
'error'
```

Examples

jsx

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

import {render} from 'preact';

export default function extension() {

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

}

function Extension() {

const giftCards = shopify.appliedGiftCards.value;

if (giftCards.length === 0) {

return null;

}

return (

<s-stack>

<s-text type="strong">

Applied gift cards:

</s-text>

{giftCards.map((card) => (

<s-stack

key={card.lastCharacters}

direction="inline"

gap="small-200"

<s-text>

•••• {card.lastCharacters}

</s-text>

<s-text>

-{card.amountUsed.amount}{' '}

{card.amountUsed.currencyCode}

</s-text>

</s-stack>

))}

</s-stack>

);

}

Examples

Description

List each gift card applied to the checkout. This example displays the last four characters and amount deducted for each card.

jsx

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

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

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

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

  return (
    <s-stack>
      <s-text type="strong">
        Applied gift cards:
      </s-text>
      {giftCards.map((card) => (
        <s-stack
          key={card.lastCharacters}
          direction="inline"
          gap="small-200"
        >
          <s-text>
            •••• {card.lastCharacters}
          </s-text>
          <s-text>
            -{card.amountUsed.amount}{' '}
            {card.amountUsed.currencyCode}
          </s-text>
        </s-stack>
      ))}
    </s-stack>
  );
}

Description

Redeem a gift card code during checkout. This example calls `shopify.applyGiftCardChange` with a code and displays a success banner when the card is accepted.

jsx

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

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

function Extension() {
  const [applied, setApplied] = useState(false);

  async function applyGiftCard() {
    const result =
      await shopify.applyGiftCardChange({
        type: 'addGiftCard',
        code: 'SHOP-1234-5678-9012',
      });

    if (result.type === 'error') {
      console.error(result.message);
    } else {
      setApplied(true);
    }
  }

  if (applied) {
    return (
      <s-banner tone="success">
        Gift card applied!
      </s-banner>
    );
  }

  return (
    <s-stack>
      <s-text>
        A gift card is available for this order.
      </s-text>
      <s-button onClick={applyGiftCard}>
        Apply gift card
      </s-button>
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Treat gift card codes as sensitive data: Gift card codes function as payment credentials. Use caution if your extension retrieves codes from an external source, and avoid logging or transmitting them unnecessarily.
Show remaining balance for transparency: Each AppliedGiftCard includes both amountUsed (the amount deducted at checkout) and balance (the card's remaining value before checkout). Display both to help buyers understand their gift card value.
Protect network-retrieved codes: If your extension retrieves gift card codes through a network call, review the security considerations to protect against code interception.

Anchor to LimitationsLimitations

Gift card changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay.

Was this page helpful?