Skip to main content

Introduction to transactions

A transaction, as defined in Engage, is when a customer visits a physical or online store and purchases (or returns) one or more items. The transaction contains its own data -- such as the transaction's unique ID, the store's ID, the timestamp -- plus the data for each individual item that was purchased or returned (known as the line items).

All fields in the transaction data model can be used for segmentation and analysis in Engage.

Caution

Transaction data is sent to the endpoint called /receipts. You might see the term "receipt" turning up other places in the Engage API or in field names. Keep in mind that "receipt" means "transaction".

Warning

You might also come across an API endpoint named /transactions. This is a legacy endpoint maintained for a few older clients, so, despite the name, do NOT send your transaction data here.

Processing of API calls

Transactions posted to the /receipts API are not relayed to the database immediately. Instead, they are collected and, at a preset interval, converted into an XML file. This XML is processed and applied to the database. By default, an XML is generated every 15 minutes, meaning it could take this amount of time for a transaction 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 transaction XML is converted through XSLT in the same way as historical transaction which 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 transaction 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 transaction import. This richer object would then be accessible to future versions of the API.

Duplicates

Any transaction imported that has the same uniqueReceiptId as an already existing transaction in the database will be seen as a duplicate and ignored.

Discounts (line-item and total)

Total 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 transaction

Once a transaction is imported into Engage it is not possible to update it 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 metadata and spare fields

Engage can access all product metadata from the transaction as well as the specific line items. Read more about other options here. There are also a limited amount of fields per product that can be used for storing extra data for a transaction:

  • 10 spare string fields (spare1, spare2 ... spare10)

  • 10 spare date fields (datespare1, datespare2 ... datespare5)

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 transaction 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 transaction.

So freight should always be excluded from the transaction's total, even if the e-com handles it separately, whether per item row or as a total amount. Regardless on how the e-com 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 only 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 item.type as "return" and quantity should be negative

  • A purchase should have item.type as "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 grossPaidPricegrossPaidPrice / (1 + taxPercent / 100)

  • createdDate should be in ISO8601 with time zone designator