List the cards in a series

GET /api/v1/card-batches/{id}/cards prm_cards_list

One row per card, carrying the plaintext code and, for prepaid series, the login username and password. Behind both the card-list permission and the per-series subtree gate for that reason.

state and effective_state are different questions and you almost always want the second. Nothing ever writes state 'expired', so a voucher past its expiry still reads as 'unused' in state and shows as available stock; effective_state applies the expiry at read time. Meanwhile disposition answers who holds the card — a voucher sold at the till but not yet redeemed is still 'unused' and is not stock you can sell again.

At a glance

Authentication: Staff token or session
Requires permission: prm_cards_list View card batches & cards

Parameters

Parameter	Description
`id`required path · integer	Series id.
`filter[state]` query · string	Stored state — unused, consumed, active, exhausted, revoked.
`filter[disposition]` query · string	Who holds the card, which is orthogonal to state.
`filter[has_customer]` query · boolean	Cards linked to a subscriber.

Request

curl -X GET "$BASE/api/v1/card-batches/{id}/cards" \
  -H "Authorization: Bearer $XR_TOKEN"

Response 200 OK

{
  "data": [
    {
      "id": 90211,
      "serial": "000312",
      "code": "K7P4M2Q9XD",
      "username": "v90211",
      "password": "8sk3ndq1",
      "state": "unused",
      "effective_state": "unused",
      "disposition": "available",
      "redemptions_left": 1,
      "expires_at": "2027-01-01 00:00:00",
      "used_bytes": 0,
      "used_seconds": 0
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 500, "has_next": true }
}

BASE is your tenant host: the same address you sign in on.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us