Gift card hero REST api

Overview

The Gift Card Hero Backend API allows you to manage gift cards for a store. You can create, retrieve, update, and delete gift cards using this API. Gift cards are alternative payment methods with unique codes that can be used during checkout.

Base URL: https://gifthero.syncu.be/api/external

Authentication: All requests require a Bearer token in the Authorization header.

You can obtain a Bearer token in the "For Developers" section of the app by clicking Send me access token. The access token will be sent to the email associated with your store registration. If you don't see the email, please check your junk or spam folder.

Endpoints

1. List Gift Cards

Retrieves a list of gift cards.

URL: /gift-cards
Method: GET

Query Parameters

Parameter	Description
`status`	Optional. Retrieve gift cards with a given status
`limit`	Optional. The maximum number of results to show (default: 50, maximum: 250)
`since_id`	Optional. Restrict results to after the specified ID
`fields`	Optional. Show only certain fields, specified by a comma-separated list of field names

Response

{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-01-14T10:26:56-05:00",
      "updated_at": "2020-01-14T10:26:56-05:00",
      "currency": "USD",
      "initial_value": "50.00",
      "disabled_at": null,
      "line_item_id": null,
      "api_client_id": null,
      "user_id": null,
      "customer_id": null,
      "note": null,
      "expires_on": null,
      "template_suffix": null,
      "last_characters": "0y0y",
      "order_id": null
    },
    // ... more gift cards
  ]
}

1.1. List Gift Cards with Transactions

Retrieves a list of gift cards with their transaction history and advanced filtering options.

/external/gift-cards/transactions

GET

Query Parameters

Pagination

Parameter	Description
`limit`	Optional. The maximum number of results to show (default: 50, maximum: 250)
`page_info`	Optional. Pagination cursor for retrieving the next page of results

Search & Filtering

Parameter	Type	Description	Examples
`query`	string	Search across gift card fields	`query=Bob Norman` `query=title:green hoodie`
`balance_status`	string	Filter by balance status	`full` - Full balance `partial` - Partially used `empty` - Zero balance `full_or_partial` - Has remaining balance
`created_at`	datetime	Filter by creation date	`created_at:>=2020-01-01T12:00:00Z`
`expires_on`	date	Filter by expiration date	`expires_on:>=2020-01-01`
`id`	integer	Filter by ID range	`id:1234` `id:>=1234` `id:<=1234`
`initial_value`	decimal	Filter by initial value	`initial_value:>=100`
`source`	string	Filter by creation source	`manual` - Created manually `purchased` - Purchased by customer `api_client` - Created via API
`status`	string	Filter by gift card status	`disabled` - Disabled cards `enabled` - Active cards `expired` - Expired cards `expiring` - Expiring in next 30 days

Response

Returns an array of gift cards with their transaction history. Pagination information is provided via HTTP Link header.

[
  {
    "id": 572379529462,
    "balance": "20.00",
    "created_at": "2025-01-03T13:36:11+03:00",
    "updated_at": "2025-01-03T13:36:11+03:00",
    "currency": "USD",
    "initial_value": "50.00",
    "disabled_at": null,
    "customer_id": 123456789,
    "note": "Birthday gift card",
    "expires_on": "2026-01-01",
    "template_suffix": null,
    "last_characters": "htj7",
    "order_id": 987654321,
    "transactions": [
      {
        "id": 123456,
        "amount": "-30.00",
        "processed_at": "2025-01-02T15:30:00+03:00",
        "note": "Purchase at store"
      },
      {
        "id": 123455,
        "amount": "50.00",
        "processed_at": "2025-01-01T10:00:00+03:00",
        "note": "Initial gift card creation"
      }
    ]
  }
]

Response Headers

Header	Description
`Link`	Contains pagination URLs when more results are available

Link Header Example

Link: <https://yourstore.myshopify.com/external/gift-cards/transactions?page_info=eyJsYXN0X2lkIjo1NzIzNzk1Mjk0NjJ9&limit=50>; rel="next"

Example Requests

Get all active gift cards with partial balance

GET /external/gift-cards/transactions?status=enabled&balance_status=partial

Get gift cards worth $50 or more created after January 1, 2024

GET /external/gift-cards/transactions?initial_value:>=50&created_at:>=2024-01-01T00:00:00Z

Get gift cards expiring in the next 30 days

GET /external/gift-cards/transactions?status=expiring

Search for gift cards by last 4 characters

GET /external/gift-cards/transactions?query=last4:1234

Get API-created gift cards with full balance

GET /external/gift-cards/transactions?source=api_client&balance_status=full

Notes

All filter parameters can be combined using AND logic
The /transactions endpoint provides the same gift card data as the standard endpoint, but includes transaction history
Use the standard /external/gift-cards endpoint if you don't need transaction data for better performance
Pagination uses cursor-based pagination via the page_info parameter and Link header

2. Get a Single Gift Card

Retrieves a single gift card by its ID.

URL: /gift-cards/{gift_card_id}
Method: GET

Response

{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-01-14T10:26:56-05:00",
    "updated_at": "2020-01-14T10:26:56-05:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": null,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

3. Create a Gift Card

Creates a new gift card.

URL: /gift-cards
Method: POST

Request Body

{
  "note": "This is a note",
  "initial_value": 100.0,
  "code": "ABCD EFGH IJKL MNOP",
  "template_suffix": "gift_cards.birthday.liquid"
}

Response

{
  "gift_card": {
    "id": 1063936318,
    "balance": "100.00",
    "created_at": "2020-01-14T10:32:53-05:00",
    "updated_at": "2020-01-14T10:32:53-05:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": "This is a note",
    "expires_on": null,
    "template_suffix": "gift_cards.birthday.liquid",
    "last_characters": "mnop",
    "order_id": null,
    "code": "abcdefghijklmnop"
  }
}

4. Update Gift Card Balance

Updates the balance of an existing gift card.

URL: /gift-cards/{gift_card_id}/balance
Method: PUT

Request Body

{
  "balance": "100.00"
}

Response

{
  "id": 204959973622,
  "gift_card_id": 564744552694,
  "api_client_id": 5469899,
  "user_id": null,
  "order_transaction_id": null,
  "number": 1,
  "amount": "-15.00",
  "processed_at": "2023-06-16T13:06:03+03:00",
  "created_at": "2023-06-16T13:06:03+03:00",
  "updated_at": "2023-06-16T13:06:03+03:00",
  "note": null,
  "remote_transaction_ref": null,
  "remote_transaction_url": null
}

5. Update Gift Card

Updates an existing gift card. Note: The gift card's balance can't be changed via this request.

URL: /gift-cards/{gift_card_id}
Method: PUT

Request Body

{
  "id": 48394658,
  "expires_on": "2024-01-01"
}

Response

{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-01-14T10:26:56-05:00",
    "updated_at": "2020-01-14T10:32:55-05:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": null,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": "2024-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

6. Disable a Gift Card

Disables a gift card. This action cannot be undone.

URL: /gift-cards/{gift_card_id}/disable
Method: POST

Request Body

{
  "id": 48394658
}

Response

{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-01-14T10:26:56-05:00",
    "updated_at": "2020-01-14T10:32:55-05:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-01-14T10:32:55-05:00",
    "line_item_id": null,
    "api_client_id": null,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

7. Search Gift Cards

Searches for gift cards that match a supplied query.

URL: /gift-cards/search
Method: GET

Query Parameters

Parameter	Description
`order`	Optional. The field and direction to order results by (default: disabled_at DESC)
`query`	Optional. The text to search for
`limit`	Optional. The maximum number of results to retrieve (default: 50, maximum: 250)
`fields`	Optional. Show only certain fields, specified by a comma-separated list of field names

Response

{
  "gift_cards": [
    {
      "id": 1063936317,
      "balance": "10.00",
      "created_at": "2020-01-14T10:32:47-05:00",
      "updated_at": "2020-01-14T10:32:47-05:00",
      "currency": "USD",
      "initial_value": "10.00",
      "disabled_at": null,
      "line_item_id": null,
      "api_client_id": null,
      "user_id": null,
      "customer_id": null,
      "note": null,
      "expires_on": null,
      "template_suffix": null,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}

Notes

Gift card codes cannot be retrieved after they're created—only the last four characters can be retrieved.
After a gift card is created, only the expiry date, note, and template suffix can be updated.
The search endpoint indexes the following fields: created_at, updated_at, disabled_at, balance, initial_value, amount_spent, and last_characters.
This API uses pagination for list and search endpoints. The pagination links are provided in the response header.