> ## 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.

# Create Bulk Order

The `createVirtualCardBulkOrder` mutation allows you to create multiple virtual cards in a single request.

<Info>
  **Prerequisites:** a user access token with the `CREATE_VIRTUALCARD` scope, and a `CreateVirtualCardBulkOrderInput` object. To find an `offerId`, see [Get Virtual Card Offers](/features/get-card-offers).
</Info>

<Note>
  Bulk orders are processed asynchronously. This mutation returns an `orderId` and an initial `orderStatus` of `PENDING` — poll [Get Bulk Order Status](/features/get-bulk-order-status) to track completion.
</Note>

## Sandbox test offers

| Offer ID                               | Program Name                                   | Reward Value |
| :------------------------------------- | :--------------------------------------------- | :----------- |
| `ed669305-5e43-40a0-9a25-7a15ed174628` | Virtual Card                                   | 1.5%         |
| `b23630f6-8d91-43df-84aa-a541e7691197` | Virtual Card - Mastercard Prepaid              | 1.5%         |
| `592c394e-26cc-44ac-a145-a5f81301fe77` | Brand Locked Virtual Card - Mastercard Prepaid | 1.5%         |

## Important considerations

* **Offer ID:** The `offerId` is applied to all cards created within the bulk order.
* **Funding Source:** You can fund your virtual cards using either your Fluz balance or a linked bank account.
  * If you select a bank account as the `primaryFundingSource`, you must provide the `bankAccountId`.
* **Spend Limits:** The `spendLimit` you set must adhere to the program's defined spend limits for the chosen `spendLimitDuration`. An error will occur if the limit is exceeded.
* **Quantity:** Each item in the `orderItems` array includes a `quantity`, allowing you to create multiple cards with the same configuration efficiently.

## Arguments

* `input` (`CreateVirtualCardBulkOrderInput!`): The input object containing details for the new virtual card bulk order.

## CreateVirtualCardBulkOrderInput fields

| Field        | Type                                      | Description                                                                                                          | Required |
| :----------- | :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | :------- |
| `offerId`    | `UUID!`                                   | The Offer ID to be used for all cards in this bulk order. Use getVirtualCardOffers to fetch a list of active offers. | Yes      |
| `orderItems` | `[CreateVirtualCardBulkOrderItemInput!]!` | An array of objects, each defining a set of virtual cards to be created.                                             | Yes      |

### CreateVirtualCardBulkOrderItemInput fields

| Field                  | Type                            | Description                                                                                        | Required |
| :--------------------- | :------------------------------ | :------------------------------------------------------------------------------------------------- | :------- |
| `quantity`             | `Int!`                          | The number of virtual cards to create with this specific configuration.                            | Yes      |
| `spendLimit`           | `Float!`                        | The maximum amount you can charge to each card. You are only charged for the amount actually used. | Yes      |
| `spendLimitDuration`   | `VirtualCardSpendLimitDuration` | Card limit duration type. Default is `LIFETIME`.                                                   | No       |
| `lockDate`             | `String`                        | The date when the card will be locked. The default is 47 months from creation. Format: yyyy-mm-dd  | No       |
| `lockCardNextUse`      | `Boolean`                       | Setting to lock the card after its next use. The default is `false`.                               | No       |
| `cardNickname`         | `String`                        | The card's nickname.                                                                               | No       |
| `primaryFundingSource` | `VirtualCardFundingSource`      | Primary Funding Source for Virtual Card. Default is `FLUZ_BALANCE`.                                | No       |
| `bankAccountId`        | `UUID`                          | The unique identifier for the bank account. Required if `primaryFundingSource` is `BANK_ACCOUNT`.  | No       |

## cURL example

```bash theme={null}
curl -X POST \
  https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  -d '{
    "query": "mutation CreateVirtualCardBulkOrder { createVirtualCardBulkOrder( input: { offerId: \"592c394e-26cc-44ac-a145-a5f81301fe77\", orderItems: [ { quantity: 3, spendLimit: 100, spendLimitDuration: DAILY, lockCardNextUse: true, cardNickname: \"Test nickname\", primaryFundingSource: FLUZ_BALANCE }, { quantity: 1, spendLimit: 200, spendLimitDuration: WEEKLY, lockCardNextUse: false, lockDate: \"2030-10-10\", cardNickname: \"Test nickname 2\", primaryFundingSource: BANK_ACCOUNT, bankAccountId: \"7f60cb5d-683f-4181-9194-408ea92d6248\" } ] } ) { orderId orderStatus } }"
  }'
```

## Sample mutation

```graphql theme={null}
mutation CreateVirtualCardBulkOrder {
    createVirtualCardBulkOrder(
        input: {
            offerId: "592c394e-26cc-44ac-a145-a5f81301fe77"
            orderItems: [
                {
                    quantity: 3
                    spendLimit: 100
                    spendLimitDuration: DAILY
                    lockCardNextUse: true
                    cardNickname: "Test nickname"
                    primaryFundingSource: FLUZ_BALANCE
                }
                {
                    quantity: 1
                    spendLimit: 200
                    spendLimitDuration: WEEKLY
                    lockCardNextUse: false
                    lockDate: "2030-10-10"
                    cardNickname: "Test nickname 2"
                    primaryFundingSource: BANK_ACCOUNT
                    bankAccountId: "7f60cb5d-683f-4181-9194-408ea92d6248"
                }
            ]
        }
    ) {
        orderId
        orderStatus
    }
}
```

## Sample response

```json theme={null}
{
  "data": {
    "createVirtualCardBulkOrder": {
      "orderId": "MTFkYjIxNTYtNTEwOS00ODNmLTkwMTYtYjA5N2E2NTEyMjU5fDIzMjIxODRhLTEzMjgtNDkwYy05Mzc1LTZlOWM4MWIwMjkzZA==",
      "orderStatus": "PENDING",
    }
  }
}
```

## Response fields

| Field         | Type                          | Description                                                                                                        |
| ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `orderId`     | `UUID`                        | The unique identifier for the bulk creation order. Pass this to `getVirtualCardBulkOrderStatus` to track progress. |
| `orderStatus` | `VirtualCardBulkOrderStatus!` | The status of the bulk order (e.g., `COMPLETED`, `PENDING`, `FAILED`).                                             |

## Next steps

<Card title="Get bulk order status" icon="list-checks" horizontal href="/features/get-bulk-order-status">
  Poll the `orderId` to track processing and retrieve the cards as they're issued.
</Card>