Skip to main content
PATCH
JavaScript

Authorizations

Authorization
string
header
required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-08-10"

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.

billing
object

New billing address. Requires line1, city, region, postal_code, and country_code. On an invited card, passing billing alone (as the invited user) completes onboarding and starts card provisioning.

canceled
boolean

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

frozen
boolean

Pass true to freeze the card, false to unfreeze it. The assigned cardholder may freeze their own card without the payout:account:update scope.

name
string

A display name for the card.

pin
string

New 4-digit PIN. Can only be set on a card assigned to the acting user, who may set it without the payout:account:update scope.

remove_limit
boolean

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

spend_limit
number

Spending limit amount, in dollars.

spend_limit_frequency
enum<string>

The window the spend limit applies to.

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

Per-transaction limit amount, in dollars.

user_id
string

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

Response

invited card onboarding completed: card provisioning started

billing
object | null
required

The billing address.

canceled_at
string<date-time> | null
required

When the card was canceled.

created_at
string<date-time> | null
required

When the card was created.

expiration_month
string | null
required

Card expiration month.

expiration_year
string | null
required

Card expiration year.

id
string
required

Card ID, prefixed icrd_.

last4
string | null
required

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

limit
object | null
required

The spending limit configuration.

name
string | null
required

Card display name.

object
enum<string>
required
Available options:
card
spent_last_month
integer | null
required

Total spend in the last 30 days, in cents.

status
enum<string> | null
required

The card status. denied means the issuer declined the cardholder, so the card will never be issued.

Available options:
null,
active,
frozen,
canceled,
invited,
denied
type
enum<string> | null
required

The card type.

Available options:
null,
virtual,
physical
user_id
string | null
required

Cardholder user ID, prefixed user_, when assigned.

secrets
object | null

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