> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Issue 100 Cards at Once
> Create a bulk virtual card order, poll it to completion, and handle partial failures — the programmatic issuance pattern at scale.
This Quickstart issues 100 virtual cards in one request. You'll place an asynchronous bulk order, poll its status as cards are created, and retrieve the full card details — the same pattern whether you're issuing 10 cards or 10,000.
**Prerequisites**
* A **Fluz account with a staging application** — Steps 1–2 of any quickstart, or see [Prepare your accounts](/get-started/prepare-accounts) and [API credentials](/get-started/api-credentials).
* A token with **`CREATE_VIRTUALCARD`** to place the order and **`REVEAL_VIRTUALCARD`** to poll its status. Without the second, step 2 fails with `AUTH-0031`.
* Enough available balance to cover the order — 100 cards × the spend limit you set.
* A billing address on the account, or a `billingAddress` on each order item. Without one, card creation fails and the order completes with `failedCardCreations` equal to the order size.
## The full flow
A bulk order is asynchronous. The mutation returns immediately with an `orderId` and a `PENDING` status; the cards are created in the background. **The order and the cards succeed independently** — an order can reach `COMPLETED` with some cards failed, so the order status alone never tells you whether you got what you asked for.
```mermaid theme={null}
stateDiagram-v2
[*] --> PENDING: createVirtualCardBulkOrder
PENDING --> IN_PROGRESS: cards being created
IN_PROGRESS --> COMPLETED: all cards attempted
IN_PROGRESS --> FAILED: order could not be processed
COMPLETED --> AllSucceeded: successfulCardCreations == totalCards
COMPLETED --> PartialFailure: failedCardCreations > 0
AllSucceeded --> [*]
PartialFailure --> Reissue: place a new order for the shortfall
Reissue --> [*]
FAILED --> [*]
```
Always reconcile `successfulCardCreations` and `failedCardCreations` against `totalCards` before treating an order as done. `orderStatus` has one more possible value not shown above — `CANCELED` — which, like `FAILED`, means the order will produce no more cards.
One `createVirtualCardBulkOrder` call creates all 100 cards. Each entry in `orderItems` is a card configuration with a `quantity` — here, 100 identical single-use disbursement cards.
Unlike most money-moving mutations, this one takes **no `idempotencyKey`** — the input accepts only `offerId` and `orderItems`. See [Idempotency](/concepts/idempotency) for where the key does apply.
```graphql Mutation theme={null}
mutation createVirtualCardBulkOrder($input: CreateVirtualCardBulkOrderInput!) {
createVirtualCardBulkOrder(input: $input) {
orderId
orderStatus
}
}
```
```json Variables theme={null}
{
"input": {
"offerId": "592c394e-26cc-44ac-a145-a5f81301fe77",
"orderItems": [
{
"quantity": 100,
"spendLimit": 25.00,
"lockCardNextUse": true,
"cardNickname": "July payout batch",
"primaryFundingSource": "FLUZ_BALANCE"
}
]
}
}
```
```json Response theme={null}
{
"data": {
"createVirtualCardBulkOrder": {
"orderId": "ZTBhYTg2YmQt...",
"orderStatus": "PENDING"
}
}
}
```
The `offerId` applies to **every** card in the order; mix configurations by adding more `orderItems` entries (e.g. 20 qty of \$25 single-use + 80 qty of \$100 monthly). `lockCardNextUse: true` makes each card self-destruct after its first charge — the standard disbursement pattern.
Bulk orders are **asynchronous** — the response is an `orderId` and `PENDING`, not cards. Save the `orderId`; it's your handle for everything that follows.
Track progress with `getVirtualCardBulkOrderStatus`. Cards populate incrementally while the order is `PENDING`:
```graphql Query theme={null}
query getVirtualCardBulkOrderStatus($input: GetVirtualCardBulkOrderStatusInput!) {
getVirtualCardBulkOrderStatus(input: $input) {
orderId
orderStatus
successfulCardCreations
failedCardCreations
totalCards
virtualCards {
virtualCardId
cardNumber
expiryMMYY
cvv
cardHolderName
}
}
}
```
```json Variables theme={null}
{ "input": { "orderId": "" } }
```
Poll with backoff until `orderStatus` is `COMPLETED` (or `FAILED`) — while pending, `successfulCardCreations` climbs toward `totalCards` and `virtualCards` fills in.
The response contains **full PANs, CVVs, and expiry dates in plaintext**. Treat it as sensitive cardholder data: TLS only, never log it, surface it only to authorized users.
A bulk order can partially succeed: `successfulCardCreations: 98, failedCardCreations: 2` on a completed order means 98 real, spendable cards and 2 that need retrying. Reconcile by comparing the counts to `totalCards`, then re-issue only the shortfall as a new order:
```json theme={null}
{
"input": {
"offerId": "592c394e-26cc-44ac-a145-a5f81301fe77",
"orderItems": [{ "quantity": 2, "spendLimit": 25.00, "lockCardNextUse": true }]
}
}
```
Persistent failures usually trace to program limits or funding — check [Virtual Card Error Codes](/features/virtual-card-error-codes) and your available balance.
## You're done 🎉
One hundred configured cards from one request, with a poll loop that's production-ready as-is. Next:
Monitor spend across the whole batch — up to 10 cards per query, or account-wide by date.
Distributing to people outside your org? Hosted claim links handle onboarding for you.
**Want to learn more?** Contact us at [support@fluz.app](mailto:support@fluz.app) to speak with our experts or request a demo.