Create Voucher

Create a new voucher or generate vouchers in bulk

Authorization · string · required

Bearer token with marketing:write scope

Single voucher creation

code · string

Voucher code (auto-generated if not provided, always uppercased)

type · string · default: "gift_card"

Voucher type: gift_card, store_credit, loyalty_reward, compensation, referral

status · string · default: "active"

Initial status: pending, active

customer_id · string

Customer ID to assign the voucher to

initial_balance_minor · integer · required

Initial balance in minor units (cents)

currency · string · default: "USD"

3-letter ISO currency code

expires_at · string

ISO 8601 datetime when voucher expires

is_transferable · boolean · default: "true"

Whether voucher can be used by different customers

source_type · string

Source of the voucher (e.g., “purchase”, “refund”, “reward”)

source_id · string

ID of the source entity (e.g., order ID, booking ID)

metadata · object

Custom metadata

Bulk voucher creation

Set bulk: true to generate multiple vouchers at once.

bulk · boolean · required

Set to true for bulk creation

count · integer · required

Number of vouchers to generate (max 1000)

prefix · string · default: "GC"

Prefix for generated codes (max 10 characters)

type · string · default: "gift_card"

Voucher type for all vouchers

initial_balance_minor · integer · required

Initial balance for all vouchers

currency · string · default: "USD"

Currency for all vouchers

expires_at · string

Expiry date for all vouchers

is_transferable · boolean · default: "true"

Transferability for all vouchers

Response

Returns the created voucher(s).

Request (Single)

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"
  }'

Response (Single)

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

Request (Bulk)

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"
  }'

Response (Bulk)

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