POST/v1/cards/:id/freeze

Freeze a card

Blocks spending on the card until it is unfrozen. The card and its balance stay intact.

Required scope: cards.writeRate limit: 10 rps

Parameters

idstringrequired

The card ID.

Idempotency-Keystringrequired

Required, at least 8 characters. A replayed key returns the stored answer instead of toggling the card a second time.

Code samples

curl -X POST "https://samaprime.com/api/v1/cards/smsord_01J8X9AABBCCDD/freeze" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0e7f5c1e-2b3a-4f6d-9c8b-1a2b3c4d5e6f"

Response

→ 200
{
  "data": {
    "id": "cm_card_01J8Z1A2BBCCDD",
    "status": "frozen"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

Errors

Status	Code
404	`not_found` No card with this ID belongs to you at this store.
409	`suspended_by_provider` The issuer already suspended this card, which is a different state from a freeze you set yourself.
409	`provider_error` The issuer refused the freeze. The card is unchanged by this call — neither frozen nor unfrozen.
400	`idempotency_key_required` There is no Idempotency-Key header, or it is shorter than 8 characters. Required even though a freeze moves no money: the same toggle must not be applied twice.
403	`test_key_not_allowed` A test key (sk_test_) cannot move money: card writes need a live key. Nothing was reserved and the wallet was not touched.