📌 Purpose

Stored value vouchers are a powerful tool to reward customers with monetary value they can use on future purchases. This recipe walks you through creating a programme that can issue one-time use stored value voucher that carries a fixed balance, valid for a specific promotional period. These vouchers are ideal for use cases such as compensation, goodwill gestures, or limited-time incentives. See the Create Programmes API for additional options that can be configured against programmes.

🖼 Recipe Overview

In this recipe, you will create a new voucher programme that generates single-use stored value vouchers. Each voucher will have a fixed or range-based balance (e.g. £5–£20), a validity period (start and end date) and single-use logic to ensure the voucher cannot be reused once redeemed. At the end of this setup, you will have a fully configured stored value programme that can issue vouchers. The vouchers issued with this setup can only be redeemed once. Any remaining value will not be spendable in future transactions.

📋 Prerequisites

Ensure you have:

• Access to Eagle Eye APIs
• Name for your voucher
• Minimum and maximum voucher value (e.g. £5 min, £50 max)
• Voucher validity dates (start and end)

📤 Outputs

As you complete each step, note these outputs for future API calls and validation:

📒 Steps

Step 1: Define Voucher Details

Start by defining the required values to create a new voucher. You will define the name, type, balance rules, and expiry window.

• 1.1 Choose a name for the voucher
• 1.2 Set the type to VOUCHER
• 1.3 Define the balance rules:
  • Values are in the currency's lowest denomination (e.g. pence or cents)
  • maxBalance: the maximum value a voucher can hold
  • minLoadAmount: the minimum load amount for a voucher
  • maxLoadAmount: the maximum load amount for a voucher
  • maxDebitAmount: the maximum amount a customer can spend at once
• 1.4 Set a start and end date for the programme
• 1.5 Select a currency value (e.g. GBP or USD)
• 1.6 Set rules.redemption.couponLimit to 1 to ensure single use

Step 2: Call POST /programmes

{
    "type": "VOUCHER",
    "status": "ACTIVE",
    "details": {
        "name": "Single Use Voucher Programme",
        "description": "",
        "startDate": "2025-05-09 00:00:00",
        "endDate": "2040-06-30 23:59:59",
        "tags": []
    },
    "settings": {
        "accountClientType": "VOUCHER",
        "defaultAccountClientState": "LOADED",
        "passphrase": false,
        "refreshToken": true,
        "currency": "GBP"
    },
    "partners": {
        "creation": [],
        "redemption": []
    },
    "rules": {
        "expiry": {
            "type": "NEVER",
            "date": null,
            "value": null
        },
        "balances": {
            "maxBalance": 50000,
            "minLoadAmount": 500,
            "maxLoadAmount": 50000,
            "maxDebitAmount": 10000
        },
        "redemption": {
            "couponLimit": 1
        }
    }
}

{
    "id": "101443267",
    "type": "VOUCHER",
    "status": "ACTIVE",
    "reference": "101443267",
    "details": {
        "name": "Single Use Voucher Programme",
        "description": "",
        "startDate": "2025-05-09 00:00:00",
        "endDate": "2040-06-30 23:59:59",
        "tags": []
    },
    "settings": {
        "tokenProvider": null,
        "tokenFormat": null,
        "cardNumber": {
            "bin": null,
            "scheme": null
        },
        "accountClientType": "VOUCHER",
        "defaultAccountClientState": "LOADED",
        "passphrase": false,
        "refreshToken": true,
        "currency": "GBP"
    },
    "partners": {
        "creation": [],
        "redemption": []
    },
    "rules": {
        "expiry": {
            "type": "NEVER",
            "date": null,
            "value": null
        },
        "balances": {
            "maxBalance": 50000,
            "minLoadAmount": 500,
            "maxLoadAmount": 50000,
            "maxDebitAmount": 10000
        },
        "redemption": {
            "couponLimit": 1
        },
        "storeRestrictions": []
    },
    "dateCreated": "2025-08-06 16:03:16",
    "lastUpdated": "2025-08-06 16:03:16"
}

✅ Business Readiness Checklist

Use these checks to confirm programme is set up correctly:

• Retrieve the programme using Create Programmes API to confirm the setup
• Create a voucher in a wallet using Create Programme Account

🔧 Troubleshooting Tips