generateVCShareLinks

Generates share links. Requires CREATE_SHARE_LINK scope. Creates quantity share requests and returns one single load open loop card link per request. Each link maps to one share request (PENDING) and is funded from userCashBalanceId at claim time, not at generation.

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
    recipientRegistrationResults {
      index
      status
      userId
      error
    }
  }
}

Arguments

GenerateVCShareLinksInput!

required

See GenerateVCShareLinksInput for the full field list. Key fields:

Field	Type	Required	Description
`cardLimit`	`Int!`	Yes	Spend limit (and load amount) for each card, in whole currency units. Must be a whole number ≥ the program minimum.
`offerId`	`String!`	Yes	UUID v4 of the merchant offer the card is tied to. The offer must be active and its merchant must be shareable.
`quantity`	`Int!`	Yes	Number of links to generate. One distinct hosted URL is created per unit.
`shareMethod`	`ShareMethodType!`	Yes	How recipients are identified and links are delivered: `GENERATE_URL`, `EMAIL`, `PHONE_NUMBER`, `EXISTING_USER`, or `REGISTER_USER`.
`userCashBalanceId`	`UUID`	Yes*	The spend account used to fund the cards. Marked optional in the schema but required in practice — omitting it fails validation.
`daysUntilExpiration`	`Int`	No	Days until the link expires. Minimum 1. Defaults to the program default (30 days) if omitted. This date also becomes the card’s lock/freeze date.
`recipientListEmail`	`[String]`	Conditional	Required and non-empty when `shareMethod = EMAIL`. Length must equal `quantity`. Must be empty otherwise.
`recipientListPhone`	`[String]`	Conditional	Required and non-empty when `shareMethod = PHONE_NUMBER`. Length must equal `quantity`. Must be empty otherwise.
`recipientUserIds`	`[UUID]`	Conditional	Known Fluz user IDs to bind as recipients when `shareMethod = EXISTING_USER`. Length must equal `quantity`. Mutually exclusive with `recipientRegistrations`.
`recipientRegistrations`	`[ShareLinkRecipientRegistrationInput]`	Conditional	Inline pre-register payloads when `shareMethod = REGISTER_USER` — Fluz creates or reuses a placeholder user (no seat) per entry before generating links. Length must equal `quantity`. Mutually exclusive with `recipientUserIds`.
`virtualCardId`	`UUID`	No	Existing open loop card to bind to the hosted link. When provided, claim grants access to that card instead of issuing a new one.
`usePrepaymentBalance`	`Boolean`	No	Whether to use your Prepayment Balance as an additional funding source if `userCashBalanceId` doesn’t cover the full amount at claim time. Default `false`.
`useRewardsBalance`	`Boolean`	No	Whether to use your Fluz Rewards Balance as an additional funding source if `userCashBalanceId` doesn’t cover the full amount at claim time. Default `false`.

Recipient identification & delivery (`shareMethod`)

Value	Behavior	Recipient field	Card created
`GENERATE_URL`	Fluz returns the hosted URLs in the response. You distribute them yourself.	Both lists must be empty/omitted.	At claim
`EMAIL`	Fluz emails a link to each recipient.	`recipientListEmail` required; length must equal `quantity`.	At claim
`PHONE_NUMBER`	Fluz texts a link to each recipient.	`recipientListPhone` required; length must equal `quantity`.	At claim
`EXISTING_USER`	Link is bound to a known Fluz user from the start; only that user can claim it.	`recipientUserIds` required; length must equal `quantity`.	Immediately, at generation time
`REGISTER_USER`	Fluz creates or reuses a placeholder user per entry, then binds the link to that user, same as `EXISTING_USER`.	`recipientRegistrations` required; length must equal `quantity`.	Immediately, at generation time

Example

Generate URLs

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 3,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Returns

ShareRequest — ShareRequest represents a response from creating a share link.

Field	Type	Description
`shareLinks`	`[String]`	The hosted URLs generated by this request, one per `quantity`, each of the form `https://fluz.app/virtual-prepaid-card/{share_request_id}`.
`recipientRegistrationResults`	`[ShareLinkRecipientRegistrationResult]`	Per-recipient registration outcomes, populated only when `shareMethod` is `REGISTER_USER`.

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1",
        "https://fluz.app/virtual-prepaid-card/9b2d...77",
        "https://fluz.app/virtual-prepaid-card/0c41...e3"
      ]
    }
  }
}

Errors

Cause	Result
Missing/invalid Bearer token or missing `CREATE_SHARE_LINK` scope	Request rejected (unauthorized).
Recipient field (`recipientListEmail`, `recipientListPhone`, `recipientUserIds`, or `recipientRegistrations`) length ≠ `quantity`	Validation error; no records created.
`recipientUserIds` references a non-existent Fluz user	Validation error; no records created.
Inactive offer, non-shareable merchant, or invalid `offerId`	Validation error; no records created.
Missing/invalid `userCashBalanceId`	Validation error; no records created.

See Send Open Loop Cards for the full guide, including delivery-method walkthroughs and expiration/freeze behavior.

API reference

Conventions

generateVCShareLinks

Arguments

Recipient identification & delivery (`shareMethod`)

Example

Returns

Errors

​Arguments

​Recipient identification & delivery (shareMethod)

​Example

​Returns

​Errors

Arguments

Recipient identification & delivery (`shareMethod`)

Example

Returns

Errors