Skip to content

Headless Integration

Gift Card Hero supports headless Shopify storefronts that do not use Shopify's standard theme system. Enable headless mode to get an integration code snippet you embed in your custom storefront.

Step 1: Enable headless mode

Go to For developers in the left navigation. In the Headless mode card, click Enable headless mode. The status badge changes to Enabled. Click Save in the save bar to keep it.

Enable headless mode

Step 2: Copy the integration code

Once headless mode is enabled, a code snippet appears on the page. Click Copy to clipboard. The snippet contains an empty <div id="sc-giftcard-builder">, a configuration block and the Gift Card Hero storefront script. Add it to your gift card product page.

Integration code snippet

Step 3: Replace placeholders

The code snippet contains placeholder values that you must replace with your store's specific information:

Placeholder Replace with Example
[MONEY_FORMAT] Your store's money format string ${{amount}}
[PRODUCT_ID] Your gift card product's Shopify numeric ID 7654321098765
[MYSHOPIFY_DOMAIN] Your store's .myshopify.com address my-store.myshopify.com
[ADD_TO_CART_CALLBACK] A JavaScript function that handles adding items to the cart addItemToCart
[LOCALE] The locale code of your translations en

[PRODUCT_ID] is a number and has no quotes in the snippet. The others sit inside quotes. Replace '[ADD_TO_CART_CALLBACK]' together with its quotes by your function (for example addToCart: addItemToCart), because Gift Card Hero calls it as a function.

Money format

The money format string determines how prices are displayed. The page shows your store's own money format as an example next to the placeholder. See Shopify's currency formatting guide for the format codes.

Common formats:

  • ${{amount}} — US dollars
  • {{amount}} EUR — Euros
  • ${{amount}} CAD — Canadian dollars

Product ID

To find your gift card product's Shopify ID:

  1. Open Shopify Admin
  2. Go to Products
  3. Click on your gift card product
  4. Look at the URL in your browser's address bar — the numeric ID is at the end

For example, if the URL is https://admin.shopify.com/store/my-store/products/7654321098765, the product ID is 7654321098765.

Add to cart callback

The [ADD_TO_CART_CALLBACK] placeholder should be replaced with a JavaScript function name that your storefront uses to add items to the cart. Gift Card Hero calls it with one object and expects a promise back:

function addItemToCart({ items, sections }) {
  // items: [{ id: <variant id>, quantity: 1, properties: { ... } }]
  // Add the line to your cart (for example a Storefront API cart) and return a promise.
}

properties holds the buyer's choices (message, sender, recipient, delivery date and the card design data). Pass all of them to your cart line unchanged so the gift card is created correctly. If the function is missing, adding to the cart fails with "Add to cart method is not defined in headless mode".

Locale

The [LOCALE] placeholder sets the language of the Gift Card Hero interface. Use the code of a language you have set up in the app's translations, written exactly the same (for example en or fr). Defaults to en if omitted.

How the snippet gets its settings

When the page loads, the storefront script requests your gift card settings, the product and your translations from https://gifthero.syncu.be/api/configuration/headless, using your [MYSHOPIFY_DOMAIN], [PRODUCT_ID] and [LOCALE]. It needs no login. The answer is cached for about a minute, and saving your settings in the app refreshes it.

If the product ID is wrong, the request fails with Product id is incorrect and nothing is shown. If the money format, product ID or shop is missing from the snippet, the script reports it in the browser console.

Custom amounts

If you sell custom-amount gift cards, the amount must stay between the minimum and maximum you set in the app; the server refuses amounts outside them. When the checkout is created through Gift Card Hero, the server rebuilds the order from your settings, so the price cannot be changed from the browser. In this flow the buyer is sent to the checkout link that the server returns, instead of your add-to-cart function being called.

After integration

Once the snippet is embedded and placeholders are replaced, Gift Card Hero renders its gift card selection interface on your storefront. To build your own interface instead of the app's gift card builder, also tick Enable storefront API on the For developers page. The builder is then not shown, and the Storefront API (window.GiftHeroAPI) is loaded for you to drive.