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:

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.

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.

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*	[e-mail]	Contact’s email address.
mobilePhone*	[phone]	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 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>[phone] </mobilePhone>
  </new>
...

Used (redeemed) vouchers

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