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

​
Valid status transitions

Every status change requires substatus (why the card is moving, in the issuer’s vocabulary) and reason (a short sentence explaining the change). See the API reference for the full list of substatus values. 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 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.

​
Updating the per-transaction limit

To set or change the per-transaction spending limit:
Send a positive integer to set the limit (in the smallest unit of the card’s currency, so cents for USD) or null to remove it. Omit the field to leave the current limit unchanged. An authorization for exactly the limit is allowed, and a later clearing can still settle above it (e.g. a restaurant tip) — the limit caps the authorization, not the final settled amount. You cannot send maxSpendPerTransaction together with status: 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 status changes are instant — no issuer round-trip is simulated. The request and response shape is the same as production.