API Documentation

Volia provides a RESTful API for voucher generation, validation, and redemption. All API endpoints are available at the base URL of your Volia instance.

Base URL

Authentication Methods

Volia supports two authentication methods:

• Session Cookie — Used by the web application after login. Automatically handled by the browser.
• API Key — For server-to-server integration. Include via Authorization: Bearer <key> header.

Generate API keys from the API Keys page in your dashboard. Keys are prefixed with vh_live_ and are shown only once upon creation.

Using API Keys

Vouchers are split into two categories:

Note: Percentage vouchers require maxRedeemValue. Benefit vouchers require description instead.

Each voucher follows a status lifecycle:

Voucher codes are generated from a format pattern. Each X in the pattern is replaced with a random alphanumeric character (A-Z, 0-9).

Pattern Rules

• Maximum 50 characters
• Allowed characters: A-Z, 0-9, X, -
• If count > 1, pattern must contain X
• No consecutive, leading, or trailing dashes

Examples

The prefix is automatically derived from the pattern — everything before the first X, with trailing dashes removed. If no prefix is found, defaults to GEN.

Create one or more vouchers for a customer. Requires authentication (session or API key).

{
  "format": "SUMMER-XXXX",
  "type": "fixed",
  "value": 20,
  "campaignId": "uuid-here",
  "count": 5,
  "maxUses": 1,
  "expiresAt": "2026-12-31",
  "maxRedeemValue": 50,
  "group": "Batch-1",
  "minPurchase": 100
}

[
  {
    "id": "uuid",
    "code": "SUMMER-A3K9",
    "prefix": "SUMMER",
    "type": "fixed",
    "value": 20,
    "status": "active",
    "redeemCount": 0,
    "maxUses": 1,
    "maxRedeemValue": null,
    "expiresAt": "2026-12-31T00:00:00.000Z",
    "group": "Batch-1",
    "customerId": "user-uuid",
    "createdAt": "2026-07-06T12:00:00.000Z"
  }
]

Check whether a voucher code is valid without redeeming it. Requires authentication — call this endpoint from your backend with a valid API key.

{
  "code": "SUMMER-A3K9",
  "cartTotal": 150  // optional — used to compute percentage discount
}

{
  "valid": true,
  "voucher": {
    "code": "SUMMER-A3K9",
    "category": "discount",
    "description": null,
    "type": "fixed",
    "value": 20,
    "maxRedeemValue": 50,
    "minPurchase": 100,
    "computedDiscount": 20
  }
}

{
  "valid": false,
  "error": "Voucher has expired"
}

There are two ways to redeem a voucher:

1. Redeem by Code

Requires authentication — call this endpoint from your backend with a valid API key.

{
  "code": "SUMMER-A3K9",
  "customerEmail": "user@example.com",
  "cartTotal": 150
}

{
  "success": true,
  "voucher": {
    "code": "SUMMER-A3K9",
    "category": "discount",
    "description": null,
    "type": "fixed",
    "value": 20,
    "maxRedeemValue": 50,
    "computedDiscount": 20
  }
}

{
  "success": true,
  "voucher": {
    "code": "SUMMER-PCT",
    "category": "discount",
    "type": "percentage",
    "value": 15,
    "maxRedeemValue": 50,
    "computedDiscount": null,
    "warning": "cartTotal is required to compute percentage discount"
  }
}

{
  "statusCode": 400,
  "message": "This voucher has expired"
}

2. Authenticated Redeem (by ID)

Requires authentication. Redeem a voucher by its ID. Only the voucher owner can redeem via this method.

Campaigns organize vouchers and manage budgets. Each campaign has a fund (total budget) and usedFund (budget consumed by created vouchers).

Fund Mechanics

When you create vouchers in a campaign, the fund is reserved at creation time:

perVoucher = (type === 'fixed') ? value : maxRedeemValue
totalReserve = perVoucher × maxUses × count
remaining = campaign.fund - campaign.usedFund

// If totalReserve > remaining → Error: Insufficient campaign fund
// Otherwise → campaign.usedFund += totalReserve

Fund is not released on redemption. To free up budget, delete a voucher group (which recalculates usedFund based on remaining active vouchers).

Campaign API

Campaign Statuses

Campaign status is computed dynamically:

• scheduled — startsAt > now
• active — Within the date range or no dates set
• ended — endsAt < now

Voucher Groups

Within a campaign, vouchers can be organized into groups — logical labels set at creation time.

• Group is an optional free-text field
• Vouchers without a group belong to "Ungrouped"
• Deleting a group deletes all vouchers in it and recalculates the campaign fund

API errors follow a consistent format:

{
  "statusCode": 400,
  "message": "Description of what went wrong"
}

Common HTTP Status Codes

Common Voucher Errors