Skip to main content

Voyado Engage

Introduction to receipts

In Voyado Engage, a contact's transactions, both purchases and returns, are stored in a rich model called receipts, using an adaptable but slim database object. Besides the standard fields, every receipt line item can also have up to 10 extra configurable string fields and 5 date fields. All fields in the receipt model can be used for segmentation and analysis in Engage.

Processing of calls to the API

Data posted to the /receipts API is not relayed to the database immediately. Instead, receipts are collected and, at a preset interval, converted into an XML file. This XML is then processed and applied to the database. By default, an XML is generated every 15 minutes, meaning that it could take this amount of time for a receipt to be registered in the database. It’s possible to change this interval, all the way down to 0 minutes if needed, to speed up testing. Talk to your Voyado Engage team about this.

The receipts XML is converted through XSLT in the same way as historical receipts that are imported through Engage's ftp. However, no XSLT is required in this case as long as no special transformations are used.

Extended data

The receipt data model is much richer than what is currently stored in the production environment database. It is in the roadmap to also save this extended data in the Voyado Data Lake before it is processed and then modeled as a regular “receipt” import. This richer object would then be accessible to future versions of the API.

Duplicates

Any receipt imported, having the same uniqueReceiptId as an existing receipt, will be seen as a duplicate and ignored.

Discounts (line-item and total-receipt)

Total-receipt discounts (ex. 30% on an entire purchase) should not be recorded as a separate line item. Instead, the discount should be applied on each line-item so that each item reflects the actual price paid for the item. The same applies for line item discounts (ex. 25% on a specific item), where the discount should be deducted from the specified line item price (i.e. original price * 0.75).”. Read more about discounts below and in the section Discounts

Updates to a receipt

Once imported into Engage it is not possible to update a receipt with new information.

Group currency and local currency

Group currency is the default currency for the specific Engage instance, normally decided in the pre-study. The property currency.conversion.factors  sets the different exchange rates used when converting between the group currency and the local currency.

Product meta data and spare fields

Engage can obtain all product metadata from the receipt and the specific line items. Read more about other options here. But there are a limited amount of fields, per product, available for storing extra data in conjunction with a transaction:

  • 10 so-called spare fields (typed as strings)

  • 10 spare date fields

These fields can be found in the API and XML under “extraData”. If they are named the same as in the client configuration, no transformation needs to be done.

Freight

In Engage's receipt model, freight should not be included, to avoid the end-user being awarded bonus points based on the freight cost. Bonus points should only be based on what the end-user has actually paid for their purchase.

There are also some reports and KPIs in Engage that require the freight fee to be excluded. For example: most purchased articles, number of articles purchased, total purchase amount and the average amount on the receipt.

So freight should always be excluded from the receipt's total, even if the ECOM handles it separately, whether per item row or as a total amount. Regardless on how the ECOM handles it, the amount total on the receipt sent to Engage is calculated without the freight cost, and the amount for each item must sum to the total amount.

Note

This is true for the endpoint /receipts. For the /orders endpoint, Engage uses an object called freightFee to inform the end customer, in their order communication emails, how much they have paid for freight.

Validations

  • discounts.value should always be negative

  • A return should have the item.type=return and quantity should be negative

  • A purchase should have item.type=purchase and quantity should be positive

  • quantity should never be 0

  • Sum of all paymentMethods should equal totalGrossPrice.

  • Sum of all grossPaidPrice should equal totalGrossPrice

  • taxAmount should equal grossPaidPrice – grossPaidPrice / (1 + taxPercent / 100)

  • createdDate should be in ISO8601 with time zone designator