Get virtual card issuance quota for a specific cardholder
GET/api/partner/cards/virtual-card-quota/:cardholderId
Pre-issuance check for the rolling virtual-card issuance cap on a specific cardholder.
The cardholder must be accessible to the calling partner:
- a direct individual onboarding owned by the partner, or
- a B2B cardholder hosted by one of the partner's B2B tenants.
Ownership-mismatch returns 404 Not Found with no further detail — identical whether the cardholder does not exist or belongs to another partner (no enumeration).
Read-only. A skipped or stale check can never let an extra card through — the authoritative block lives in the issuance path, and both the pre-check and the issuance call evaluate the same quota.
Scope: applies to non-B2B cardholders only (partner-owned
individuals and direct individuals). For B2B cardholders the
response returns applies: false with a neutral non-blocking
quota — issuance for B2B cardholders is governed by the
per-account concurrent cap (GET /cards/hold-limits/virtual),
not the rolling cap.
B2B cardholder behavior: if the quota does not apply to the
resolved cardholder, the response is always applies: false,
status: 'OK', used: 0, with remaining = limit and
nextSlotFreesAt: null. The quota object is still returned (never
omitted) so the partner client never has to branch on scope — any
code that reads data.status === 'LIMIT_EXCEEDED' simply never
fires for B2B cardholders, and any code that reads data.used
sees 0 instead of a misleading real count.
Status field guide:
status | Meaning |
|---|---|
OK | Under the warning band — proceed silently. |
WARNING_THRESHOLD_REACHED | Still allowed, but the cardholder is close to the cap. Tell them. |
LIMIT_EXCEEDED | Cap reached; issuance will be blocked with 429. |
Request
Responses
- 200
- 400
- 401
- 404
Rolling virtual-card issuance quota for the cardholder
Bad request — missing or invalid fields
Unauthorized — missing or invalid JWT
Not found