Browse the docs

Update card

PATCH /v2/api-gateway/cards/{card_id}

Freezes (frozen: true) or unfreezes (frozen: false) the card, and/or replaces its metadata. Send at least one of the two; each is applied only when present, so you can change the metadata without touching the freeze state and the other way round. Returns { message } only — unlike V1 PATCH /card/{card_id}/freeze, the card is not returned, so read GET /cards/{card_id} to see the stored metadata.

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`card_id` required	string, uuid	Card UUID (the card `id` returned by the card endpoints).

Body

Field	Type	Description
`frozen`	boolean	`true` freezes the card, `false` unfreezes it. Omit to leave it as it is.
`metadata`	object	Your own key-value data to store on this card. It is returned verbatim on every read of the card and never affects how the card is processed — use it to carry your order or customer identifier so you do not have to keep a separate mapping. Up to 50 keys, keys up to 40 characters and values up to 500 characters. Values must be strings — nested objects, arrays, numbers and booleans are rejected. On update the map you send replaces the stored map in full: omit the field to leave it unchanged, send `{}` to clear it, and send a key with an empty string value to remove just that key.

Example request

cURL

curl --request PATCH \
     --url 'https://api.themooncard.com/v2/api-gateway/cards/7c9e6679-7425-40de-944b-e07fc1f90ae7' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "frozen": true,
       "metadata": {
         "order_id": "ORD-10294"
       }
     }'

Responses

200 Success

Field	Type	Description
`message` required	string	Human-readable confirmation of what happened. The wording is fixed per route — the response description on each operation quotes it — but it is not a stable machine key: branch on the 2xx status, not on this text.

JSON

{
  "message": "Card status updated successfully"
}

400 Error

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

404 Error

Card not found or not owned by you.

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated June 5, 2026