Skip to content

Developer Tools

The For developers page provides API access, webhook configuration, headless mode, and advanced integration options. Open it from For developers in the left navigation.

Changes to checkboxes and webhook URLs on this page are applied when you click Save in the save bar. The token buttons and Generate Secret act immediately. Enable headless mode also needs Save.

Developer tools


Storefront API

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

  • Enable storefront API — turn on to load the JavaScript API on your gift card product page. The gift card interface generated by the app is switched off on that page, so your developer builds the interface instead.
  • Disable gift card page animation — appears once the storefront API is on. Removes the app's animated gift card page, so you can build a custom gift card page.

The API does not read balances. It collects the gift card choices (amount, design, message, recipient) and adds the gift card to the cart.

Full API reference: Storefront API


REST API

The REST API lets you integrate Gift Card Hero with external systems — CRMs, analytics dashboards, loyalty platforms, and more.

Enabling

Tick Enable REST API and save. Then click Send me access token — Gift Card Hero sends the API access token to the shop contact email address shown on the page.

Your store has one API token at a time, shared by every integration that uses it:

  • Send me access token issues a new token. The previous one stops working immediately, so update your integrations with the new token. To look the token up again, find the earlier email instead.
  • Revoke access token disables the current token without issuing a new one — use it if the token may have leaked or a partner no longer needs access.
  • Turning Enable REST API off also revokes the token.

Details: Managing your API token

A Postman collection link is available on the page for quick API exploration. Show available API endpoints lists the main endpoints on the page itself.

Available endpoints

Method Endpoint Description
POST /api/external/gift-cards Create a gift card
POST /api/external/gift-cards/{id}/disable Disable a gift card
GET /api/external/gift-cards List gift cards (filterable by status)
GET /api/external/gift-cards/{id} Get a single gift card
GET /api/external/gift-cards/search?query=... Search gift cards (for example last_characters:mnop)
PUT /api/external/gift-cards/{id} Update a gift card
PUT /api/external/gift-cards/{id}/balance Update a gift card's balance
POST /api/external/gift-cards/{id}/redeem Redeem a gift card from a POS or till app (sends the redemption notification, records the branch)
POST /api/external/gift-cards/{id}/resend Send the gift card email to its owner again
GET /api/external/customers/{customer_id}/gift-cards List a customer's gift cards, with each full code on record (for your own account page; call it from your server)
GET /api/external/gift-cards/transactions Gift cards with their transactions, paginated
POST /api/external/gift-cards/assign-to-order Assign your own gift card codes to an order

Full API reference: REST API Reference


Webhooks

Webhooks configuration

Gift Card Hero can send HTTP POST requests to your server when specific gift card events occur.

Webhook settings appear on this page once Enable REST API is on.

Setting up a webhook secret

Click Generate Secret to create a signing secret. Copy it from the banner right away — it is shown only once. Use it on your server to verify that incoming payloads come from Gift Card Hero. The signature is sent in the X-GiftHero-Signature header (HMAC-SHA256).

Click Regenerate Secret to rotate the secret, for example if it has leaked. The old secret stops working at once, so update your server with the new one.

Webhook endpoints

Configure your server URLs for these webhook types:

Field on the page When it fires
Order with gift card webhook URL Gift cards of an order are processed by Gift Card Hero
Gift card payment webhook URL An order is created that was paid with a gift card
Gift card balance webhook URL Not sent at the moment (see the integration guide)

Enter your endpoint URL in each field and save. A new or changed URL must start with https:// and be reachable from the internet; private-network addresses are refused when you save.

Full integration guide: Webhooks Integration Guide


Custom Code Editor

Add custom CSS to Gift Card Hero's storefront components without modifying your Shopify theme directly.

Click Open custom code editor. It opens the Custom code tab in Settings.

Custom code editor

Your CSS is added to the gift card product pages, the gift card page, and the pages of physical and custom-amount gift card products. It is not added to the rest of your store. Use it to adjust the look of the gift card builder and the gift card page. Click Save in the save bar to apply your changes.

CSS only

The editor accepts CSS only. CSS that contains </style is refused when you save. Custom JavaScript that was set up for your store before this change keeps working, but it can no longer be edited here. To change it, contact support.


Save Gift Card Data to Metafield

Tick Save a gift card data to a metafield to store the data of each gift card (design, message, sender) in a Shopify metafield on your shop:

  • Namespace: gift_hero
  • Key: cards_data

The data is keyed by the last four characters of the gift card code. This makes it available in Shopify email templates during gift card generation and in your own Liquid templates.

Disable gift card page animation for templates with suffix — turns off the app's gift card page for gift cards that have a template suffix set (see template_suffix in the REST API), so your own template is shown instead.


Headless Mode

Enable Headless Mode for custom or headless Shopify storefronts that don't use Shopify's standard theme system.

Click Enable headless mode (the status badge changes to Enabled). A code snippet appears with placeholder values you replace with your store's specifics:

Placeholder Replace with
[MONEY_FORMAT] Your store's money format string
[PRODUCT_ID] Your gift card product's Shopify numeric ID
[MYSHOPIFY_DOMAIN] Your store's .myshopify.com domain
[ADD_TO_CART_CALLBACK] Your custom add-to-cart JavaScript function
[LOCALE] The locale code of your translations (e.g., en, fr). en is the default

Copy the snippet and integrate it into your custom storefront codebase.

Full setup guide: Headless Integration Guide


Custom Fulfillment

This section appears only for stores that use the self-fulfillment option. With it, Gift Card Hero is fully responsible for creating and delivering the gift cards of an order, instead of Shopify's automatic gift card fulfillment.

Turn off automatic fulfillment in Shopify first

In your Shopify checkout (order processing) settings, choose Don't fulfill any of the order's line items automatically. The page links to Check settings and a Shopify guide. Do not fulfill gift cards in an order yourself — they must stay unfulfilled.

The badge shows the current status (Enabled or Disabled). Click Enable custom fulfilment or Disable custom fulfilment to switch.