Skip to main content
PATCH
/
cards
/
{card_id}
Update Card
curl --request PATCH \
  --url https://{defaultHost}/cards/{card_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "spend_limit": 123,
  "transaction_limit": 123,
  "remove_limit": true,
  "pin": "<string>",
  "frozen": true,
  "canceled": true
}
'
{
  "object": "card",
  "id": "<string>",
  "name": "<string>",
  "last4": "<string>",
  "expiration_month": "<string>",
  "expiration_year": "<string>",
  "user_id": "<string>",
  "spent_last_month": 123,
  "limit": {
    "amount": 123,
    "frequency": "<string>"
  },
  "billing": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country_code": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "canceled_at": "2023-11-07T05:31:56Z",
  "secrets": {
    "card_number": "<string>",
    "cvc": "<string>",
    "name_on_card": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

An account API key, account scoped JWT, app API key, or user OAuth token.

Headers

​
Api-Version-Date
string<date>

Pins the request to a dated API version.

Example:

"2026-07-01"

Path Parameters

​
card_id
string
required

Card ID to retrieve, prefixed icrd_.

Body

application/json
​
account_id
string

The owning account ID (a biz_ identifier). Provide this or user_id.

​
user_id
string

The owning user ID (a user_ identifier). Provide this or account_id.

​
name
string

A display name for the card.

​
billing
object

New billing address. Requires line1, city, region, postal_code, and country_code.

​
spend_limit
number

Spending limit amount, in dollars.

​
spend_limit_frequency
enum<string>

The spending limit window.

Available options:
daily,
weekly,
monthly,
one_time
​
transaction_limit
number

Per-transaction limit amount, in dollars.

​
remove_limit
boolean

Pass true to remove the spending limit (make the card unlimited).

​
pin
string

New 4-digit PIN. Can only be set on a card assigned to the acting user.

​
frozen
boolean

Pass true to freeze the card, false to unfreeze it.

​
canceled
boolean

Pass true to permanently cancel the card. A canceled card cannot be uncanceled. Cannot be combined with other fields.

Response

card canceled

​
object
enum<string>
required
Available options:
card
​
id
string
required

Card ID, prefixed icrd_.

​
name
string | null
required

Card display name.

​
type
enum<string> | null
required

The card type.

Available options:
null,
virtual,
physical
​
status
enum<string> | null
required

The card status.

Available options:
null,
active,
frozen,
canceled,
invited
​
last4
string | null
required

Last four digits of the card number. null for pending invitation cards.

​
expiration_month
string | null
required

Card expiration month.

​
expiration_year
string | null
required

Card expiration year.

​
user_id
string | null
required

Cardholder user ID, prefixed user_, when assigned.

​
spent_last_month
integer | null
required

Total spend in the last 30 days, in cents.

​
limit
object
required

The spending limit configuration.

​
billing
object
required

The billing address.

​
created_at
string<date-time> | null
required

When the card was created.

​
canceled_at
string<date-time> | null
required

When the card was canceled.

​
secrets
object

Sensitive card details. Present only on GET /cards/:card_id for active cards; null when the card is inactive or details cannot be retrieved.