Gift CardsAPI
The API for interacting with gift cards.
Anchor to standardapiStandardApi
The base API object provided to purchase
, and customer-account.order-status
extension targets.
- Anchor to appliedGiftCardsappliedGiftCardsStatefulRemoteSubscribable<AppliedGiftCard[]>required
Gift Cards that have been applied to the checkout.
Docs_Standard_GiftCardsApi
- appliedGiftCards
Gift Cards that have been applied to the checkout.
StatefulRemoteSubscribable<AppliedGiftCard[]>
export interface Docs_Standard_GiftCardsApi
extends Pick<StandardApi, 'appliedGiftCards'> {}
AppliedGiftCard
- lastCharacters
The last four characters of the applied gift card's code.
string
- amountUsed
The amount of the applied gift card that will be used when the checkout is completed.
Money
- balance
The current balance of the applied gift card prior to checkout completion.
Money
export interface AppliedGiftCard {
/**
* The last four characters of the applied gift card's code.
*/
lastCharacters: string;
/**
* The amount of the applied gift card that will be used when the checkout is completed.
*/
amountUsed: Money;
/**
* The current balance of the applied gift card prior to checkout completion.
*/
balance: Money;
}
Money
- amount
The price amount.
number
- currencyCode
The ISO 4217 format for the currency.
CurrencyCode
export interface Money {
/**
* The price amount.
*/
amount: number;
/**
* The ISO 4217 format for the currency.
* @example 'CAD' for Canadian dollar
*/
currencyCode: 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 checkoutapiCheckoutApi
The API object provided to purchase.checkout
extension targets.
- Anchor to applyGiftCardChangeapplyGiftCardChange(change: GiftCardChange) => Promise<GiftCardChangeResult>required
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
property.
CautionSee security considerations if your extension retrieves gift card codes through a network call.
NoteThis method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Docs_Checkout_GiftCardsApi
- applyGiftCardChange
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`](/docs/api/checkout-ui-extensions/apis/gift-cards#standardapi-propertydetail-appliedgiftcards) property. > Caution: > See [security considerations](/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.
(change: GiftCardChange) => Promise<GiftCardChangeResult>
export interface Docs_Checkout_GiftCardsApi
extends Pick<CheckoutApi, 'applyGiftCardChange'> {}
GiftCardChange
GiftCardAddChange | GiftCardRemoveChange
GiftCardAddChange
- type
The type of the `GiftCardChange` API.
"addGiftCard"
- code
Gift card code.
string
export interface GiftCardAddChange {
/**
* The type of the `GiftCardChange` API.
*/
type: 'addGiftCard';
/**
* Gift card code.
*/
code: string;
}
GiftCardRemoveChange
- type
The type of the `GiftCardChange` API.
"removeGiftCard"
- code
Gift card code.
string
export interface GiftCardRemoveChange {
/**
* The type of the `GiftCardChange` API.
*/
type: 'removeGiftCard';
/**
* Gift card code.
*/
code: string;
}
GiftCardChangeResult
GiftCardChangeResultSuccess | GiftCardChangeResultError
GiftCardChangeResultSuccess
- type
Indicates that the gift card change was applied successfully.
"success"
export interface GiftCardChangeResultSuccess {
/**
* Indicates that the gift card change was applied successfully.
*/
type: 'success';
}
GiftCardChangeResultError
- type
Indicates that the gift card change failed.
"error"
- message
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.
string
export interface GiftCardChangeResultError {
/**
* Indicates that the gift card change failed.
*/
type: 'error';
/**
* 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.
*/
message: string;
}
Anchor to useAppliedGiftCardsuse Applied Gift Cards()
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.
AppliedGiftCard[]
export function useAppliedGiftCards<
Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): AppliedGiftCard[] {
const {appliedGiftCards} = useApi<Target>();
return useSubscription(appliedGiftCards);
}
AppliedGiftCard
- lastCharacters
The last four characters of the applied gift card's code.
string
- amountUsed
The amount of the applied gift card that will be used when the checkout is completed.
Money
- balance
The current balance of the applied gift card prior to checkout completion.
Money
export interface AppliedGiftCard {
/**
* The last four characters of the applied gift card's code.
*/
lastCharacters: string;
/**
* The amount of the applied gift card that will be used when the checkout is completed.
*/
amountUsed: Money;
/**
* The current balance of the applied gift card prior to checkout completion.
*/
balance: Money;
}
Money
- amount
The price amount.
number
- currencyCode
The ISO 4217 format for the currency.
CurrencyCode
export interface Money {
/**
* The price amount.
*/
amount: number;
/**
* The ISO 4217 format for the currency.
* @example 'CAD' for Canadian dollar
*/
currencyCode: 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 useApplyGiftCardChangeuse Apply Gift Card Change()
Returns a function to add or remove gift cards.
UseApplyGiftCardChangeGeneratedType
Returns a function to add or remove gift cards. > Caution: > See [security considerations](/docs/api/checkout-ui-extensions/configuration#network-access) if your extension retrieves gift card codes through a network call.
(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,
);
}
GiftCardChange
GiftCardAddChange | GiftCardRemoveChange
GiftCardAddChange
- type
The type of the `GiftCardChange` API.
"addGiftCard"
- code
Gift card code.
string
export interface GiftCardAddChange {
/**
* The type of the `GiftCardChange` API.
*/
type: 'addGiftCard';
/**
* Gift card code.
*/
code: string;
}
GiftCardRemoveChange
- type
The type of the `GiftCardChange` API.
"removeGiftCard"
- code
Gift card code.
string
export interface GiftCardRemoveChange {
/**
* The type of the `GiftCardChange` API.
*/
type: 'removeGiftCard';
/**
* Gift card code.
*/
code: string;
}
GiftCardChangeResult
GiftCardChangeResultSuccess | GiftCardChangeResultError
GiftCardChangeResultSuccess
- type
Indicates that the gift card change was applied successfully.
"success"
export interface GiftCardChangeResultSuccess {
/**
* Indicates that the gift card change was applied successfully.
*/
type: 'success';
}
GiftCardChangeResultError
- type
Indicates that the gift card change failed.
"error"
- message
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.
string
export interface GiftCardChangeResultError {
/**
* Indicates that the gift card change failed.
*/
type: 'error';
/**
* 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.
*/
message: string;
}