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.

8. Assign gift codes to an order

URL: gift-cards/assign-to-order
Method: POST
Response: 200 OK { "scheduled": boolean }

Purpose

Attach one or more predefined gift codes to gift-card line items in an existing Shopify order and enqueue processing. Codes are applied to individual gift card items; any items without an explicit code will be handled by the app’s default code generation flow.

Request schemas

Single code

{
  "orderId": 1234567890,
  "giftCode": "ABCD-EFGH-1234"
}

Multiple codes mapped to line items

{
  "orderId": 1234567890,
  "giftCodes": [
    { "lineItemId": 987654321, "code": "AA11-BB22-CC33" },
    { "lineItemId": 987654321, "code": "DD44-EE55-FF66" },
    { "lineItemId": 222333444, "code": "GG77-HH88-II99" }
  ]
}

Notes

orderId: numeric Shopify Order ID.
lineItemId: numeric Shopify line item ID.
Codes are normalized server‑side: spaces removed, lowercased; lastCharacters is derived from the normalized value.
For multiple gift codes per the same line item (quantity > 1), codes are assigned in the given order to that line item’s gift card entries sequentially.
A linkage record is persisted internally to associate each code to (order, lineItemId, index), and a job is queued for processing.

Behavior

The server fetches the order and derives gift-card items for processing.
Codes are applied as follows:
- giftCodes[]: matched to gift-card items by lineItemId, assigned sequentially per item count.
- giftCode (single): assigned to the first gift-card item.
A processing job is enqueued (custom gift-card flow). The response indicates whether a job was scheduled.

Response

200 OK
- {"scheduled": true} when at least one gift-card item was found and queued
- {"scheduled": false} when the order contains no gift-card items for processing
400 Bad Request: missing/invalid orderId, giftCode/giftCodes
401 Unauthorized: invalid/missing external token
404 Not Found: order not found

Examples

Single code

curl -X POST https://<your-app>/api/external/gift-cards/assign-to-order \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1234567890,
    "giftCode": "ABCD-EFGH-1234"
  }'

Multiple codes

curl -X POST https://<your-app>/api/external/gift-cards/assign-to-order \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1234567890,
    "giftCodes": [
      { "lineItemId": 987654321, "code": "AA11-BB22-CC33" },
      { "lineItemId": 987654321, "code": "DD44-EE55-FF66" },
      { "lineItemId": 222333444, "code": "GG77-HH88-II99" }
    ]
  }'

Best practices

Ensure each code is unique and not previously used.
Provide the correct numeric lineItemId for precise mapping.
If you must retry, keep requests idempotent on your side to avoid duplicate submissions.