Public reference

Card Batches

Every endpoint in this group. Open one for its parameters and a worked example.

28 Endpoints

View as Markdown

Card Batches

28

GET /api/v1/card-batches List card series prm_cards_list

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

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

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.

Parameters

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

Open the full reference

Response 200 OK

{
  "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 }
}

POST /api/v1/card-batches Generate a card series prm_cards_generate_user

Stages an asynchronous generation job and returns immediately. The cards and the printable artifact are produced in the background; poll the series until status is ready, then fetch the print job.

Authentication: Staff token or session
Requires permission: prm_cards_generate_user Generate user cards
Rate limit: t_mutate
Idempotency key: request_id

A fresh stage answers 202 Accepted; a replay of the same request_id answers 200 OK with the original batch_id and replay true. The status field says generating in both cases, because it describes the job, not the outcome of this call. Branch on the HTTP status or on replay, not on status.

Parameters

Parameter	Description
`type`required body · enum	refill or prepaid.
`quantity`required body · integer	How many cards to mint.
`face_value`required body · number	Value per card, major units.
`expiration`required body · string	yyyy-MM-dd HH:mm:ss or yyyy-MM-dd. Series-level card lifetime.
`plan_profile_id` body · integer	Required for prepaid, and for a refill card that auto-activates.
`code_length` body · integer	The redemption PIN length. A MINIMUM, not an exact value — a mint may exceed it when the tenant's live code pool needs more entropy.
`code_charset` body · enum	numeric, alpha, alnum or alnum_no_ambig.
`owner_manager_id` body · integer	The series owner. Defaults to the creator.
`request_id`required body · string	Idempotency key.

Open the full reference

Response 202 Accepted

{
  "data": {
    "batch_id": 209,
    "mode": "voucher_account",
    "status": "generating",
    "replay": false
  }
}

POST /api/v1/card-batches/bulk-delete Delete card batches prm_cards_delete

Authentication: Staff token or session
Requires permission: prm_cards_delete Delete card batches
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/card-batches/bulk-expiry Change card expiry prm_cards_change_expiry

Authentication: Staff token or session
Requires permission: prm_cards_change_expiry Change card expiry
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/card-batches/bulk-print-job Download / export cards prm_cards_download

Authentication: Staff token or session
Requires permission: prm_cards_download Download / export cards
Rate limit: t_heavy

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/card-batches/bulk-printed Download / export cards prm_cards_download

Authentication: Staff token or session
Requires permission: prm_cards_download Download / export cards
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/card-batches/bulk-release Suspend / release cards prm_cards_suspend_release

Authentication: Staff token or session
Requires permission: prm_cards_suspend_release Suspend / release cards
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/card-batches/bulk-suspend Suspend / release cards prm_cards_suspend_release

Authentication: Staff token or session
Requires permission: prm_cards_suspend_release Suspend / release cards
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/card-batches/code-length Generate user cards prm_cards_generate_user

Authentication: Staff token or session
Requires permission: prm_cards_generate_user Generate user cards

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

DELETE /api/v1/card-batches/{id} Delete a card series prm_cards_delete

Deletes the series and its cards. Refuses outright once any card in it has been redeemed, transferred or sold at the till, because those are financial records.

Authentication: Staff token or session
Requires permission: prm_cards_delete Delete card batches
Rate limit: t_mutate

Parameters

Parameter	Description
`id`required path · integer	Series id.

Open the full reference

GET /api/v1/card-batches/{id} Fetch one card series prm_cards_list

The series header, its generation spec and its stock breakdown.

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

Parameters

Parameter	Description
`id`required path · integer	Series id.

Open the full reference

PATCH /api/v1/card-batches/{id} Manage card designs prm_cards_designer

Authentication: Staff token or session
Requires permission: prm_cards_designer Manage card designs
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/card-batches/{id}/cards List the cards in a series 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.

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

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.

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.

Open the full reference

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 }
}

POST /api/v1/card-batches/{id}/expiry Change card expiry prm_cards_change_expiry

Authentication: Staff token or session
Requires permission: prm_cards_change_expiry Change card expiry
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/card-batches/{id}/pdf Download / export cards prm_cards_download

Authentication: Staff token or session
Requires permission: prm_cards_download Download / export cards
Rate limit: t_heavy

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

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

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

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

DELETE /api/v1/card-batches/{id}/pricing/{resellerId} Manage card designs prm_cards_designer

Authentication: Staff token or session
Requires permission: prm_cards_designer Manage card designs
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

PUT /api/v1/card-batches/{id}/pricing/{resellerId} Manage card designs prm_cards_designer

Authentication: Staff token or session
Requires permission: prm_cards_designer Manage card designs
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/card-batches/{id}/print-job Fetch a series' print job prm_cards_download

The data a client needs to render the printable sheet in the browser. Rendering happens client-side; the server ships no PDF engine.

Authentication: Staff token or session
Requires permission: prm_cards_download Download / export cards

Parameters

Parameter	Description
`id`required path · integer	Series id.

Open the full reference

POST /api/v1/card-batches/{id}/printed Mark a series printed prm_cards_download

Records that the sheet was rendered, stamping printed_at and incrementing print_count.

Authentication: Staff token or session
Requires permission: prm_cards_download Download / export cards
Rate limit: t_mutate

Print tracking is observational only and deliberately does NOT move the series status. Nothing may set status to 'printed': the till refuses to mint into any series whose status is not 'ready', so auto-stamping would silently close every printed series to counter top-ups.

Parameters

Parameter	Description
`id`required path · integer	Series id.

Open the full reference

POST /api/v1/card-batches/{id}/regenerate Generate user cards prm_cards_generate_user

Authentication: Staff token or session
Requires permission: prm_cards_generate_user Generate user cards
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/card-batches/{id}/release Release a suspended card series prm_cards_suspend_release

Puts the revoked-but-unused cards of a suspended series back into stock.

Authentication: Staff token or session
Requires permission: prm_cards_suspend_release Suspend / release cards
Rate limit: t_mutate

Parameters

Parameter	Description
`id`required path · integer	Series id.

Open the full reference

POST /api/v1/card-batches/{id}/suspend Suspend a card series prm_cards_suspend_release

Revokes every still-unused card in the series. Cards already in flight are left alive. Re-running it is a harmless no-op.

Authentication: Staff token or session
Requires permission: prm_cards_suspend_release Suspend / release cards
Rate limit: t_mutate

Parameters

Parameter	Description
`id`required path · integer	Series id.

Open the full reference

Response 200 OK

{
  "data": { "message_key": "card_batch_suspended" }
}

POST /api/v1/card-batches/{id}/transfer-count Transfer N cards from a series prm_cards_change_owner

Like transfer-whole, but moves a count of cards off the top of the available stock rather than the entire series.

Authentication: Staff token or session
Requires permission: prm_cards_change_owner Transfer / change card owner
Rate limit: t_mutate
Idempotency key: request_id

Parameters

Parameter	Description
`id`required path · integer	Series id.
`count`required body · integer	How many cards to move.
`from_manager_id`required body · integer	The current holder.
`to_manager_id`required body · integer	The receiving reseller.
`unit_price`required body · number	Price per card. Required, never defaulted to zero.
`request_id`required body · string	Idempotency key.

Open the full reference

POST /api/v1/card-batches/{id}/transfer-range Transfer a card id range prm_cards_change_owner

Moves a contiguous range of card ids from the series, for the case where the physical cards handed over are a known block.

Authentication: Staff token or session
Requires permission: prm_cards_change_owner Transfer / change card owner
Rate limit: t_mutate
Idempotency key: request_id

Parameters

Parameter	Description
`id`required path · integer	Series id.
`card_id_range`required body · object	The inclusive id range to move.
`unit_price`required body · number	Price per card. Required.
`request_id`required body · string	Idempotency key.

Open the full reference

POST /api/v1/card-batches/{id}/transfer-whole Transfer a whole series to another reseller prm_cards_change_owner

Moves every card in the series from one manager to another at an agreed unit price, posting the matching ledger entries on both sides.

Authentication: Staff token or session
Requires permission: prm_cards_change_owner Transfer / change card owner
Rate limit: t_mutate
Idempotency key: request_id

unit_price is a required tri-state and omitting it is refused rather than read as zero. A bare 0 from a client that simply left the field out would mean "give the stock away", which is exactly the defect this check exists to stop. A negative price inverts the transfer.

Parameters

Parameter	Description
`id`required path · integer	Series id.
`from_manager_id`required body · integer	The current holder.
`to_manager_id`required body · integer	The receiving reseller.
`unit_price`required body · number	Price per card, major units. Must be sent explicitly — omitting it is an error, not a zero.
`request_id`required body · string	Idempotency key.

Open the full reference

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

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

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

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

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

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

Written to be read by machines too

The reference is public and needs no account, so a tool that has never seen X-Radius can reach a correct first call on its own.

/llms.txt: An index of every page, with one-line summaries.
/llms-full.txt: The whole reference as one Markdown file, with no navigation to crawl.
/openapi.json: OpenAPI 3.1, generated from the router that serves this instance.
/skill.md: A ready-made skill file for an assistant: authentication, the response envelope and the error codes in one page.
<page-url>.md: Append .md to any reference URL for the same page as Markdown.
Accept: text/markdown: Send this header on the ordinary URL and the answer comes back as Markdown instead.

Hand this to your assistant

Read https://x-radius.com/llms.txt, then fetch the endpoint you need as Markdown by appending .md to its URL.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us