Create Bulk Order

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

Prerequisites: a user access token with the CREATE_VIRTUALCARD scope, and a CreateVirtualCardBulkOrderInput object. To find an offerId, see Get Virtual Card Offers.

Bulk orders are processed asynchronously. This mutation returns an orderId and an initial orderStatus of PENDING — poll Get Bulk Order Status to track completion.

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

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

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

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

Get bulk order status

Poll the orderId to track processing and retrieve the cards as they’re issued.

​Sandbox test offers

​Important considerations

​Arguments

​CreateVirtualCardBulkOrderInput fields

​CreateVirtualCardBulkOrderItemInput fields

​cURL example

​Sample mutation

​Sample response

​Response fields

​Next steps

Get bulk order status

Sandbox test offers

Important considerations

Arguments

CreateVirtualCardBulkOrderInput fields

CreateVirtualCardBulkOrderItemInput fields

cURL example

Sample mutation

Sample response

Response fields

Next steps