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
  ]
}

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.