Storefront API¶

The Storefront API provides a JavaScript interface (window.GiftHeroAPI) for building custom gift card selection and purchase flows on your storefront.

Storefront API configuration

Enable the API¶

Go to For developers in the left navigation.
Tick Enable storefront API and save.

The gift card interface that the app generates on your gift card product page is switched off, and window.GiftHeroAPI is loaded instead. You build the interface.

The API does not read gift card balances. It collects the buyer's choices and adds the gift card to the cart.

Headless storefronts

On a headless storefront, the API is loaded when headless mode and Enable storefront API are both on. See Headless Integration.

Initialization¶

The API loads asynchronously. Gift Card Hero fires an event on window when it is ready. Listen for it before calling any methods:

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

The event name is spelled initalized

The event name has a typo: gift.hero:initalized (no second "i"). Use it exactly as written. The event fires on window, not on document, after the Gift Card Hero storefront script has loaded. If the script is not on the page, or the storefront API is off, the event does not fire.

When the API starts, it selects the first variant (or the variant in the ?variant= URL parameter) and the first image.

Methods¶

addToCart(quantity?, skipValidation?)¶

Validates the card data and adds the configured gift card to the cart with Shopify's /cart/add.js.

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

Parameter	Type	Default	Description
`quantity`	number	1	Number of gift cards to add
`skipValidation`	boolean	false	Add the card even if `validate()` reports errors

Returns: a promise with the Shopify cart response ({ status, data }). It rejects with { status: 400, data: { errors } } when validation fails.

generatePreview()¶

Opens a preview showing how the gift card will look to the recipient, using the data set so far.

window.GiftHeroAPI.generatePreview();

getImages()¶

Returns an array of image URLs available for the gift card: your own designs, the selected built-in designs and, if enabled, the product images.

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

Returns the product options, including the available denominations.

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

Returns the interface translations for the current language, such as the labels and the validation message.

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

Returns the product variants array.

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

Sets all gift card data at once.

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

Field	Type	Description
`variantId`	number	The selected variant ID
`image`	string	URL of the selected card image
`message`	string	Gift card message
`from`	string	Sender's name
`to`	string	Recipient's name (optional)
`deliveryDate`	`Date`	Scheduled delivery date, as a JavaScript `Date` object (optional)
`email`	string	Recipient's email address (optional)

SMS delivery is not available through the API, so there is no phone field.

Individual setters¶

Method	Parameter	Description
`setDeliveryDate(date)`	`Date`	Set scheduled delivery date. Throws an error if it is not a valid date object
`setEmail(email)`	string	Set recipient email
`setFrom(name)`	string	Set sender name
`setTo(name)`	string	Set recipient name
`setImage(image)`	string	Set selected card image URL
`setMessage(message)`	string	Set gift card message
`setVariant(variantId)`	number or string	Set selected variant
`setProperty(name, value)`	string, string	Add an extra line item property to the cart line

validate()¶

Checks the current gift card data and returns { valid, errors }, where errors is an array of messages built from your translations.

const { valid, errors } = window.GiftHeroAPI.validate();

Validation rules:

If a recipient email is set, the delivery date, the sender name (from) and the message are required.
If a delivery date is set, the recipient email, the sender name and the message are required.
With no email and no delivery date, nothing is required.

setCustomAmount(amount)¶

Selects a custom amount, in your store currency (for example 75 for 75.00). It works only when custom amounts are turned on for your store; otherwise it throws Custom amount is not enabled. The method does not check your minimum and maximum, so validate the amount yourself.

window.GiftHeroAPI.setCustomAmount(75);

Physical gift cards¶

If you sell physical gift cards, switch the API to them with setCardType('physical') (use setCardType('eGift') to go back).

Method	Description
`setCardType(type)`	`'eGift'` or `'physical'`. Selecting `'physical'` picks the first physical variant and image
`getPhysicalProduct()`	The physical gift card product
`getPhysicalVariants()`	Variants of the physical product
`getPhysicalImages()`	Image URLs of the physical product
`setPhysicalVariant(variantId)`	Select a physical variant (physical type only)
`setPhysicalDeliveryAddress(address)`	Set the delivery address (physical type only): `firstName`, `lastName`, `address`, `zipCode`, `city`, `country`, and optional `state`
`isPhysicalCard()`	`true` when the physical type is selected

uploadCustomDesign(file, options?)¶

Uploads a buyer's own image and returns its URL, which you can pass to setImage().

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

The file must be a JPG, PNG, GIF or WebP image, up to 5 MB by default. You can change the limits with options.maxSize (bytes) and options.allowedTypes. The method throws an error with a clear message when the file is refused.

React integration example¶

A complete React integration example is available on JSFiddle. It demonstrates how to initialize the API, build a custom gift card selection UI, and handle the add-to-cart flow:

View React Example on JSFiddle