For developers

Overview

The "For Developers" section provides advanced configuration options for store owners who want to customize their gift card functionality beyond the standard interface. This section allows you to enable APIs, configure webhooks, set up headless mode, and control custom fulfillment settings.


Important: Most features in this section require technical knowledge. We recommend working with a developer to implement these customizations.



Getting Started

Accessing Developer Settings

  1. Log into your Gift Card Hero app from your Shopify admin
  2. Navigate to the main menu and select "For developers"
  3. You'll see several configuration sections available

API Configuration

Storefront API

The Storefront API allows developers to create custom user interfaces for your gift card products.


How to Enable Storefront API

  1. In the APIs section, check "Enable storefront API"
  2. Click Save to apply changes


What happens when enabled:

  • The default gift card product interface generated by the app will be disabled
  • Developers can use custom JavaScript to create gift card interfaces
  • API methods are available for gift card operations

Documentation: Developers can find API methods and examples in the API documentation


Disable Gift Card Page Animation

When Storefront API is enabled, you can also:


  1. Check "Disable gift card page animation"
  2. This removes the default gift card page animation
  3. Allows developers to create completely custom gift card pages

REST API

Note: This feature is only available for stores outside of Shopify's internal testing environment.


How to Enable REST API

  1. In the APIs section, check "Enable REST API"
  2. Click Save to apply changes


What this provides:

  • Access to create, read, update, and delete gift card operations
  • Custom functionality beyond standard gift card features

Getting Your Access Token

  1. After enabling REST API, click "Send me access token"
  2. The access token will be emailed to your store's contact email
  3. Important: Save this token securely - it provides full access to your gift card data

Available API Endpoints

Click "Show available API endpoints" to see all REST API methods:


  • POST - Create gift cards
  • GET - Retrieve gift card lists and details
  • PUT - Update gift cards and balances
  • POST - Disable gift cards
  • GET - Search gift cards by criteria

Download: Use our Postman collection to test API endpoints.

You may find the API documentation here: REST API documentation


Webhook Configuration

Webhooks allow your external systems to receive real-time notifications about gift card events.


Setting Up Webhook Security

Generating a Webhook Secret

  1. In the Webhooks section, click "Generate Secret" (or "Regenerate Secret" if you already have one)
  2. Important: Copy and save the secret immediately - it won't be shown again
  3. This secret is used to verify that webhook requests come from Gift Hero


Security Note: Gift Hero uses HMAC SHA-256 signatures sent in the X-GiftHero-Signature header to ensure webhook authenticity.


Webhook Types

1. Order with Gift Card Webhook

Purpose: Receive notifications when an order containing a gift card is created


Configuration:

  1. Enter your webhook URL in "Order with gift card webhook URL"
  2. Example: https://your-domain.com/webhooks/gift-card-order

2. Gift Card Payment Webhook

Purpose: Receive notifications when a gift card is used for payment


Configuration:

  1. Enter your webhook URL in "Gift card payment webhook URL"
  2. Example: https://your-domain.com/webhooks/gift-card-payment

3. Gift Card Balance Webhook

Purpose: Receive notifications when a gift card balance changes (payment or manual update)


Configuration:

  1. Enter your webhook URL in "Gift card balance webhook URL"
  2. Example: https://your-domain.com/webhooks/gift-card-balance


Webhook Data Formats

Gift Card Order Webhook Payload

When an order containing gift cards is created, you'll receive:


{
  "type": "gift_card_order",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "data": {
    "shop": "your-store.myshopify.com",
    "orderId": 5671418331319,
    "orderName": "#1077",
    "orderEmail": "customer@example.com",
    "createdAt": "2025-06-11T15:11:19+03:00",
    "jobType": "gift_card_order",
    "giftCards": [
      {
        "id": 111222333,
        "code": "ABCD-1234-EFGH", // Optional - may not always be available
        "balance": "50.00",
        "currency": "USD",
        "lastCharacters": "EFGH",
        "initialValue": "50.00",
        "customer": {
          "id": 67890,
          "email": "customer@example.com",
          "name": "John Doe"
        },
        "recipient": {
          "id": 67891,
          "email": "recipient@example.com",
          "name": "Jane Smith"
        }
      }
    ]
  }
}

Gift Card Payment Webhook Payload

When a gift card is used for payment:


{
  "type": "gift_card_payment",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "shop": "your-store.myshopify.com",
    "orderId": 5671418331319,
    "orderName": "#1077",
    "orderEmail": "customer@example.com",
    "createdAt": "2025-06-11T15:11:19+03:00",
    "jobType": "gift_card_payment",
    "giftCards": [
      {
        "id": 111222333,
        "balance": "30.00",
        "currency": "USD",
        "lastCharacters": "EFGH",
        "initialValue": "50.00",
        "transaction": {
          "id": "txn_123456",
          "amount": "20.00",
          "currency": "USD",
          "type": "debit",
          "createdAt": "2024-01-15T10:30:00.000Z"
        }
      }
    ]
  }
}

Gift Card Balance Webhook Payload

When a gift card balance changes:


{
  "type": "gift_card_balance",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "shop": "your-store.myshopify.com",
    "orderId": 5671418331319,
    "orderName": "#1077",
    "orderEmail": "customer@example.com",
    "createdAt": "2025-06-11T15:11:19+03:00",
    "jobType": "gift_card_balance",
    "giftCards": [
      {
        "id": 111222333,
        "balance": "30.00",
        "currency": "USD",
        "lastCharacters": "EFGH",
        "initialValue": "50.00",
        "transaction": {
          "id": "txn_123456",
          "amount": "20.00",
          "currency": "USD",
          "type": "debit",
          "createdAt": "2024-01-15T10:30:00.000Z"
        }
      }
    ]
  }
}

Webhook Authentication

Verifying Webhook Requests

All webhook requests include these headers:


  • Content-Type: application/json
  • User-Agent: GiftHero-Webhooks/1.0
  • X-GiftHero-Topic: The webhook type (e.g., gift_card_order )
  • X-GiftHero-Signature: HMAC SHA-256 signature (if secret is configured)

Example Verification (Pseudo-code)

// Extract the signature from headers
signature = request.headers['X-GiftHero-Signature']

// Get the request body
body = request.body

// Create expected signature using your webhook secret
expected_signature = 'sha256=' + hmac_sha256(webhook_secret, body)

// Compare signatures
if (signature === expected_signature) {
    // Webhook is authentic
    process_webhook(body)
} else {
    // Webhook may be fraudulent - reject
    reject_request()
}

Webhook Best Practices

  1. Always verify the signature if you've configured a webhook secret
  2. Respond with HTTP 200 to acknowledge receipt
  3. Process webhooks asynchronously to avoid timeouts
  4. Implement idempotency - you may receive the same webhook multiple times
  5. Set up retry logic in case your endpoint is temporarily unavailable

Timeout: Gift Hero will wait up to 6 seconds for your webhook endpoint to respond.



Data Storage Options

Save Gift Card Data to Metafield

This feature stores gift card information in Shopify metafields for use in email templates and other customizations.


How to Enable

  1. Check "Save a gift card data to a metafield"
  2. Click Save

What this does:

  • Stores scheduled gift card data in metafield namespace: gift_hero
  • Uses metafield key: cards_data
  • Makes gift card data accessible in Shopify email templates during generation

Disable UI for Template Suffix

  1. Check "Disable gift card page animation for templates with suffix"
  2. This disables the Gift Hero UI on gift card pages that have a template_suffix set
  3. Useful when you want to use custom templates for specific gift card types


Headless Mode

Headless mode allows you to use Gift Card Hero's functionality while providing your own custom frontend interface.


Enabling Headless Mode

  1. In the Headless mode section, click "Enable headless mode"
  2. The integration code will appear below

Integration Code

When headless mode is enabled, you'll receive integration code that includes:


  • [MONEY_FORMAT] - Replace with your store's money format (e.g., ${{amount_no_decimals}} )
  • [PRODUCT_ID] - Replace with your gift card product ID
  • [MYSHOPIFY_DOMAIN] - Replace with your *.myshopify.com address
  • [ADD_TO_CART_CALLBACK] - Replace with your add to cart function
  • [LOCALE] - Replace with your store locale (default: 'en')

Integration Steps

  1. Copy the provided integration code
  2. Replace all placeholder values with your actual store information
  3. Add the code to your gift card product page
  4. Test the integration with your development team

Note: Your store's money format can be found in Shopify's currency formatting documentation.



Troubleshooting

Common Issues

Webhooks Not Receiving Data

  1. Check your webhook URLs - Ensure they're publicly accessible
  2. Verify SSL certificates - Webhook endpoints must use HTTPS
  3. Check response codes - Your endpoint must respond with HTTP 200
  4. Review timeout settings - Respond within 6 seconds

API Authentication Failures

  1. Verify your access token - Request a new one if needed
  2. Check token expiration - Tokens may need to be refreshed
  3. Confirm API permissions - Ensure REST API is enabled

Headless Mode Not Working

  1. Verify placeholder replacements - All placeholders must be replaced with actual values
  2. Check product ID - Ensure you're using the correct gift card product ID
  3. Test money format - Verify your store's money format is correct

Getting Help

If you need assistance with developer features:


  1. Documentation: Visit API documentation
  2. Support: Contact Gift Card Hero support through the app
  3. Developer Resources: Use the Postman collection for API testing


Security Considerations

API Security

  • Never expose access tokens in client-side code
  • Store tokens securely on your server
  • Rotate tokens regularly for enhanced security
  • Use HTTPS only for all API communications

Webhook Security

  • Always use webhook secrets for production environments
  • Verify signatures on all incoming webhook requests
  • Use HTTPS endpoints only
  • Implement rate limiting to prevent abuse

Data Protection

  • Handle customer data carefully according to privacy regulations
  • Encrypt sensitive information in transit and at rest
  • Log security events for audit purposes
  • Follow PCI compliance guidelines for payment-related data


This documentation provides store owners and their developers with comprehensive guidance on implementing Gift Card Hero's advanced features. Always test configurations in a development environment before deploying to production.