# Gift Cards

The API for interacting with gift cards.

## StandardApi

The base API object provided to `purchase`, and `customer-account.order-status` extension targets.

### Docs_Standard_GiftCardsApi

### appliedGiftCards

value: `StatefulRemoteSubscribable<AppliedGiftCard[]>`

Gift Cards that have been applied to the checkout.

### AppliedGiftCard

### lastCharacters

value: `string`

The last four characters of the applied gift card's code.

### amountUsed

value: `Money`

The amount of the applied gift card that will be used when the checkout is completed.

### balance

value: `Money`

The current balance of the applied gift card prior to checkout completion.

### Money

### amount

value: `number`

The price amount.

### currencyCode

value: `CurrencyCode`

The ISO 4217 format for the currency.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## CheckoutApi

The API object provided to `purchase.checkout` extension targets.

### Docs_Checkout_GiftCardsApi

### applyGiftCardChange

value: `(change: GiftCardChange) => Promise<GiftCardChangeResult>`

Performs an update on the gift cards.
It resolves when gift card change have been negotiated and results in an update
to the value retrieved through the [`appliedGiftCards`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/gift-cards#standardapi-propertydetail-appliedgiftcards) property.

> Caution:
> See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access) if your extension retrieves gift card codes through a network call.

> Note: This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

### GiftCardAddChange

### type

value: `"addGiftCard"`

The type of the `GiftCardChange` API.

### code

value: `string`

Gift card code.

### GiftCardRemoveChange

### type

value: `"removeGiftCard"`

The type of the `GiftCardChange` API.

### code

value: `string`

Gift card code.

### GiftCardChangeResultSuccess

### type

value: `"success"`

Indicates that the gift card change was applied successfully.

### GiftCardChangeResultError

### type

value: `"error"`

Indicates that the gift card change failed.

### message

value: `string`

A message that explains the error. This message is useful for debugging.
It is **not** localized, and therefore should not be presented directly
to the buyer.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## useAppliedGiftCards

Returns the current gift cards applied to the cart.

### UseAppliedGiftCardsGeneratedType

Returns the current gift cards applied to the cart, and automatically re-renders
your component if gift cards are added or removed.

#### Returns: AppliedGiftCard[]
export function useAppliedGiftCards<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): AppliedGiftCard[] {
  const {appliedGiftCards} = useApi<Target>();

  return useSubscription(appliedGiftCards);
}


### AppliedGiftCard

### lastCharacters

value: `string`

The last four characters of the applied gift card's code.

### amountUsed

value: `Money`

The amount of the applied gift card that will be used when the checkout is completed.

### balance

value: `Money`

The current balance of the applied gift card prior to checkout completion.

### Money

### amount

value: `number`

The price amount.

### currencyCode

value: `CurrencyCode`

The ISO 4217 format for the currency.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)

## useApplyGiftCardChange

Returns a function to add or remove gift cards.

### UseApplyGiftCardChangeGeneratedType

Returns a function to add or remove gift cards.

> Caution:
> See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access) if your extension retrieves gift card codes through a network call.

#### Returns: (change: GiftCardChange) => Promise<GiftCardChangeResult>
export function useApplyGiftCardChange<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): (change: GiftCardChange) => Promise<GiftCardChangeResult> {
  const api = useApi<Target>();

  if ('applyGiftCardChange' in api) {
    return api.applyGiftCardChange;
  }

  throw new ExtensionHasNoMethodError(
    'applyGiftCardChange',
    api.extension.target,
  );
}


### GiftCardAddChange

### type

value: `"addGiftCard"`

The type of the `GiftCardChange` API.

### code

value: `string`

Gift card code.

### GiftCardRemoveChange

### type

value: `"removeGiftCard"`

The type of the `GiftCardChange` API.

### code

value: `string`

Gift card code.

### GiftCardChangeResultSuccess

### type

value: `"success"`

Indicates that the gift card change was applied successfully.

### GiftCardChangeResultError

### type

value: `"error"`

Indicates that the gift card change failed.

### message

value: `string`

A message that explains the error. This message is useful for debugging.
It is **not** localized, and therefore should not be presented directly
to the buyer.

## Related

- [Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)
- [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)
- [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
- [Tutorials](/apps/checkout)