Purchase Gift Cards

Once you've determined your preferred offer, use the purchaseGiftCard mutation to purchase your gift card. This mutation requires a PurchaseGiftCardInput input object.

Sample Mutation

Here's the quickest way to start purchasing a gift card. You are able to customize your query from the UserPurchase object. See UserPurchase.

mutation purchaseGiftCard($input: PurchaseGiftCardInput!) {
  purchaseGiftCard(input: $input) {
    purchaseDisplayId
    purchaseAmount
    giftCard {
      giftCardId
      status
      termsAndConditions
    }
  }
}

Fields

The following fields are used to run this mutation:

idempotencyKey — Required. A unique client-generated UUID to ensure a request is processed only once.

offerId or merchantSlug — Required. Use the offerId or merchantSlug from the getOfferQuote query to get the best offer. Using the merchantSlug will automatically purchase the best offer rate for that merchant.

amount — Required. The gift card amount you'd like to purchase.

Only one of the following is required. You may also choose to combine your Fluz balance with another funding source.

exclusiveRateId — The unique identifier for a specific exclusive rate offer. When provided, this forces the purchase to use the specified exclusive rate. If not provided, the system will automatically select the best available rate. The exclusiveRateId can be found in the getMerchants query response for offers with type EXCLUSIVE_RATE_OFFER when you provide exclusiveRateId in your query request under offers.

balanceAmount — If you want to pay for your gift card with your Fluz balance, define the amount of balance here. You can use the getWallet query to check your balances. See reference.

bankAccountId — If you want to pay with a bank account, define the bank account ID.

bankCardId — If you want to pay with a bank card, define the bank card ID.

paypalVaultId — If you want to pay with a PayPal account, define the PayPal account ID.

defaultToBalance — If you want to use your Fluz balance as the fallback payment method in case your other payment methods fail, set defaultToBalance to true. By default, this is set to true. If you change this setting to false, the system will not attempt to use your Fluz balance as a backup payment method.

minRewardRate — If you want to specify the minimum reward rate to purchase if the merchantSlug option is chosen.

userCashBalanceId — If you want to specify the cash balance (spend account) to be used for that purchase.

memo — If you want to attach a note to this transaction, provide a free-text memo here. Max 255 characters.

transactionCategory — If you want to categorize this transaction, provide a category name. Categories are created automatically on first use and reused if the same name is passed again.

attachmentId — If you want to attach a file to this transaction, provide the ID returned by the upload endpoint. See Annotate a Transaction.

PurchaseGiftCardInput

{
  "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "offerId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "amount": 987.65,
  "balanceAmount": 123.45,
  "bankAccountId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "paypalVaultId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "exclusiveRateId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "merchantSlug": "xyz789",
  "minRewardRate": 5.6,
  "userCashBalanceId": "85de1b3e-4e72-462c-8ed1-a6f4982e22f7"
}

Sample Response

Once your purchase is complete, you'll get a response that looks something like this:

{
  "data": {
    "purchaseGiftCard": {
      "purchaseId": "255f8245-02c7-4817-901e-15fe265f6968",
      "purchaseDisplayId": "1019688",
      "purchaseBankCardId": "255f8245-02c7-4817-901e-15fe265f6968",
      "bankAccountId": "255f8245-02c7-4817-901e-15fe265f6968",
      "purchaseAmount": 123.45,
      "fluzpayAmount": 85.0,
      "seatRewardValue": 0.05,
      "paypalVaultId": "255f8245-02c7-4817-901e-15fe265f6968",
      "createdAt": "2007-12-03T10:15:30Z",
      "giftCard": {
        "giftCardId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "purchaserUserId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
        "endDate": "2007-12-03T10:15:30Z",
        "status": "ACTIVE",
        "termsAndConditions": "Except as required by law, Gift Cards cannot be transferred for...",
        "createdAt": "2007-12-03T10:15:30Z",
        "merchant": {
          "merchantId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
          "name": "Starbucks",
          "slug": "starbucks",
          "logoUrl": "https://storage.googleapis.com/.../starbucks-logo.jpg",
          "faceplateUrl": "https://storage.googleapis.com/.../starbucks-faceplate.png",
          "offers": [
            {
              "offeringMerchantId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
              "offerId": "85de8b3e-4e72-462c-8ed1-a6f4982e22f7",
              "type": "GIFT_CARD_OFFER",
              "deliveryFormat": "CODES",
              "barcodeType": "C128",
              "hasStockInfo": false,
              "offerRates": [
                {
                  "maxUserRewardValue": 5.0,
                  "cashbackVoucherRewardValue": 1.0,
                  "boostRewardValue": 0.5,
                  "displayBoostReward": true,
                  "denominations": [25, 50, 100],
                  "allowedPaymentMethods": ["CREDIT_CARD", "PAYPAL"]
                }
              ],
              "denominationsType": "VARIABLE",
              "stockInfo": []
            }
          ]
        }
      }
    }
  }
}

Buying more than one card

A single purchaseGiftCard call buys exactly one gift card, on one offer, at one rate. There is no quantity field, and a call is never split or blended across offers or rates. To buy several cards, send the mutation once per card, each with its own unique idempotencyKey.

Because each card is its own call, ordering more cards than a stocked offer has in inventory resolves per call:

• offerId (pinned offer): once the stocked offer is depleted, the remaining calls fail with GC-0009. There is no automatic fallback to another offer or rate.
• merchantSlug (auto-select): the remaining calls auto-select the next-best available offer — often a variable offer at a lower reward rate — unless minRewardRate blocks the lower rate.

For the full per-call breakdown, the minRewardRate rate-floor pattern, and the GC-0009 response, see Buying Multiple Stocked Inventory Gift Cards.

Ordering at volume: concurrency, timeouts, and retries

Purchases that draw on the same Fluz account are processed sequentially. When many purchaseGiftCard calls are submitted at the same time against a single account, they queue behind one another, and individual calls can take longer to return — occasionally up to a few minutes under heavy load. Calls that aren't queued typically return within seconds.

To keep latency predictable and avoid false failures when ordering at volume:

• Pace your concurrent requests. Instead of firing an entire batch simultaneously against one account, submit in smaller waves, or spread volume across multiple accounts. This keeps per-call latency low.

• Use a generous client timeout. Fluz does not abandon an in-flight purchase after a few seconds — a request can still be legitimately processing and will return a valid result. A short client-side timeout (for example, 30 seconds) may cause you to give up on a purchase that ultimately succeeds. Set your timeout high enough to absorb occasional multi-minute processing under load. We recommend 1 minute.

• A client timeout is not a cancellation. Closing your connection does not cancel a request that Fluz has already accepted; it continues processing to completion. Treat a timeout as an unknown outcome, not a failure.

• Resolve timeouts by retrying with the same idempotencyKey. Reissue the identical request with the identical idempotencyKey. Because the key guarantees the purchase is processed at most once, the retry returns the original purchase if it already succeeded — it will not create a duplicate or a second charge. Never issue a new idempotencyKey for a purchase you've already attempted; doing so is what produces duplicate orders.

Next Steps

Now it's time to reveal your gift card details for use. Learn how to do so here:

View Gift Cards