📌 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

Note: If the programme should be restricted for use in one or more banners, the rules.storeRestrictions object can be added to the request payload, else the resulting stored value accounts can be managed at any banner within the company.

    "rules": {
        "storeRestrictions": {
            "{bannerIdentifier}": {
                "included": {
                    "locationIdentifiers": null
                }
            }
        }
    }

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": false,
        "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": false,
        "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