Browse the docs

List cards

GET /v2/api-gateway/cards

Lists cards newest first. Filtering by an unknown card_holder_id / end_customer_id returns 200 with an empty list, not 404.

Request

Authentication: your API key in the x-api-key header.

Query parameters

Field	Type	Description
`page`	integer	Page number, starting at `1`. Default `1`.
`current_page`	integer	Page number, starting at `1` — the canonical spelling, accepted on every paginated endpoint and matching `pagination.current_page` in the response. `page` means the same thing and keeps working; if both are sent, `current_page` wins.
`limit`	integer	Cards per page. Minimum `1`, maximum `49`. Default `10`.
`per_page`	integer	Cards per page. Minimum `1`, maximum `49`. The canonical spelling, accepted on every paginated endpoint and matching `pagination.per_page` in the response. `limit` means the same thing and keeps working; if both are sent, `per_page` wins. A value above `49` is not rejected: it is reduced to `49`, and `pagination.per_page` in the response reports the size actually applied. The route's own spelling keeps its existing behaviour for an out-of-range value.
`external_id`	string	Only cards linked to the cardholder with this `external_id` (your identifier), searched across your top-level organization and its child organizations. A Moon cardholder id is also accepted here for backwards compatibility. An unknown value yields an empty list. Combined with `card_holder_id`, both must match. Canonical name for the value this route also accepts as `end_customer_id`. Send one or the other; sending both with different values is rejected.
`end_customer_id`	string	Deprecated alias of `external_id`, kept working for existing integrations. Send one or the other; sending both with different values is rejected.
`card_holder_id`	string, uuid	Only cards linked to the cardholder with this Moon cardholder id (the `id` returned by the cardholder endpoints). An unknown value yields an empty list.
`include_inactive_cards`	boolean	By default deleted, expired, terminated and marked-as-used cards are excluded. Set to `true` to include them. Ignored when `inactive_only=true`.
`inactive_only`	boolean	Set to `true` to return only inactive cards (deleted, expired, terminated or marked as used). Frozen cards count as active. Default `false`.

Example request

cURL

curl --request GET \
     --url 'https://api.themooncard.com/v2/api-gateway/cards' \
     --header 'x-api-key: YOUR_API_KEY'

Responses

200 Success

Field	Type	Description
`cards` required	array of object, nullable
`cards[].id` required	string	Card id.
`cards[].balance` required	string, nullable	Current balance, "0.00" style string, or null.
`cards[].true_balance` required	string, nullable	Balance including pending holds, or null.
`cards[].expiration` required	string, date-time, nullable	Expiration as an ISO-8601 timestamp, or null when unknown.
`cards[].display_expiration` required	string	Expiration formatted for display, e.g. "12/29".
`cards[].available_balance` required	string, nullable	Spendable balance, or null.
`cards[].terminated` required	integer	1 when the card is terminated, otherwise 0.One of: `0`, `1`
`cards[].card_product_id` required	string	Card product this card was issued from.
`cards[].pan` required	string	Full card number.
`cards[].cvv` required	string, nullable	Card verification value, or null when not available.
`cards[].support_token` required	string	Token to reference this card in support requests.
`cards[].frozen` required	integer	1 when the card is frozen, otherwise 0.One of: `0`, `1`
`cards[].activated` required	integer	1 when the card is activated, otherwise 0.One of: `0`, `1`
`cards[].metadata` required	object	The key-value data you stored on this card, returned exactly as you sent it. An empty object when you never set any — it is never null.
`cards[].card_type` required	string, nullable	Card type, e.g. "virtual" or "physical"; null when unknown.
`pagination` required	object
`pagination.total` required	integer	Total number of items across all pages.
`pagination.last_page` required	integer	Number of the last page (0 when there are no items).
`pagination.prev_page` required	integer, nullable	Previous page number, or null on the first page.
`pagination.next_page` required	integer, nullable	Next page number, or null on the last page.
`pagination.per_page` required	integer	Page size that was applied.
`pagination.current_page` required	integer	1-based current page.
`pagination.from` required	integer	1-based index of the first item on this page (0 when empty).
`pagination.to` required	integer	1-based index of the last item on this page (0 when empty).

JSON

{
  "cards": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "balance": "25.50",
      "true_balance": "25.50",
      "expiration": "2029-12-31T23:59:59Z",
      "display_expiration": "12/29",
      "available_balance": "25.50",
      "terminated": 0,
      "card_product_id": "a8358b18-be77-41b7-af4d-f4e9760cba86",
      "pan": "4111111111111111",
      "cvv": "123",
      "support_token": "ST-8QK2-4M7D",
      "frozen": 0,
      "activated": 1,
      "metadata": {
        "order_id": "ORD-10294"
      },
      "card_type": "VIRTUAL"
    }
  ],
  "pagination": {
    "total": 1,
    "last_page": 1,
    "prev_page": null,
    "next_page": null,
    "per_page": 10,
    "current_page": 1,
    "from": 1,
    "to": 1
  }
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated June 5, 2026