Generate a card series

POST /api/v1/card-batches 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.

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.

At a glance

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

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.

Errors

Code	When it is returned
`ERR_VALIDATION`400	bad expiration, an unworkable spec, or a request_id that is missing, too long or reserved
`ERR_VALIDATION`402	the generating manager's wallet cannot cover the generation charge
`ERR_FORBIDDEN`403	minting refill cards without the refill-generation permission, which is separate from the generate permission the route checks

Request

curl -X POST "$BASE/api/v1/card-batches" \
  -H "Authorization: Bearer $XR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "prepaid",
  "quantity": 500,
  "face_value": 150.00,
  "expiration": "2027-01-01",
  "plan_profile_id": 7,
  "code_length": 10,
  "code_charset": "alnum_no_ambig",
  "request_id": "5f2a7c18-2b0d-4a61-9f3e-7a4c8d2e1b09"
}'

Response 202 Accepted

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

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