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

# Card status, locks & limits

> What each VirtualCardStatus means, why a locked card still reads ACTIVE, how to read a card's current limit, and how cards are closed.

## Status and lock are separate

`status` describes where the card is in its lifecycle. Whether it can authorize right now is a separate question, answered by its **lock** fields. A locked card still reports `status: ACTIVE`.

| `VirtualCardStatus` | Meaning |
| :- | :- |
| `PENDING` | Card created; issuance not yet complete |
| `ACTIVE` | Issued and open. Check the lock fields to see whether it can authorize |
| `USED` | Used; applies mainly to single-use cards |
| `CANCELLED` | Closed permanently |
| `REFUNDED` | The card's underlying purchase was refunded |
| `EXPIRED` | Closed by the expiry process |
| `DISPUTED` | In a dispute |

`LOCKED` and `CLOSED_EXPIRED` are not status values. 

### Telling a locked card from an open one

Read `authorizationSetting`:

| Field | Meaning |
| :- | :- |
| `lockedByUser` | Locked with `lockVirtualCard` |
| `lockedBySystem` | Locked by Fluz, for example by risk controls |
| `lockCardNextUse` | Locks itself after its next transaction |
| `lockDate` | Locks itself at this time |

A card is usable only when `status` is `ACTIVE` and no lock applies.

### After `lockDate` passes

The card stays `ACTIVE` but declines as locked. It doesn't become `EXPIRED`. You can reopen a multi-use card:

* call `unlockVirtualCard`, optionally passing a new lock date; or
* call `setVirtualCardLockDate` with a future date, or clear it.

## Reading a card's current state and limit

Query `getVirtualCards`, filtered to the card:

```graphql theme={null}
query ($filter: VirtualCardFilterInput) {
  getVirtualCards(filter: $filter) {
    rows {
      virtualCardId
      status
      authorizationSetting {
        dailySpendLimit weeklySpendLimit monthlySpendLimit
        annualSpendLimit lifetimeSpendLimit
        lockDate lockedByUser lockedBySystem lockCardNextUse
      }
    }
  }
}
```

<Note>
  `initialAmount` is the amount requested when the card was created. It never changes, so it isn't the current limit. Read the current limit from the `authorizationSetting` limit that matches the card's duration.
</Note>

### Changing the limit

Send `spendLimit` **and** `spendLimitDuration` together on `editVirtualCard`. Sending only `spendLimit` may not apply the change. Confirm it by re-reading `authorizationSetting`, not `initialAmount`.

## Closing a card permanently

There is no public mutation to cancel a card. For a temporary stop, use `lockVirtualCard`. To cancel permanently, contact support with the `virtualCardId`. `VC-0008 UNABLE_TO_CANCEL` comes from that support-side process.

When a card is cancelled, its unspent funded balance goes back through the refund process. Authorizations that haven't cleared are cleaned up with the card's purchase; timing depends on the network. Locking a card doesn't release its balance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.