View Gift Cards

After purchasing a gift card, you need to make an API call to reveal the gift card ID. Follow these steps to retrieve the necessary information:

1. Retrieve the Gift Card Order List - You can skip this step if you just purchased a gift card and have the giftCardId already.
2. Reveal gift card details - Use the revealGiftCardByGiftCardId mutation to reveal the gift card redemption details.

Step 1: Retrieve the Gift Card Order List

To obtain a list of gift cards ordered on your account, use the getGiftCards query. This call returns a list of gift cards with basic details, including the giftCardId. You will need this ID to reveal a gift card's details.

Sample Query

query GetGiftCards {
  getGiftCards(
    paginate: { limit: 20, offset: 0 }
  ) {
    giftCardId
    purchaserUserId
    endDate
    status
    createdAt
    merchant {
        merchantId
        name
        slug
    }
  }
}

Fields

The following fields are used to run this mutation:

status - If you want to filter the gift cards by status.

userCashBalanceId - If you want to filter gift cards by the cash balance (spend account).

paginate - Pagination fields

paginate.limit - Maximum amount of gift cards per page

paginate.offset - The amount of records that should be offset

Sample response:

{
  "data": {
    "getGiftCards": [
      {
        "giftCardId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "purchaserUserId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "endDate": "2007-12-03T10:15:30Z",
        "status": "ACTIVE",
        "createdAt": "2007-12-03T10:15:30Z",
        "merchant": Merchant
      }
    ]
  }
}

Step 2: Reveal Gift Card Details

Once you have retrieved the full gift card order list, you can reveal the details of each gift card, including the gift card code and other information, using the revealGiftCardByGiftCardId mutation.

Input

The revealGiftCardByGiftCardId mutation only requires an input argument of giftCardId to return your gift card redemption details as a response.

Sample Response:

{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null
    }
  }
}

📘

Not all merchant gift cards have codes, pins and URLs

Depending on the merchant and the partner, the gift card details may vary. Some merchants use an alphanumeric code and do not provide a PIN with their gift card. Some merchants or partners only provide a URL instead of a code and pin.

Fluz will alway pass all information that we are provided from the merchants on each gift card order.

Recommended Polling Strategy

If gift card details are not immediately returned, you can poll the Reveal Gift Card endpoint using an exponential backoff strategy. Starting recommendation:

• Initial delay: 300ms
• Backoff strategy: Exponential (e.g. 300ms → 600ms → 1200ms → 2400ms → …)
• Maximum delay: 180000ms (3 minutes)
• Stop polling once gift card details are successfully returned

This approach balances responsiveness with system load and helps prevent unnecessary timeouts or excessive requests.