Skip to main content

Voucher export (XML)

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.

Adding a port to the external FTP

It's possible to specify a port with the FTP hostname, in the way shown here:

port-on-ftp-url.png

Field descriptions

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

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 / 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>

Settings and limits

These are the back-end settings for the export.

vouchers-xml-export.png

Note that when "0" is used as the amount in the second field it means "unlimited".

Caution

10,000 vouchers per file is considered the limit. Don't exceed this.