Gift cards

List and retrieve gift cards

Stored value a customer can spend, with every movement on it.

The gift card object

Real records only, so a test key never sees one. See Test data.

idstringrequired

A gift card id, gft_ and 22 characters.

object"gift_card"required

code_last4stringrequirednullable

The last four characters of the code. The whole code is never sent.

balanceintegerrequired

An amount in whole cents.

expires_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

activebooleanrequired

holderstringrequirednullable

A customer id, cus_ and 22 characters.

buyerstringrequirednullable

A customer id, cus_ and 22 characters.

recipient_namestringrequirednullable

delivered_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

movementsarray of objectsrequired

movements[].typestringrequirednullable

issue, redeem, refund and so on.

movements[].amountintegerrequired

An amount in whole cents.

movements[].balance_afterintegerrequirednullable

An amount in whole cents.

movements[].orderstringrequirednullable

A order id, ord_ and 22 characters.

movements[].bookingstringrequirednullable

A booking id, bkg_ and 22 characters.

movements[].created_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

created_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

updated_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

The gift card object

{
  "id": "gft_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "gift_card",
  "code_last4": "<string>",
  "balance": 4500,
  "expires_at": "2026-10-08T03:00:00.000Z",
  "active": true,
  "holder": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "buyer": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "recipient_name": "<string>",
  "delivered_at": "2026-10-08T03:00:00.000Z",
  "movements": [
    {
      "type": "<string>",
      "amount": 4500,
      "balance_after": 4500,
      "order": "ord_0TMXp8QPR6yGvKuV2GZQ10",
      "booking": "bkg_0TMXp8QPR6yGvKuV2GZQ10",
      "created_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z"
}

List gift cards

GEThttps://api.hatcel.com/gift-cards

Any key

Every gift card the key can see, newest first, a page at a time.

Query parameters

limitinteger

How many to return, 1 to 100. Defaults to 25.

starting_afterstring

The next_cursor of the page before. Omit it for the first page.

updated_sincestring

Only rows changed at or after this instant, ISO 8601 with an offset.

customerstring

Only those for this customer, by its cus_ id.

curl "https://api.hatcel.com/gift-cards?limit=25" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"

200 response

{
  "object": "list",
  "data": [
    {
      "id": "gft_0TMXp8QPR6yGvKuV2GZQ10",
      "object": "gift_card",
      "code_last4": "<string>",
      "balance": 4500,
      "expires_at": "2026-10-08T03:00:00.000Z",
      "active": true,
      "holder": "cus_0TMXp8QPR6yGvKuV2GZQ10",
      "buyer": "cus_0TMXp8QPR6yGvKuV2GZQ10",
      "recipient_name": "<string>",
      "delivered_at": "2026-10-08T03:00:00.000Z",
      "movements": [
        {
          "type": "<string>",
          "amount": 4500,
          "balance_after": 4500,
          "order": "ord_0TMXp8QPR6yGvKuV2GZQ10",
          "booking": "bkg_0TMXp8QPR6yGvKuV2GZQ10",
          "created_at": "2026-10-08T03:00:00.000Z"
        }
      ],
      "created_at": "2026-10-08T03:00:00.000Z",
      "updated_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wOFQwMzowMDowMC4wMDBaIiwiaSI6IjBmOGZhZDViIn0"
}

Retrieve a gift card

GEThttps://api.hatcel.com/gift-cards/{id}

Any key

One gift card by its id, with its version in the ETag header. Another object's id, or one this key cannot see, is a 404.

Path parameters

idstringrequired

The gift card's id, gft_ and 22 characters.

curl "https://api.hatcel.com/gift-cards/gft_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"

200 response

{
  "id": "gft_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "gift_card",
  "code_last4": "<string>",
  "balance": 4500,
  "expires_at": "2026-10-08T03:00:00.000Z",
  "active": true,
  "holder": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "buyer": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "recipient_name": "<string>",
  "delivered_at": "2026-10-08T03:00:00.000Z",
  "movements": [
    {
      "type": "<string>",
      "amount": 4500,
      "balance_after": 4500,
      "order": "ord_0TMXp8QPR6yGvKuV2GZQ10",
      "booking": "bkg_0TMXp8QPR6yGvKuV2GZQ10",
      "created_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z"
}

Tickets Webhooks