View Gift Cards

After purchasing a gift card, you need to make an API call to reveal the gift card details. 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

📘

Reconciling gift cards to your orders

getGiftCards returns purchaseId (the same UUID returned by purchaseGiftCard and getUserPurchases), purchaseDisplayId (the short Fluz transaction ID, e.g. 1047283), and the order value via purchaseValue / currentValue / currency. Use these to map each giftCardId back to its originating order and amount without having to reveal every card.

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
    purchaseId
    purchaseDisplayId
    purchaserUserId
    endDate
    status
    purchaseValue
    currentValue
    currency
    createdAt
    deliveryFormat
    termsAndConditions
    merchant {
      merchantId
      name
      slug
    }
  }
}

Query Arguments

The following arguments are used to run this query:

• 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",
        "purchaseId": "785f57ff-f756-4f5c-afca-b896881e3e87",
        "purchaseDisplayId": "1047283",
        "purchaserUserId": "7c57c381-4b19-49e4-bbb0-404a45166ee4",
        "endDate": "2007-12-03T10:15:30Z",
        "status": "ACTIVE",
        "purchaseValue": 25,
        "currentValue": 25,
        "currency": "USD",
        "createdAt": "2007-12-03T10:15:30Z",
        "deliveryFormat": "PIN_WITH_URL",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for...",
        "merchant": {
          "merchantId": "123",
          "name": "Merchant",
          "slug": "merchant"
        }
      }
    ]
  }
}

Response Fields

purchaseId — The UUID of the purchase that created this gift card. Use this to reconcile a gift card against the purchaseId you stored when calling purchaseGiftCard / from getUserPurchases. Returns null if no associated purchase is found.

purchaseDisplayId — The short, human-readable Fluz transaction ID for the purchase (e.g. 1047283). This is the ID Fluz support references for manual review and in exports. Returns null if no associated purchase is found.

purchaseValue — The value (denomination / face value) the gift card was purchased at, in the card's currency. Use this for reconciling order amounts.

currentValue — The remaining balance on the gift card, in the card's currency. For single-use cards this typically equals purchaseValue.

currency — The ISO currency code of the gift card's value (e.g. USD).

deliveryFormat — The delivery format of the offer this gift card was purchased under. One of URL, CODES, PIN_AS_CODE, PIN_WITH_URL, or CODE_WITH_PREFIX.

termsAndConditions — The terms and conditions text for the offer this gift card was purchased under (legal language, restrictions, expiration policies). This is the offer-time T&C, which may differ from the merchant's currently active offer's T&C — same reasoning as deliveryFormat.

📘

Prefer deliveryFormat from getGiftCards over getMerchants

A merchant's active offer can change over time. The format the gift card was purchased under may differ from the merchant's current active offer, so always use the deliveryFormat returned by getGiftCards when deciding how to render the redemption details from revealGiftCardByGiftCardId.

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 Mutation

mutation RevealGiftCardByGiftCardId {
  revealGiftCardByGiftCardId(
    giftCardId: "86dd5fcf-fea3-4531-aa5d-1d196957f7d7"
  ) {
    code
    pin
    url
    termsAndConditions
  }
}

Sample Response

{
  "data": {
    "revealGiftCardByGiftCardId": {
      "code": "9877890000000000",
      "pin": "2014",
      "url": null,
      "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for..."
    }
  }
}

📘

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 always 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.