> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vouchers
Vouchers are part of the **Promotions** module. Administrators can create vouchers based on the client configuration. If a contact meets the requirements then one or more vouchers can be granted to the contact.
As an Engage user, you decide how a contact's points are converted to vouchers. Depending on how your model is set up, you can either:
* Convert all earned points into the corresponding monetary value and then clear the points
* Use a step model to send out vouchers with fixed amounts
Your points model also determines what the minimum points are for vouchers to be paid out.
## Getting a contact's vouchers
Once a contact has been identified, and you have their `contactId`, you can fetch their available vouchers with the following request:
```http Fetch active vouchers for customer theme={null}
GET /api/v3/reward-vouchers/available
```
You can also fetch all of their vouchers (expired and redeemed as well as available) like this:
```http Fetch active, expired and redeemed vouchers for customer theme={null}
GET /api/v3/reward-vouchers
```
Or you can fetch only those vouchers with the status redeemed:
```http Fetch only redeemed vouchers for customer theme={null}
GET /api/v3/reward-vouchers/redeemed
```
In all these cases, the GUID of the contact is appended to the URL as the parameter contactId as in this example:
```http theme={null}
GET /api/v3/reward-vouchers?contactId=a3835e0b-4acd-480f-9a24-ceac75337237
```
### Response
Below is an example of a successful response with a *HTTP 200 OK* status and one voucher returned (in the items array).
```json Example payload response theme={null}
{
"count": 1,
"offset": 0,
"items": [
{
"id": "af61c5c8-7ff8-1234-9b67-c75300738cd3",
"voucherNumber": "2511233093766",
"name": "Bonus payment 2017-04-12 07:00",
"redeemedOn": "2023-02-08T12:15:59.212Z",
"redeemed": true,
"expiresOn": "2023-02-08T12:15:59.212Z",
"value": {
"currency": "SEK",
"amount": 195
},
"localValues": [
{
"currency": "NOK",
"amount": 195
},
{
"currency": "EUR",
"amount": 19.5
}],
"points": 4869
}
],
"totalCount": 1
}
```
## Redeem a voucher
Redeeming a voucher means telling Engage that the voucher has been used and that its status should now change from available to redeemed.
To redeem a voucher for a specific contact, use this endpoint:
```http Redeem voucher for customer theme={null}
POST /api/v3/reward-vouchers/{rewardVoucherId}/redeem
```
Since the `rewardVoucherId` is unique for the contact who has it, the `contactId` does not need to be sent.
After 4.5 seconds this endpoint will give up and time out, provided it has not already saved the voucher as redeemed. If the voucher *has* been redeemed (this is also also known as the "point of no return") when the 4.5 seconds limit is passed, the request will be processed until completion.
It is recommended to not have a timeout shorter than 60 seconds, in order to avoid situations where a voucher is redeemed in Engage but the calling system does not know it due to aborting the request.
If the request has been successful, you'll get a *HTTP 200 OK* response. Otherwise you'll get one of these:
* *400: InvalidRewardVoucherId*
* *404: RewardVoucherNotFound*
* *409: RewardVoucherAlreadyRedeemed, RewardVoucherExpired*
* *504: GatewayTimeout*
## Reactivate a voucher
A used voucher can be reactivated and have its status changed from redeemed back to available.
To reactivate a voucher (which is connected to a specific contact) you use this endpoint:
```http Reactivate a voucher for customer theme={null}
POST api/v3/reward-vouchers/{rewardVoucherId}/reactivate
```
Where `rewardVoucherId` is the reward voucher's unique ID.
If the reactivation has worked, you'll get a *HTTP 200 OK* response. Otherwise, one of these:
* *400: InvalidRewardVoucherId*
* *404: RewardVoucherNotFound*
* *409: RewardVoucherAlreadyActivated, RewardVoucherExpired, ReactivationLimitExceeded*
In the voucher configuration in Engage you can specify how many times a voucher can be reactivated. 3 times is the default. It you try to reactivate the voucher more times than that, you will get the *409* error above.
Reactivating a voucher does not change any of its data, such as the value, the expiry date and so on. These will remain as they were when the voucher was created.
## Webhooks
Engage provides webhooks for working with points and vouchers.
## Voucher XML export
Engage can export voucher data as XML files. Using this, you can export both new (unused) and redeemed vouchers.
The XML files generated are saved into your tenant-specific folder on the Engage FTP server:
```bash theme={null}
[base-ftp-url]/integration/bonusCheckExport
```
This is done using a scheduled job (called "Export reward vouchers"). How often this job runs can be configured. Your Voyado team can help you with setting up the FTP folders as well as the scheduled job.
### XML export fields
Only one contact field (marked with \*) can be used together with **contactKey**.
| Field | Example value | Description |
| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| checkNumber | 0000000111751 | An incremental numerical ID. The start value can be decided by the client and set by a product specialist. |
| contactKey | 1000005760 | The key value set in the environment for the client. |
| amount | 40.0000 | The monetary amount of the voucher, always shown in the group currency as configured for this Engage tenant. This is applied as a payment method or a discount on the transaction. |
| validFrom | 2020-04-21T00:00:00 | Date and time from when the voucher is valid |
| expires | 2021-04-21T00:00:00 | Date and time when the voucher expires |
| bonusPoints | 2000.0000 | Number of bonus points withdrawn to generate the voucher |
| usedDate | 2020-06-21T00:00:00 | Date and time when the voucher was redeemed in Engage. |
| contactId\* | 67ea3358-0e09-484f-d1c4-aa3e00e1e29c | The contact's unique ID in Engage. |
| externalId\* | 1526235 | Identification key for external systems. |
| memberNumber\* | 12345678 | Contact's member number. |
| socialSecurityNumber\* | 198101010101 | Contact's personal identity number. |
| email\* | [example@example.com](mailto:example@example.com) | Contact's email address. |
| mobilePhone\* | +46739111111 | Contact's mobile phone number. |
### Default XML format
This export cannot be transformed or modified through an XSLT-transformation. The format is fixed.
### New (unused and available) vouchers
```xml theme={null}
0000000111751
1000005760
40.0000
2020-04-21T00:00:00
2020-12-31T23:59:59
2000.0000
+46702291216
...
```
### Used (redeemed) vouchers
```xml theme={null}
...
0000000110099
7000247
2020-04-23T10:27:27
```