> ## Documentation Index
> Fetch the complete documentation index at: https://agents-docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Freezing & Closing Cards

> Freeze, unfreeze, and close cards via the signed-retry pattern

Freeze, close, and other card updates use a single authenticated
`PATCH /cards/{id}` request and return the updated card with `200 OK`.

`PATCH /cards/{id}` covers status, funding source, and other card settings.
See [Funding sources](https://agents-docs.lightspark.com/cards/card-management/funding-sources.md) for the
funding-source-only flow and
[Velocity limits](https://agents-docs.lightspark.com/cards/card-management/velocity-limits.md) for amount and count
caps.

## Valid status transitions

| From | To | Endpoint |
| - | - | - |
| `ACTIVE` | `FROZEN` | `PATCH /cards/{id}` body `{ "status": "FROZEN" }` |
| `FROZEN` | `ACTIVE` | `PATCH /cards/{id}` body `{ "status": "ACTIVE" }` |
| `ACTIVE` or `FROZEN` | `CLOSED` | `PATCH /cards/{id}` body `{ "status": "CLOSED" }` |

Any other transition returns `409 INVALID_STATE_TRANSITION`. In
particular, you cannot un-freeze a `CLOSED` card — close is terminal.

`{ "status": "ACTIVE" }` also returns `409 INVALID_STATE_TRANSITION` when:

* the customer is not `ACTIVE`;
* Grid froze the card for review; or
* the card was frozen with substatus `COMPROMISED`, including by you.

Contact Grid support to have a card reviewed. A compromised card cannot be
unfrozen: close it and issue a new one. Once a suspended customer is
`ACTIVE` again, you can unfreeze cards that were frozen only because of the
suspension.

You can also combine a status change with a funding source replacement
in one PATCH — just include both fields in the body.

```bash theme={null}
curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "FROZEN" }'
```

The response is `200 OK` with the updated `Card` and a
`CARD.STATUS_CHANGE` webhook.

## What freeze does

Setting a card to `FROZEN`:

* Causes Authorization Decisioning to decline new auths with
  `cardDeclinedReason: CARD_NOT_ACTIVE`.
* Does **not** pause the lifecycle of authorizations that already
  passed. Pulls, clearings, and refunds against existing transactions
  continue to reconcile normally.
* Emits `CARD.STATUS_CHANGE` with `status: "FROZEN"`.

Unfreeze (`status: "ACTIVE"`) reverses this — new auths flow normally
again.

## What close does

Closing a card is done with the same `PATCH /cards/{id}` endpoint by
setting `status: "CLOSED"`. The operation is permanent:

* Card status transitions to `CLOSED`, `statusReason: "CLOSED_BY_PLATFORM"`.
* All pending authorizations reconcile to a terminal state via the
  existing reconcile primitive.
* Funding-source bindings are detached. Refunds already in flight
  continue to complete because Lightspark holds the card-reserve keys.
* Inbound clearings received after close follow the standard
  force-post / late-presentment path — Lightspark absorbs the loss if
  a post-hoc pull on the now-unbound source fails.
* `CARD.STATUS_CHANGE` fires with `status: "CLOSED"`.

```bash theme={null}
curl -X PATCH "$GRID_BASE_URL/cards/Card:019542f5-b3e7-1d02-0000-000000000010" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'
```

`fundingSource` cannot be supplied alongside `status: CLOSED`.
`409 CARD_ALREADY_CLOSED` is returned if the card is already in the
terminal `CLOSED` state.

## Managing velocity limits

Use [Velocity limits](https://agents-docs.lightspark.com/cards/card-management/velocity-limits.md) to configure
per-authorization, daily, rolling, and other calendar-window amount and count
caps. `PATCH /cards/{id}` changes the card's status and other card settings;
velocity limits are managed through `/card-velocity-limits`.

## Sandbox behavior

In Sandbox the status changes are instant — no issuer round-trip is
simulated. The request and response shape is the same as production.


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