Sign in
OpenAPI 3.1.02026-08-143874115.7 MB

a84d4905fdbb

Cards

Update Card

Update, freeze, or cancel a card. Updating the card's name, billing address, or limits requires both payout:account:update and company:balance:read; a card's assigned holder may update their own card's pin and frozen state with any user token.

patch/cards/{card_id}

Request body

account_idstring

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

canceledboolean

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

frozenboolean

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

namestring

A display name for the card.

pinstring

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_limitboolean

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

spend_limitnumber

Spending limit amount, in dollars.

spend_limit_frequency'daily' | 'weekly' | 'monthly' | 'one_time'

The window the spend limit applies to.

transaction_limitnumber

Per-transaction limit amount, in dollars.

user_idstring

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

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "billing": {
    "city": "Austin",
    "country_code": "US",
    "line1": "4180 Burnet Rd",
    "line2": "Suite 210",
    "postal_code": "78756",
    "region": "TX"
  },
  "canceled": true,
  "frozen": true,
  "name": "Detailing supplies",
  "pin": "1234",
  "remove_limit": true,
  "spend_limit": 2500,
  "spend_limit_frequency": "monthly",
  "transaction_limit": 500,
  "user_id": "user_xxxxxxxxxxxxxx"
}

Response

invited card onboarding completed: card provisioning started

canceled_atstring date-time nullable required

When the card was canceled.

created_atstring date-time nullable required

When the card was created.

expiration_monthstring nullable required

Card expiration month.

expiration_yearstring nullable required

Card expiration year.

idstring required

Card ID, prefixed icrd_.

last4string nullable required

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

namestring nullable required

Card display name.

object'card' required
spent_last_monthinteger nullable required

Total spend in the last 30 days, in cents.

status'null' | 'active' | 'frozen' | 'canceled' | 'invited' | 'denied' nullable required

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

type'null' | 'virtual' | 'physical' nullable required

The card type.

user_idstring nullable required

Cardholder user ID, prefixed user_, when assigned.

Example response

{
  "billing": {
    "city": "Austin",
    "country_code": "US",
    "line1": "4180 Burnet Rd",
    "line2": "Suite 210",
    "postal_code": "78756",
    "region": "TX"
  },
  "canceled_at": "2026-01-01T12:00:00.000Z",
  "created_at": "2026-01-01T12:00:00.000Z",
  "expiration_month": "12",
  "expiration_year": "2027",
  "id": "icrd_xxxxxxxxxxxxxx",
  "last4": "4242",
  "limit": {
    "amount": 50,
    "frequency": "daily"
  },
  "name": "Detailing supplies",
  "object": "card",
  "spent_last_month": 1234,
  "status": "active",
  "type": "virtual",
  "user_id": "user_xxxxxxxxxxxxxx"
}