Overview

The Fetch Voucher API enables you to retrieve voucher codes assigned to users through CleverTap’s Partner Voucher Campaigns. These vouchers can be displayed in the user's voucher tray within your application, allowing a seamless reward experience and promoting post-campaign engagement.

Sample UI Behavior

Here’s how businesses can implement client-side behaviors when integrating the Fetch Voucher API into their applications. These usage patterns help ensure a seamless and intuitive user experience when displaying assigned vouchers:

Logged-in User: Call the API with their identity to show assigned vouchers.
Anonymous User: Skip the API call, or show an empty tray with a message prompting login.
Voucher Expiry: Use the listExpiry timestamp to filter out expired vouchers on the business's side.

Base URL

Here is an example base URL from the account in the India region:

https://sk1.api.clevertap.com/1/promo/vouchers

Region

To identify the API endpoint for the region of your account, refer to Region.

Headers

For more information about API headers used while processing API requests, refer to Headers.

HTTP Method

GET

Query Parameters

Parameter	Description	Required	Data Type	Sample Value
identity	Unique identifier for the user. Accepts phone (E.164 format), email, or CleverTap ID.	Yes	String	`+919538784114`

Sample Responses

The Fetch Voucher API returns different types of responses based on the validity of the input and the state of the user’s assigned vouchers. Below are sample responses for common scenarios:

Success Response

On success, the API returns a list of vouchers assigned to the user:

{
    "status": "success",
    "records": [
        {
            "listExpiry": 1750789800,
            "listTag": "summersale",
            "partner": "AMAZON",
            "campaignId": 1500,
            "externalVoucherId": 1434,
            "listName": "FLAT1000",
            "listDescription": "Get flat 1500 offer on Amazon using this voucher",
            "voucherCode": "BMO9IW7QTALK"
        },
        {
            "listExpiry": 1750789800,
            "listTag": "newyearsale",
            "partner": "FLIPKART",
            "campaignId": 1501,
            "externalVoucherId": 1434,
            "listName": "FLAT20%",
            "listDescription": "Get 20% offer on electronics items",
            "voucherCode": "3248BO386IJG"
        }
    ]
}

Key	Description	Type	Sample Value
`voucherCode`	The voucher code assigned to the user.	String	`BMO9IW7QTALK`
`listName`	Name of the voucher list from which the code is drawn.	String	`summersale`
`listTag`	Tag associated with the voucher list. (@Bajrang: how is code different from tag??)	String	`FLAT1000`
`listExpiry`	Expiry of the voucher list in the Epoc timestamp format.	Epoch	`1750789800`
`partner`	Partner or brand name associated with the voucher.	String	`FLIPKART`
`campaignId`	Campaign ID from which the voucher was assigned.	Number	`1500`
`externalVoucherId`	Voucher list ID from which the voucher code is assigned.	Number	`1434`
`listDescription`	Optional description of the voucher list.	String	`"Offer is applicable on orders above $100"` (empty if none)

Empty Response

If the identity is valid but no vouchers are assigned, the API returns the following response:

{
    "status": "success",
    "records": []
}

Error Response

If the identity is missing or invalid:

{
    "status": "fail",
    "error": "Invalid identity",
    "code": 400
}

Errors

To know about the errors applicable to the Fetch Voucher API, refer to API Error Cases.