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

# List cards

`GET /cards`

Retrieve a paginated list of cards. Cards can be filtered by cardholder, bound funding-source internal account, state, and platform-specific card identifier. If no filters are provided, returns all cards visible to the caller.

## Query parameters

- `cardholderId` string
- `accountId` string
- `platformCardId` string
- `state` 'PENDING_KYC' | 'PROCESSING' | 'ACTIVE' | 'FROZEN' | 'CLOSED' — Lifecycle state of a card. | State | Description | |-------|-------------| | `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this state cannot transact. | | `PROCESSING` | The card has been requested and is being provisioned with the issuer. | | `ACTIVE` | The card is live and can authorize transactions. | | `FROZEN` | The card is temporarily disabled by the platform. New authorizations are declined with `CARD_PAUSED`. Existing settlements and refunds continue to reconcile. | | `CLOSED` | The card is permanently closed. Terminal, irreversible state. |
- `limit` integer
- `cursor` string
- `sortOrder` 'asc' | 'desc'

## Response `200`

Successful operation

- CardListResponse
  - `data` Card[], required — List of cards matching the filter criteria
    - `id` string, required — System-generated unique card identifier
    - `cardholderId` string, required — The id of the `Customer` who holds this card.
    - `platformCardId` string — Platform-specific card identifier. Optional on create — system-generated if omitted, mirroring `platformCustomerId` semantics.
    - `state` 'PENDING_KYC' | 'PROCESSING' | 'ACTIVE' | 'FROZEN' | 'CLOSED', required — Lifecycle state of a card. | State | Description | |-------|-------------| | `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this state cannot transact. | | `PROCESSING` | The card has been requested and is being provisioned with the issuer. | | `ACTIVE` | The card is live and can authorize transactions. | | `FROZEN` | The card is temporarily disabled by the platform. New authorizations are declined with `CARD_PAUSED`. Existing settlements and refunds continue to reconcile. | | `CLOSED` | The card is permanently closed. Terminal, irreversible state. |
    - `stateReason` 'ISSUER_REJECTED' | 'CLOSED_BY_PLATFORM' | 'CLOSED_BY_GRID' — Reason a card reached a terminal or non-active state. Present on `CLOSED` cards, and on cards that fail provisioning before reaching `ACTIVE`. | Reason | Description | |--------|-------------| | `ISSUER_REJECTED` | The card issuer rejected provisioning during `PROCESSING`. | | `CLOSED_BY_PLATFORM` | The card was closed via `PATCH /cards/{id}` (`state: CLOSED`) by the platform. | | `CLOSED_BY_GRID` | The card was closed by Grid (e.g. compliance or risk action). |
    - `brand` 'VISA' | 'MASTERCARD' — Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer.
    - `form` 'VIRTUAL', required — Physical form factor of the card. Only `VIRTUAL` is supported in v1; `PHYSICAL` will be added in a later release.
    - `last4` string — Last four digits of the card PAN.
    - `expMonth` integer — Card expiration month (1–12).
    - `expYear` integer — Card expiration year (four digits).
    - `fundingSources` string[], required — Internal account ids bound to this card as funding sources, in priority order — the first entry is tried first by Authorization Decisioning. Every card has at least one funding source.
    - `maxSpendPerTransaction` integer, nullable, required — Card-specific cap on a single transaction, in the smallest unit of the card's `currency`. Null means the card has no card-specific cap. When the platform config also supplies `cardConfigs.maxSpendPerTransaction`, Grid enforces the lower of the two values without replacing this configured value. A transaction for exactly the effective limit is allowed.
    - `maxSpendPerDay` integer, nullable, required — Card-specific cap on cumulative new spend during one UTC calendar day, in the smallest unit of the card's `currency`. The window resets at 00:00 UTC. Null means the card has no card-specific daily cap. When the platform config also supplies `cardConfigs.maxSpendPerDay`, Grid enforces the lower of the two values without replacing this configured value. Refunds, reversals, and authorization expiries do not restore capacity during the day. Spend exactly equal to the effective limit is allowed.
    - `currency` string — Currency the card transacts in (ISO 4217 for fiat, tickers for crypto). Derived from the funding sources at issue time — all funding sources bound to a card must be denominated in the same card-eligible currency.
    - `processorRef` string — Opaque processor-side reference for the card (e.g. the Lithic card token). Useful for cross-referencing in the processor's dashboards; not used for any Grid request routing.
    - `issuerRef` string — Opaque identifier for the card on the issuer of record (e.g. the Lead Bank account/card identifier). Useful for cross-referencing in issuer dashboards; not used for any Grid request routing.
    - `createdAt` string, date-time, required — Creation timestamp
    - `updatedAt` string, date-time, required — Last update timestamp
  - `hasMore` boolean, required — Indicates if more results are available beyond this page
  - `nextCursor` string — Cursor to retrieve the next page of results (only present if hasMore is true)
  - `totalCount` integer — Total number of cards matching the criteria (excluding pagination)

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `500` — Internal service error
- `501` — Not implemented in this environment. Cards are not enabled for every Grid deployment; environments without a configured card issuer return `501 NOT_IMPLEMENTED`.

## Changes

- **2026-09-03** `f560bb38e8d1` — 1 info
  - added the required property `data/items/maxSpendPerDay` to the response with the `200` status
- **2026-08-22** `c3db0ca19655` — 1 info
  - added the required property `data/items/maxSpendPerTransaction` to the response with the `200` status
- **2026-08-14** `aaa1fb8782c8` — 1 warning
  - added the new `EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED` enum value to the `code` response property for the response status `400`
- **2026-08-13** `df12ec487f0e` — 1 warning
  - added the new `TRANSACTION_SIZE_LIMIT_EXCEEDED` enum value to the `code` response property for the response status `400`
- **2026-08-11** `b06902b6595a` — 1 warning
  - added the new `CARDHOLDER_KYC_NOT_APPROVED` enum value to the `code` response property for the response status `400`

[Full history](https://skmtc.dev/stainless-api/apis/grid-api/changes/cards/get.md)

---

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