### List card series

`GET /api/v1/card-batches`

One page of card series with their stock breakdown. A non-admin caller sees only series created within their own manager subtree.

- Authentication: manager session (JWT) or API token
- Permission: `prm_cards_list` (View card batches & cards)
- Risk: read

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filter[status]` | query | string | no | Generation status — generating, ready, failed. |
| `filter[card_mode]` | query | string | no | The series mode. |
| `filter[owner_manager_id]` | query | integer | no | The reseller holding the series after any transfer. |
| `filter[suspended]` | query | boolean | no | Series whose unused cards have been revoked. |
| `filter[template_id]` | query | integer | no | Series cut from one saved card template. |
| `q` | query | string | no | Plan name, distribution note, or series id. |

#### Response — 200 OK

```json
{
  "data": [
    {
      "id": 208,
      "plan_id": 7,
      "plan_name": "Home 20M",
      "card_mode": "voucher_account",
      "quantity": 500,
      "face_value": 150.00,
      "code_length": 10,
      "code_charset": "alnum_no_ambig",
      "status": "ready",
      "suspended": false,
      "processed": 500,
      "used": 312,
      "available": 171,
      "sold_online": 9,
      "sold_counter": 8,
      "stuck_sale": 0,
      "expiration": "2027-01-01 00:00:00",
      "printed_at": "2026-08-30 12:01:44",
      "print_count": 1,
      "pdf_ready": true,
      "has_cards": true,
      "owner_manager_id": 41,
      "sell_online": false,
      "auto_activate": false,
      "created_by": 41
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 24, "has_next": false }
}
```

#### Note

Never derive stock by subtraction. used excludes both unused and revoked, so quantity minus used is not the unused count, and quantity itself grows when the point of sale mints into the series. available is the sellable stock. stuck_sale is a warning, not a bucket: it counts cards held by a till sale that never completed, and there is no reaper for it.