---
title: "List cards"
method: GET
path: "/cards"
tags: ["Cards"]
---

# List cards

`GET /cards`

Retrieve a paginated list of cards.

## Query parameters

- `accountId` string[] — Filter cards by one or more account IDs.
- `status` string[] — Filter cards by one or more statuses.
- `type` string[] — Filter cards by type (virtual or physical).
- `kind` string[] — Filter cards by kind (debit or credit).
- `userId` string — Filter cards by the cardholder's user ID.
- `limit` integer — Maximum number of results to return. Allowed range: 1 to 1000. Defaults to 500
- `order` 'asc' | 'desc' — Sort order. Can be 'asc' or 'desc'. Defaults to 'asc'
- `start_after` string, uuid — The ID of the card to start the page after (exclusive). When provided, results will begin with the card immediately following this ID. Use this for standard forward pagination to get the next page of results. Cannot be combined with end_before.
- `end_before` string, uuid — The ID of the card to end the page before (exclusive). When provided, results will end just before this ID and work backwards. Use this for reverse pagination or to retrieve previous pages. Cannot be combined with start_after.

## Response `200`

- CardListResponse
  - `cards` Card[], required — List of cards in the current page.
    - `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.
  - `page` object, required — Pagination cursors for navigating to next/previous pages.
    - `nextPage` string, uuid — Unique identifier for a card
    - `previousPage` string, uuid — Unique identifier for a card

## Other responses

- `400` — Invalid `end_before` or `start_after` or `order` or `limit` or `userId` or `kind` or `type` or `status` or `accountId`

---

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