Skip to main content
PATCH
Update a card
Sandbox only. This endpoint is available in sandbox only while we finish development. It is not available in production yet, and its request and response shapes may change before release.

Authorizations

x-api-key
string
header
required

Headers

x-idempotency-key
string<uuid>
required

Unique key to ensure request idempotency. If the same key is used within a certain time window, the original response will be returned instead of executing the request again.

Path Parameters

card_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

Body

application/json

Card fields to update

A status change (freeze/unfreeze/close), a new nickname, or both. A nickname sent alongside status: closed is ignored — the card is closed and its label is no longer reachable. The spend limit changes through PUT /cards/{card_id}/spend_limit.

status
enum<string>

The transition to apply. active unfreezes, frozen freezes, and closed is terminal.

Cardholder state takes precedence over card state: while the owning cardholder is suspended, active is refused with a #cardholder-suspended 403 and the card stays frozen. frozen and closed are unaffected — a suspension restricts what a client can re-enable, never what it can shut down.

Available options:
active,
frozen,
closed
nickname
string | null

Replacement display name for the card. Omit the field, or send null, to leave the current nickname unchanged; there is no way to clear one once set.

Maximum string length: 64
Example:

"Travel card"

Response

Card updated successfully

Response containing card details.

id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

cardholder_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

customer_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

wallet_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

version
integer<int64>
required

The card's version, strictly increasing for this card. It is bumped by one on every change that emits a card.created or card.updated event, including a request that changes nothing, and the same value appears as version in that event's payload. Webhook deliveries can arrive out of order, and updated_at has only one-second resolution, so neither orders them. Keep the highest version you have applied for each card and drop any event or response whose version is not greater than it.

Required range: x >= 1
Example:

7

status
enum<string>
required

Current status of the card. Returns pending on create; flips to active via a card.updated webhook.

Available options:
pending,
active,
frozen,
closed
Example:

"pending"

created_at
integer
required

Unix timestamp (seconds) of creation.

updated_at
integer
required

Unix timestamp (seconds) of last update.

last4
string | null

Non-sensitive last four digits, populated from the card provider.

Example:

"4242"

spend_limit
Spend Limit · object | null

A single cap on card spend, enforced when a purchase is authorized.

external_id
string | null
nickname
string | null

Client-supplied display name for the card. Null when none was set.

Maximum string length: 64
Example:

"Ads card"

freeze_sources
enum<string>[]

What is currently holding a freeze on this card, distinct and sorted. Empty when nothing is. A card is frozen while any source holds it, and lifting one source does not lift another. Read this rather than inferring the cause from status: status reports the card's state at the issuer, so it says only that the card is frozen, never why. manual is a freeze applied through this API and is the only source a client can lift, by sending status: active to this card's PATCH endpoint. While any other source is present that request is rejected with a card-freeze-held problem, because no card-level action will clear it.

What is holding a freeze on a card.

manual is a freeze applied deliberately through this API, and is the only source a client can lift. It is the only value this API emits today.

This enum grows as new freeze causes are built — a value is added when it can actually occur, never before. Treat any value other than manual, including one your client does not recognise, as a hold no card-level request will clear.

Available options:
manual
Example:
cardholder
Cardholder Response · object

The cardholder this card belongs to.

wallet
Card Wallet Response · object

The wallet this card draws on. Populated on the single-card detail endpoint; omitted from list responses.