---
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

## Changes

- **2026-07-14** `7d755c9f44ae` — 2 info
  - added the optional property `merchantLock` to the response with the `200` status
  - added the required property `categoryLocks` to the response with the `200` status
- **2026-06-16** `0a8c6d8f2716` — 1 warning, 1 info
  - added the new `yearly` enum value to the `spendLimit/allOf[#/components/schemas/SpendLimit]/interval/allOf[#/components/schemas/SpendLimitInterval]/` response property for the response status `200`
  - added the new `yearly` enum value to the request property `spendLimit/allOf[#/components/schemas/SpendLimit]/interval/allOf[#/components/schemas/SpendLimitInterval]/`
- **2026-04-30** `4a79a63a7c6a` — 4 breaking
  - added `#/components/schemas/NicknameUpdate, subschema #2` to the `nickname` request property `allOf` list
  - the request property `nickname` became not nullable
  - the request property `nickname` became required
  - the `nickname` request property type/format changed from `string`/`` to ``/``
- **2026-04-28** `314f542b4d39` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/cards/:cardId/post.md)

---

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