Skip to main content

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 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:
Fetch active vouchers for customer
GET /api/v3/reward-vouchers/available
You can also fetch all of their vouchers (expired and redeemed as well as available) like this:
Fetch active, expired and redeemed vouchers for customer
GET /api/v3/reward-vouchers
Or you can fetch only those vouchers with the status redeemed:
Fetch only redeemed vouchers for customer
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: 
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).
Example payload response
{
  "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:
Redeem voucher for customer
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:
Reactivate a voucher for customer
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.
https://mintcdn.com/voyado/Ns4bBcK3LNctK_Un/icons/developer-link.png?fit=max&auto=format&n=Ns4bBcK3LNctK_Un&q=85&s=fbd08f956358ab12f664a7158e1a1399

Read more about webhooks for 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: 
[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.
FieldExample valueDescription
checkNumber0000000111751An incremental numerical ID. The start value can be decided by the client and set by a product specialist.
contactKey1000005760The key value set in the environment for the client.
amount40.0000The 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.
validFrom2020-04-21T00:00:00Date and time from when the voucher is valid
expires2021-04-21T00:00:00Date and time when the voucher expires
bonusPoints2000.0000Number of bonus points withdrawn to generate the voucher
usedDate2020-06-21T00:00:00Date and time when the voucher was redeemed in Engage.
contactId*67ea3358-0e09-484f-d1c4-aa3e00e1e29cThe contact’s unique ID in Engage.
externalId*1526235Identification key for external systems.
memberNumber*12345678Contact’s member number.
socialSecurityNumber*198101010101Contact’s personal identity number.
email*example@example.comContact’s email address.
mobilePhone*+46739111111Contact’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 version="1.0" encoding="utf-8"?>
<bonusChecks>
  <new>
    <checkNumber>0000000111751</checkNumber>
    <contactKey>1000005760</contactKey>
    <amount>40.0000</amount>
    <validFrom>2020-04-21T00:00:00</validFrom>
    <expires>2020-12-31T23:59:59</expires>
    <bonusPoints>2000.0000</bonusPoints>
    <mobilePhone>+46702291216 </mobilePhone>
  </new>
...

​
Used (redeemed) vouchers

...
  <used>
    <checkNumber>0000000110099</checkNumber>
    <contactKey>7000247</contactKey>
    <usedDate>2020-04-23T10:27:27</usedDate>
  </used>
</bonusChecks>