Overview - Fluz

Buying a gift card through Fluz is four steps, and each one has a page of its own. This is the map.

Find the offer

Pull the catalog, or ask for the best rate on one merchant. → Read the catalog

Confirm the amount is purchasable

Fixed or variable, stocked or generated on demand. → Fixed vs. variable

Buy

One mutation, one card, one idempotency key. → Buying

Reveal

Get the code, PIN, or URL, and render it correctly. → Revealing

Rates change constantly. Fluz continuously re-prices to give customers the best available offer, and your rates are customized to your account. Never cache a rate and purchase against it later — re-confirm immediately before you buy.

Vocabulary

Five terms do most of the work in this section, and three of them sound alike.

Term	What it is
Merchant	The brand — Starbucks, Best Buy. Has a `merchantId` and a human-readable `slug`.
Offer	A specific purchasable deal from that merchant, with its own `offerId`. One merchant can have several.
Offer rate	The reward attached to an offer — cashback, boosts, eligible denominations, permitted payment methods.
Denomination	The face value of the card. Either chosen from a preset list or any amount in a range.
Delivery format	How the card arrives: `URL`, `CODES`, `PIN_AS_CODE`, `PIN_WITH_URL`, or `CODE_WITH_PREFIX`. Determines how you render it.

Two identifiers are easy to confuse: merchantId identifies the brand, offeringMerchantId identifies the party offering that particular deal. You buy against an offerId or a slug, never against a merchantId.

Reading the catalog

Three ways in, for three different jobs.

Approach	Query	Use when
Full catalog	`getMerchants`	You’re building a browsable storefront, syncing a local catalog, or comparing across brands
Best rate for one merchant	`getOfferQuote`	You already know the brand and amount and just want today’s best rate
CSV export	Dashboard → Stores → generate export	Analysis, finance, or a human wants a spreadsheet

Filter getMerchants to gift cards with offerTypes: { giftCardOffer: true, cardLinkedOffer: false }. Card-linked offers exist in the catalog but only gift card and exclusive offers are purchasable through the API today.

The full catalog is a cached file, refreshed twice daily. getOfferQuote is live. If the exact rate matters at purchase time — and it usually does — quote before you buy rather than trusting a catalog pull from this morning. Promotional rates are reflected in both, including in CSV exports generated during a promotion.

Both queries are rate-limited, so paginate the full catalog rather than requesting it in one call. → Get Catalog · Get Gift Card Offers · Get the Best Offer

Exclusive offers

Rates are customized per account. If yours has negotiated rates, they appear as offers with type: "EXCLUSIVE_RATE_OFFER" carrying an exclusiveRateId. Pass that ID to purchaseGiftCard to force the purchase onto that rate; omit it and Fluz picks the best available.

Fixed vs. variable offers

This is the distinction that most shapes how you build, and a merchant can have both.

FIXED

The card comes in preset denominations —

25,

50, $100 — and you buy one of them exactly.Frequently backed by real inventory Fluz holds, which is why fixed offers usually carry better rates and higher purchasing limits.Inventory is finite. It runs out.

VARIABLE

You choose any amount within a min/max range, and the card is generated in real time.No inventory to deplete — effectively unlimited supply.Usually a lower reward rate than the same brand’s fixed offer.

The practical trade-off: fixed offers pay better but can be exhausted mid-run; variable offers always work but pay less. High-volume ordering usually means taking fixed inventory first and falling back to variable.

Where to read the purchasable amounts

Two fields decide this, and the combination determines which field holds the answer. Get this wrong and you’ll submit amounts the offer can’t fulfill.

`denominationsType`	`hasStockInfo`	Purchasable amounts live in	Meaning
`FIXED`	`true`	`stockInfo` → `StockInfoFixedType`	Specific denominations with a countable `availableStock`
`FIXED`	`false`	`offerRates.denominations`	Preset denominations, no inventory constraint published
`VARIABLE`	`true`	`stockInfo` → `StockInfoVariableType`	A `minDenomination`–`maxDenomination` range
`VARIABLE`	`false`	`offerRates.denominations`	Any amount in the published range

stockInfo is a union type. You must query it with inline fragments for both shapes, or you’ll get nothing back for one of them:

stockInfo {
  ... on StockInfoFixedType    { __typename denomination availableStock }
  ... on StockInfoVariableType { __typename description minDenomination maxDenomination }
}

Always include both fragments, even when you think you know which one you’ll get. See How the GraphQL API works.

Note that “has stock info” doesn’t mean “has countable stock.” On a variable offer, stockInfo returns a range, not a quantity. Only StockInfoFixedType carries an availableStock number you can decrement against. Populating stockInfo requires Fluz to confirm inventory with the vendor, and vendor response times vary — so requesting it makes the query slower. Only ask for it when you’re about to act on it. → Get Inventory on Stocked Offers

Buying a card

One mutation: purchaseGiftCard. Three decisions.

1. How to pick the offer

You pass	Behavior
`offerId`	Pinned. Buys that exact offer. If it’s depleted, the call fails — no fallback.
`merchantSlug`	Auto-select. Buys the best available rate for that brand, falling back as inventory shifts.
`merchantSlug` + `minRewardRate`	Auto-select with a floor. Fails rather than buying below your minimum rate.
`exclusiveRateId`	Forces a specific negotiated rate.

Pinning gives you certainty about the rate; auto-select gives you certainty about fulfillment. merchantSlug + minRewardRate is the middle ground and usually the right default for automated ordering.

2. How to pay

At least one funding source is required, and you can combine your Fluz balance with another.

Field	What it does
`balanceAmount`	How much to pay from your Fluz balance
`userCashBalanceId`	Which spend account that balance draws from
`bankCardId` / `bankAccountId` / `paypalVaultId`	External funding sources
`defaultToBalance`	Fall back to balance if another method fails. Defaults to `true`

If your account holds more than one spend account, always pass userCashBalanceId explicitly. Omit it and Fluz draws from whichever account is flagged isDefault — which can change without your code changing, silently redirecting where your money comes from. This is the most common cause of surprise insufficient-funds failures.In automated pipelines, also set defaultToBalance: false so a purchase either draws from the account you named or fails cleanly.

3. Idempotency

idempotencyKey is required, and it’s the difference between a retry and a double purchase. One key per intended card, reused on every retry of that same card. → Idempotency → Purchase Gift Card

Buying more than one

One call buys exactly one card, on one offer, at one rate. There’s no quantity field and no blending across offers. For ten cards, send ten calls with ten distinct idempotency keys. What happens when you outrun inventory depends on how you picked the offer:

Pinned (offerId) — once the stocked offer is depleted, remaining calls fail. No automatic fallback.
Auto-select (merchantSlug) — remaining calls move to the next-best offer, often a variable one at a lower rate, unless minRewardRate blocks it.

→ Purchase in Bulk

Ordering at volume

Purchases against the same Fluz account process sequentially. Fire a large batch at once and calls queue behind each other, occasionally taking minutes to return.

A client timeout is not a cancellation. Fluz keeps processing a request you’ve stopped waiting for. Treat a timeout as an unknown outcome, never a failure.Resolve it by retrying with the same idempotencyKey — the retry returns the original purchase if it already succeeded, and won’t double-charge. Issuing a fresh key for a purchase you already attempted is exactly how duplicate orders happen.Set client timeouts to about a minute, pace requests in waves rather than all at once, and spread heavy volume across multiple accounts.

Revealing the card

A purchase gives you a giftCardId. Redemption details come from a second call.

Get the gift card

Skip this if you just purchased and already hold the giftCardId. Otherwise getGiftCards lists them with purchaseId, purchaseDisplayId, purchaseValue, currentValue, and status — enough to reconcile orders without revealing every card.

Reveal it

revealGiftCardByGiftCardId returns code, pin, url, and termsAndConditions.

Three things that catch people out:

Not every card has all three fields. Some merchants issue a code with no PIN; some issue only a URL. Fluz passes through whatever the merchant provides — handle nulls.
Render according to deliveryFormat and barcodeType, and take deliveryFormat from getGiftCards, not from the merchant’s current offer. Offers change; the card was issued under the format in force at purchase time. barcodeType is NONE, C128, PDF417, or QRCODE; when it’s NONE, consider displaying the faceplateUrl instead.
Details may not be ready instantly. Poll with exponential backoff — 300ms, doubling, capped at three minutes — and stop as soon as details return.

→ View Gift Cards

Scopes

Scope	Needed for
`LIST_OFFERS`	`getMerchants`, `getOfferQuote`
`PURCHASE_GIFTCARD`	`purchaseGiftCard`
`REVEAL_GIFTCARD`	`revealGiftCardByGiftCardId`
`LIST_PURCHASES`	`getUserPurchases`, purchase history
`LIST_PAYMENT`	`getUserCashBalances`, `getWallet`

Enable these on your app’s Permissions tab before you build. A scope you request but haven’t enabled is silently dropped. → Configure OAuth App

When things fail

Code	Meaning
`GC-0002`	Purchase amount or Fluz Pay amount isn’t positive
`GC-0003`	Couldn’t retrieve the gift card record
`GC-0004`	Purchase failed — try another payment method
`GC-0006`	Couldn’t reveal the card

Full list: Gift Card Error Codes. Before refunding an end user on a failed or timed-out purchase, retry with the same idempotencyKey or look up the purchase by ID. Timed-out requests frequently succeeded, and the code stays revealable until the purchase is refunded.

Next steps

Get catalog

Pull merchants and their offers.

Get the best offer

Live quote for one merchant and amount.

Get inventory

Stock on fixed, stocked offers.

Purchase a gift card

The mutation, in full.

Purchase in bulk

Ordering many cards, and depletion behavior.

View gift cards

Reveal codes, PINs, and URLs.

​Vocabulary

​Reading the catalog

​Exclusive offers

​Fixed vs. variable offers

FIXED

VARIABLE

​Where to read the purchasable amounts

​Buying a card

​1. How to pick the offer

​2. How to pay

​3. Idempotency

​Buying more than one

​Ordering at volume

​Revealing the card

​Scopes

​When things fail

​Next steps

Get catalog

Get the best offer

Get inventory

Purchase a gift card

Purchase in bulk

View gift cards

Vocabulary

Reading the catalog

Exclusive offers

Fixed vs. variable offers

Where to read the purchasable amounts

Buying a card

1. How to pick the offer

2. How to pay

3. Idempotency

Buying more than one

Ordering at volume

Revealing the card

Scopes

When things fail

Next steps