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