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 freeze / unfreeze (state), funding source updates (fundingSource), per-transaction spending limits (maxSpendPerTransaction), UTC-calendar-day spending limits (maxSpendPerDay), and UTC-calendar-day transaction limits (maxTransactionsPerDay). See Funding source for the funding-source-only flow.

​
Valid state transitions

Any other transition returns 409 INVALID_STATE_TRANSITION. In particular, you cannot un-freeze a CLOSED card — close is terminal. You can also combine a state change with a funding source replacement in one PATCH — just include both fields in the body. On card programs where the card issuer makes the authorization decision, send them as separate requests instead.
The response is 200 OK with the updated Card and a CARD.STATE_CHANGE webhook.

​
What freeze does

Setting a card to FROZEN:
  • Causes Authorization Decisioning to decline new auths with CARD_PAUSED.
  • Does not pause the lifecycle of authorizations that already passed. Pulls, clearings, and refunds against existing transactions continue to reconcile normally.
  • Emits CARD.STATE_CHANGE with state: "FROZEN".
Unfreeze (state: "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 state: "CLOSED". The operation is permanent:
  • Card state transitions to CLOSED, stateReason: "CLOSED_BY_PLATFORM".
  • All pending authorizations reconcile to a terminal state via the existing reconcile primitive.
  • The funding source is 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.STATE_CHANGE fires with state: "CLOSED".
fundingSource cannot be supplied alongside state: CLOSED. 409 CARD_ALREADY_CLOSED is returned if the card is already in the terminal CLOSED state.

​
Updating the per-transaction limit

To set or change the per-transaction spending limit:
Supply a positive integer to set the limit (in the smallest unit of the card’s currency) or null to clear it. Omitting the field leaves the current limit unchanged. maxSpendPerTransaction cannot be supplied alongside state: CLOSED.

​
Updating the daily limit

Set maxSpendPerDay to a positive integer in the smallest unit of the card’s currency, or set it to null to clear the card-specific daily limit. The window resets at 00:00 UTC. Refunds, reversals, and authorization expiries do not restore capacity during the same day.

​
Updating the daily transaction limit

Set maxTransactionsPerDay to a positive integer to cap how many transactions the card may authorize per UTC calendar day, or set it to null to clear the card-specific cap. Each approved authorization counts once; refunds, reversals, and authorization expiries do not restore capacity during the same day.

​
Sandbox behavior

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