> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Voucher

> Create a new voucher or generate vouchers in bulk

<ParamField header="Authorization" type="string" required>
  Bearer token with `marketing:write` scope
</ParamField>

## Single voucher creation

<ParamField body="code" type="string">
  Voucher code (auto-generated if not provided, always uppercased)
</ParamField>

<ParamField body="type" type="string" default="gift_card">
  Voucher type: `gift_card`, `store_credit`, `loyalty_reward`, `compensation`, `referral`
</ParamField>

<ParamField body="status" type="string" default="active">
  Initial status: `pending`, `active`
</ParamField>

<ParamField body="customer_id" type="string">
  Customer ID to assign the voucher to
</ParamField>

<ParamField body="initial_balance_minor" type="integer" required>
  Initial balance in minor units (cents)
</ParamField>

<ParamField body="currency" type="string" default="USD">
  3-letter ISO currency code
</ParamField>

<ParamField body="expires_at" type="string">
  ISO 8601 datetime when voucher expires
</ParamField>

<ParamField body="is_transferable" type="boolean" default="true">
  Whether voucher can be used by different customers
</ParamField>

<ParamField body="source_type" type="string">
  Source of the voucher (e.g., "purchase", "refund", "reward")
</ParamField>

<ParamField body="source_id" type="string">
  ID of the source entity (e.g., order ID, booking ID)
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata
</ParamField>

## Bulk voucher creation

Set `bulk: true` to generate multiple vouchers at once.

<ParamField body="bulk" type="boolean" required>
  Set to `true` for bulk creation
</ParamField>

<ParamField body="count" type="integer" required>
  Number of vouchers to generate (max 1000)
</ParamField>

<ParamField body="prefix" type="string" default="GC">
  Prefix for generated codes (max 10 characters)
</ParamField>

<ParamField body="type" type="string" default="gift_card">
  Voucher type for all vouchers
</ParamField>

<ParamField body="initial_balance_minor" type="integer" required>
  Initial balance for all vouchers
</ParamField>

<ParamField body="currency" type="string" default="USD">
  Currency for all vouchers
</ParamField>

<ParamField body="expires_at" type="string">
  Expiry date for all vouchers
</ParamField>

<ParamField body="is_transferable" type="boolean" default="true">
  Transferability for all vouchers
</ParamField>

## Response

Returns the created voucher(s).

```bash Request (Single) theme={null}
curl -X POST "https://api.voyantcloud.com/v1/vouchers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "gift_card",
    "initial_balance_minor": 10000,
    "currency": "EUR",
    "expires_at": "2025-12-31T23:59:59Z"
  }'
```

```json Response (Single) theme={null}
{
  "data": {
    "id": "voucher_abc123",
    "workspaceId": "ws_xyz",
    "code": "GC1A2B3C4D",
    "type": "gift_card",
    "status": "active",
    "customerId": null,
    "initialBalanceMinor": 10000,
    "currentBalanceMinor": 10000,
    "currency": "EUR",
    "expiresAt": "2025-12-31T23:59:59Z",
    "isTransferable": true,
    "createdAt": "2024-07-20T10:00:00Z"
  }
}
```

```bash Request (Bulk) theme={null}
curl -X POST "https://api.voyantcloud.com/v1/vouchers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bulk": true,
    "count": 50,
    "prefix": "GIFT",
    "type": "gift_card",
    "initial_balance_minor": 5000,
    "currency": "EUR",
    "expires_at": "2025-12-31T23:59:59Z"
  }'
```

```json Response (Bulk) theme={null}
{
  "data": {
    "count": 50,
    "vouchers": [
      {
        "id": "voucher_001",
        "code": "GIFT1A2B3C4D",
        "type": "gift_card",
        "status": "active",
        "initialBalanceMinor": 5000,
        "currentBalanceMinor": 5000,
        "currency": "EUR"
      }
    ]
  }
}
```

## Errors

| Status | Error                       | Description                             |
| ------ | --------------------------- | --------------------------------------- |
| 409    | Voucher code already exists | A voucher with this code already exists |