---
title: "Update a card"
method: POST
path: "/cards/{cardId}"
tags: ["Cards"]
---

# Update a card

`POST /cards/{cardId}`

Update a card's nickname or spending limits.

## Path parameters

- `cardId` string, uuid, required — Unique identifier for a card

## Request body

- UpdateCardRequest — At least one updateable field must be provided; requests where every field is the same are rejected.
  - `nickname` string, nullable, required — Updated card nickname. Omit to keep current, send null/empty to clear, send a string to set.
  - `spendLimit` object, nullable — Updated spending controls for the card. Omit to leave unchanged.
    - `amountCents` integer, required — Maximum total spend allowed per interval, in cents.
    - `atmAmountCents` integer, nullable — Maximum ATM withdrawal allowed per interval, in cents. Null for virtual cards.
    - `interval` 'daily' | 'weekly' | 'monthly' | 'yearly', required — Rolling window the limit applies to.

## Response `200`

- Card
  - `accountId` string, required — The Mercury account this card is associated with.
  - `categoryLocks` MercuryCategory[], required — Mercury spend-category locks applied to this card, in no particular order. Empty when the card has no category restrictions.
  - `createdAt` string, yyyy-mm-ddThh:MM:ssZ, required — Timestamp when the card was issued.
  - `expiration` object, required — Month and year the card expires.
    - `month` integer, required — Calendar month.
    - `year` integer, required — Four-digit calendar year.
  - `id` string, uuid, required — Unique identifier for the card.
  - `kind` 'debit' | 'credit', required — Whether the card is a debit or credit card.
  - `lastFour` string, required — Last four digits of the card's primary account number (PAN).
  - `merchantLock` object, nullable — Merchant lock applied to this card. Present only when the card is locked to a single merchant; otherwise omitted.
    - `id` string, uuid, required
    - `name` string, required
  - `nameOnCard` string, required — Cardholder name printed on the card.
  - `nickname` string, nullable — Optional user-assigned label for the card.
  - `physicalCardStatus` 'inactive' | 'active' | 'locked', nullable — Activation state of a physical card. Null for virtual cards.
  - `spendLimit` object, nullable — Spending controls applied to this card.
    - `amountCents` integer, required — Maximum total spend allowed per interval, in cents.
    - `atmAmountCents` integer, nullable — Maximum ATM withdrawal allowed per interval, in cents. Null for virtual cards.
    - `interval` 'daily' | 'weekly' | 'monthly' | 'yearly', required — Rolling window the limit applies to.
  - `status` 'active' | 'frozen' | 'cancelled' | 'inactive' | 'expired' | 'suspended', required — Current lifecycle state of the card.
  - `type` 'virtual' | 'physical', required — Whether the card is virtual (digital-only) or physical (printed, supports ATM).
  - `updatedAt` string, yyyy-mm-ddThh:MM:ssZ, required — Timestamp of the last modification to the card or its settings.
  - `userId` string, required — Mercury User who owns the card.

## Other responses

- `400` — Invalid `body`
- `404` — `cardId` not found

---

[API](https://skmtc.net/mercurytechnologies/apis/mercury-api.md) · [All operations](https://skmtc.net/mercurytechnologies/apis/mercury-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mercurytechnologies/mercury-api/versions/0bdf4a496e03/schema)