> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# View Gift Cards

getGiftCards, revealGiftCardByGiftCardId

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

```graphql theme={null}
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

```json theme={null}
{
  "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

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

### Sample Response

```json theme={null}
{
  "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.