Manage card status

Freeze, unfreeze or block a card, and change its daily limit, with one update that always sends both status and limit.

This page shows how to freeze, unfreeze or block a card and how to change its daily limit. Update card status changes a card's status, its daily limit, or both. It takes no Idempotency-Key.

A money example. Ada's card has a 300 USD daily limit. For a trip, she needs to pay a 750 USD hotel, so you send {"status": "active", "limit": 1000}. After the trip, you send {"status": "active", "limit": 300}. When she loses her phone, you send {"status": "freeze", "limit": 300}, and the card keeps its limit.

Send status and limit on every call. An update without limit saves the limit as 0. In live, a limit of 0 declines every payment. In sandbox, 0 means no limit, so the card loses its cap. Read the current limit first with Get card (spending_controls.daily_transaction_limit).

Status	Meaning
`active`	The card can spend
`freeze`	The card is stopped for now. `balance` reads 0 while the card is frozen
`blocked`	The card is closed for good. You cannot unblock it or withdraw from it

You can change a card's status in these ways:

From active to freeze or blocked
From freeze to active or blocked
From inactive to active or blocked

curl --request PATCH \
     --url https://api.gravv.xyz/v1/cards/a14ec356-f33d-4384-ba68-4d9bfa19765b/update \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "status": "freeze",
  "limit": 300
}
'

The response is the whole card, as Get card returns it. To change only the limit, send the card's current status with the new limit. limit is a whole number of US dollars per day (an integer, such as 1000).

When the status changes, Gravv sends the cards.status.update webhook with event_data.card.status. Gravv sends no webhook for a limit-only change, or for an update that sends the status the card already has.

If you use a scoped API key, it needs the card:freeze or card:terminate scope.

What can go wrong

Response	Why	Fix
400 `status is required`	You sent only `limit`, or you left out the `Content-Type: application/json` header, so the API did not read the body	Send both fields with the header
400 `json: cannot unmarshal number 1000.5 into Go struct field Body.limit of type int`	`limit` was a decimal or a string	Send a whole number
400 `card is blocked and cannot be updated`	The card is blocked	Issue a new card
400 `invalid status selected`	The status is not `active`, `freeze` or `blocked`	Use one of those values
400 `internal server error` on a freeze	The status change is not allowed, such as `inactive` to `freeze`	Use an allowed change. Read the card back, and contact support if it looks wrong
400 `card status changed concurrently, please retry`	Two updates arrived at the same time	Retry
400 `card does not exist`	The card id is wrong	Check the id