Skip to main content
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 for the funding-source-only flow and Velocity limits for amount and count caps.

​
Valid status transitions

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