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

# Changelog

> Recent updates, additions, and breaking changes to the Fluz API.

<Note>
  Subscribe to updates on the [Fluz Status Page](https://you-up.fluz.app/) for incidents and proactive change notifications. You can also subscribe to this changelog via [RSS](/changelog/rss.xml).
</Note>

<Update label="v0.0.67" tags={["Added"]} description="July 2026">
  * Update GenerateVCShareLinksInput for Open Loop Cards. See [Open Loop Cards](/features/send-open-loop-cards).
</Update>

<Update label="v0.0.66" tags={["Improved"]} description="July 2026">
  * Updates to [Primary & backup funding page](https://docs.fluz.app/features/primary-and-backup-funding).
</Update>

<Update label="v0.0.65" tags={["Added"]} description="July 2026">
  * New API endpoint exposing account-related declined transactions. See [Get Declined Transactions](/features/get-decline-transactions).
</Update>

<Update label="v0.0.63" tags={["Added"]} description="June 2026">
  * `GiftCard.purchaseId` (UUID) — the purchase that created the gift card; the same ID returned by `purchaseGiftCard` and `getUserPurchases`. Returns `null` if no associated purchase.
  * `GiftCard.purchaseDisplayId` (String) — the short, human-readable Fluz transaction ID (e.g. `1047283`) that support references in manual reviews and exports. Returns `null` if no associated purchase.
  * `GiftCard.purchaseValue` (Float) — the face value (denomination) the gift card was purchased at, in the card's currency.
  * `GiftCard.currentValue` (Float) — the remaining balance on the gift card; equals `purchaseValue` for single-use cards.
  * `GiftCard.currency` (String) — the ISO currency code of the gift card's value (e.g. `USD`).

  All five fields are now returned by `getGiftCards` (and anywhere `GiftCard` is exposed), enabling order/value reconciliation without calling `revealGiftCardByGiftCardId` per card. Additive and backward-compatible.
</Update>

<Update label="v0.0.62" tags={["Added"]} description="June 2026">
  * Added Plaid Link support.
  * Updated Overview page with `llms.txt` information.
  * Updated header with AI link to `llms.txt`.
</Update>

<Update label="v0.0.60" tags={["Added"]} description="May 2026">
  * New `getCardProvisioningUrl` **query** — mints a short, single-use URL that, when opened on a mobile device, launches Fluz and adds a virtual card to Apple Pay (iOS) or Google Pay (Android). Surface it as a QR code, SMS, email, or in-app button. Each URL expires \~5 minutes after creation. Requires the `CREATE_VIRTUALCARD` scope.
  * New input `GetCardProvisioningUrlInput { offerId, platform }`.
  * New enum `ProvisioningPlatform` (`IOS` | `ANDROID` | `OTHER`) — controls the desktop / unknown-device fallback only; iOS and Android opens are auto-routed.
  * New return type `CardProvisioningUrl { url, expiresAt }`.
</Update>

<Update label="v0.0.59" tags={["Improved"]} description="May 2026">
  * Added samples to [Generate Share Links](/features/generate-share-links).
</Update>

<Update label="v0.0.58" tags={["Added"]} description="May 2026">
  * Added `addVirtualCardAddress` mutation to save billing addresses for virtual card issuance.
  * Updated `createVirtualCard` mutation to support creating cards on behalf of authorized users.
  * Added full flow using `registerUser`, `addAuthorizedUser`, `addVirtualCardAddress`, and `createVirtualCard`.
  * Retry pending issuer approvals with `VC-0020` and returned `addressId`.
</Update>

<Update label="v0.0.57" tags={["Added"]} description="May 2026">
  * `redeemFluzGiftCard` — Redeem a Fluz Gift Card using a code. Credits `giftCardCashBalance`. Requires `MAKE_DEPOSIT`. See [Redeem a Fluz Gift Card](/features/redeem-fluz-gift-card).
  * `unlockVirtualCard` — Unlock a previously locked virtual card to restore transaction capability. Requires `EDIT_VIRTUALCARD`. See [Unlock a Virtual Card](/features/unlock-virtual-card).
</Update>

<Update label="v0.0.55" tags={["Improved"]} description="May 2026">
  **Transaction-related webhooks**

  * Added description for `TRANSACTION_CREATE`, `TRANSACTION_UPDATE` & `TRANSACTION_DECLINE` webhooks.
  * Included new fields after webhook enrichment (MCC-related, `virtualCardId`, etc.).
</Update>

<Update label="v0.0.54" tags={["Added"]} description="May 2026">
  * Added `mcc`, `merchantCountryCode`, `originalCurrencyCode`, `originalCurrencyAmount`, and `currencyConversionRate` to `VirtualCardTransaction`. Now returned by `getVirtualCardTransactions`.
  * Made `virtualCardIds` optional on `getVirtualCardTransactions` — omit to query transactions across all cards on the authenticated account. Added `dateRangeStart` and `dateRangeEnd` filters. Default `limit` of 100 when `virtualCardIds` is omitted; `limit` is capped at 500. `transactionAmount` is now nullable for rows without a settled amount (e.g., AVS-only decline records).
  * Added `usePrepaymentBalance` and `useRewardsBalance` to `CreateVirtualCardInput`. Now accepted by `createVirtualCard`. Both default to `true` (existing behavior preserved). Set both to `false` to restrict a card to drawing only from the specified `userCashBalanceId`, excluding prepaid (gift card) and rewards funds.
</Update>

<Update label="v0.0.53" tags={["Added"]} description="April 2026">
  * Added `shortDescription` (Merchant) and `termsAndConditions` (Offer). Now returned by `getMerchants` and `getOfferQuote`.
  * Added `deliveryFormat` (GiftCard). Now returned by `getGiftCards` — use `deliveryFormat` for purchased cards.
</Update>

<Update label="v0.0.52" tags={["Added"]} description="April 2026">
  * New `setVirtualCardPIN` mutation, allowing a user to set their PIN on eligible virtual cards. See [Set a Virtual Card PIN](/recipes/set-virtual-card-pin).
</Update>

<Update label="v0.0.51" tags={["Added"]} description="April 2026">
  * New `getUserCashBalances` & `getUserCashBalanceById` queries. These queries allow a user to retrieve a list of their spend accounts and a specific spend account created on their account.
</Update>

<Update label="v0.0.49" tags={["Added"]} description="April 2026">
  **Share Virtual Cards API**

  * New "Share Virtual Cards" capability under Manage Virtual Cards. Contact sales for access.
  * Added `CREATE_SHARE_LINK` scope to the [application scopes](/fluz-dashboard/application-scopes) page.
</Update>

<Update label="v0.0.45" tags={["Added"]} description="February 2026">
  **Business registration API**

  * New query `getBusinessCategories: [BusinessCategory]` for retrieving business categories, with response types `BusinessCategory` and `BusinessSubCategory`.
  * New mutation `registerBusiness(input: RegisterBusinessInput!): RegisterBusinessResult` for programmatic business registration.
  * New input types: `RegisterBusinessInput`, `BusinessLegalAddressInput`, `BusinessOwnerInput`, `OwnerAddressInput`.
  * New enums: `BusinessStructure` (`LLC`, `CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `COOP`) and `BusinessAccountUsage`.
  * New response types: `RegisterBusinessResult { accountId, kybStatus, success, error }` and `RegisterBusinessError { message, code }`.
  * Both operations require authentication with the `REGISTER_BUSINESS` OAuth scope.
</Update>

<Update label="v0.0.44" tags={["Improved"]} description="January 2026">
  **Updates to `getMerchants` query**

  * The `getMerchants` query now returns all available offers properly.
  * The `getMerchants` query can now return an `exclusiveRateId` field (within the `offers` object). This value can be used in `purchaseGiftCard` to specify the exclusive rate offer you want to purchase with.
</Update>

<Update label="v0.0.43" tags={["Added"]} description="December 2025">
  **Withdrawals & Spend Accounts APIs**

  * Added `withdrawCashBalance` mutation with `MAKE_WITHDRAWAL` scope requirement.
  * Added `WithdrawMethods` enum supporting `PAYPAL`, `BANK_ACH`, `BANK_CARD`, and `VENMO` methods.
  * Added `WithdrawSource` enum supporting `CASH_BALANCE` and `REWARDS_BALANCE` sources.
  * Added `WithdrawCashBalanceInput` with idempotency support, plus `Withdraw` and `WithdrawCashBalanceResponse` types with full withdrawal record details including fees, status, and timestamps.
  * Added `transferUserCashBalance` mutation with `MAKE_INTERNAL_TRANSFER` scope requirement, plus `TransferInternalBalanceInput` and `TransferInternalBalanceResponse` types.
  * Added `userCashBalanceId` to `EditVirtualCardInput` to enable changing the funding source to a specified spend account via `editVirtualCard`.
  * Added `userCashBalanceIds` to `TransactionFilterInput` for filtering transactions by spend accounts via `getTransactions`, and `userCashBalanceId` to `getGiftCards` for filtering gift cards by spend account.
  * Added `updateUserCashBalance` and `closeUserCashBalance` mutations with `MANAGE_PAYMENT` scope requirement, plus supporting input and response types (`UpdateUserCashBalanceInput`, `CloseUserCashBalanceInput`, `CloseUserCashBalanceResponse`, `ClosedUserCashBalance`, `CloseUserCashBalanceResponseVirtualCard`).
  * Added application action logging for audit trail.
</Update>

<Update label="v0.0.42" tags={["Added"]} description="November 2025">
  * Added new `userCashBalances` field to the `UserBalances` type in the `getWallet` query. Returns detailed information about individual user cash balance accounts with pagination via `paginate` (limit/offset), ordered by creation date (most recent first). Includes `userCashBalanceId`, `totalCashBalance`, `availableCashBalance`, `lifetimeCashBalance`, `nickname`, `status`, and `createdAt` — enabling tracking of multiple cash balance accounts per user with custom nicknames and status monitoring.
</Update>

<Update label="v0.0.40" tags={["Added"]} description="November 2025">
  * A new field `userCashBalanceId` is added to `DepositCashBalanceInput` to specify the cash balance (spend account) to deposit the funds into.
</Update>

<Update label="v0.0.39" tags={["Added"]} description="November 2025">
  * New mutations for managing saved bank cards: `updateBankCardNickname`, `updateBankCardPreferredMerchantCategoryCode`, and `deleteBankCard`, with corresponding input types.
  * `nickname` field added to the `BankCard` type.
  * Optional fields added to `AddBankCardInput`: `nickname` and `preferredMerchantCategoryCode` (MCC, normalized to 4 digits).
</Update>

<Update label="v0.0.37" tags={["Added"]} description="September 2025">
  * `getVirtualCardBalance`: new query retrieving balance information for a list of virtual cards, including `spentAmount`, `remainingBalance`, `spendLimit`, and `spendLimitDuration`.
  * `getVirtualCardTransactions`: new query retrieving transactions for a list of virtual cards, with filters such as `transactionTypes`.
</Update>

<Update label="v0.0.36" tags={["Improved"]} description="September 2025">
  * The `getUserPurchases` query now includes the ability to filter the purchases returned in the response via a new optional `UserPurchaseFilterInput` variable. Filter purchases made by the user, the account, or both.
</Update>

<Update label="v0.0.35" tags={["Added"]} description="September 2025">
  * The `revealVirtualCardByVirtualCardId` mutation response now includes a new `authorizationSetting` field.
  * **Bulk Virtual Card API**: new API for creating and managing a large number of virtual cards asynchronously.
  * `createVirtualCardBulkOrder` **mutation**: submit a bulk order and receive a unique `orderId`.
  * `getVirtualCardBulkOrderStatus` **query**: poll to track order status and retrieve card details upon completion.
  * The bulk card creation process is asynchronous — check order status to retrieve card details.
</Update>

<Update label="v0.0.32" tags={["Added"]} description="July 2025">
  * **New query `getVirtualCardOffers`**: comprehensive list of all active virtual card offers available for creation, including `offerId` (essential for card creation), `programName`, `bankName`, `rewardValue`, and detailed program limits (daily, weekly, monthly spend limits).
  * **Updated mutation `createVirtualCard`**: programmatically issue virtual cards by providing an `offerId` (from `getVirtualCardOffers`), a `spendLimit`, and customizable attributes like `cardNickname` and `spendLimitDuration`.
  * **New mutation `editVirtualCard`**: update key parameters of an existing virtual card — `spendLimit`, `spendLimitDuration`, `lockDate`, `lockCardNextUse`, and `cardNickname`.
  * **New mutation `lockVirtualCard`**: immediately lock a virtual card, preventing any further transactions.
</Update>

<Update label="v0.0.31" tags={["Added"]} description="July 2025">
  * The `Offer` type in the `getMerchants` response now includes a `deliveryFormat` field specifying how the offer is fulfilled: `URL`, `CODES`, `PIN_AS_CODE`, or `PIN_WITH_URL`.
  * The `getMerchants` query has been enhanced with a new `filterBy` argument, allowing you to filter results to only include merchants with offers matching a specific `deliveryFormat`.
</Update>

<Update label="v0.0.30" tags={["Added"]} description="2025">
  * Enhanced the `getMerchants` query with a new `offerTypes` input argument, allowing filtering by `giftCardOffer`s, `cardLinkedOffer`s, or both. By default, if `offerTypes` is not provided, the query returns only gift card offers.
</Update>

<Update label="v0.0.29" tags={["Added","Improved"]} description="2025">
  * Introduced a new query `getReferralUrl` which returns a referral string based on merchant input, with a new `MerchantInput` type.
  * Introduced an automatic repurchase attempt on the `purchaseGiftCard` mutation. If a gift card purchase using a bank card, bank account, or PayPal fails, the system automatically attempts to repurchase using the Fluz balance.
  * Introduced the `defaultToBalance` field on `PurchaseGiftCardInput` to set the Fluz balance as the fallback payment method if the primary payment method fails. Defaults to `true`.
</Update>

<Update label="v0.0.27" tags={["Added","Improved"]} description="2025">
  * Introduced a new access scope, `CREATE_VIRTUALCARD`, to create virtual cards.
  * Introduced a new function, `createVirtualCard`, to create virtual cards with specific parameters.
  * Added new query, `getBINs`, to retrieve BINs associated with virtual cards.
  * Introduced a `merchantCategoryCode` input for cash balance deposits, allowing for enhanced categorization of transactions.
  * Added a new query, `getMccList`, to retrieve a list of merchant category codes.
  * Enhanced scope validation for the `getApplicationScopes` query and improved GraphQL type definition management.
</Update>

<Update label="v0.0.26" tags={["Improved"]} description="2025">
  * Enhanced the handling of stock information for merchant offers: the `Offer` object's `stockInfo` field now returns either `StockInfoFixedType` or `StockInfoVariableType` depending on whether the offer is fixed or variable.
  * Enhanced error handling with more intuitive error message responses — improved responses for `purchaseGiftCard` no-offer errors and mismatched account and payment methods.
</Update>

<Update label="v0.0.17 – v0.0.21" tags={["Added","Fixed"]} description="2025">
  **v0.0.21**

  * Introduced an `idempotencyKey` parameter for `depositCashBalance` and `purchaseGiftCards` to prevent duplicate requests.
  * Added `purchaseGiftCardInput` types to streamline parameter handling for transactions.
  * Introduced a new field `purchaseDisplayId` on the `UserPurchase` type, providing a display ID for purchases.
  * Fixed the `Offer` object's `offeringMerchantId` field to return `offering_merchant_id` instead of `offer_id`.

  **v0.0.20**

  * Added `accountId` requirement to `generateUserAccessToken`.
  * Implemented a new query, `getAccountsByUserId`, to fetch accounts based on `userId`.
  * Added a new `AccountType` enum to categorize accounts as `CONSUMER` or `BUSINESS`, plus new `Account`, `Business`, and `Seat` objects.

  **v0.0.17**

  * Fixed `depositCashBalance` platform channel input so the deposit transaction log source is logged as `API`.
</Update>

## Change management

Additive changes (new fields, new enum values, new operations) are announced at least **7 days** before release when they require action from integrators. Breaking changes are announced at least **14 days** in advance and are typically batched into major release windows.

For a complete list of API operations, see the [API reference](/api-reference/overview).