Skip to main content
A transaction, as defined in Customer Engagement, 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 Customer Engagement.
Transaction data is sent to the endpoint called /receipts. You might see the term “receipt” turning up other places in the Customer Engagement API or in field names. Keep in mind that “receipt” means “transaction”.
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 Customer Engagement team about this. The transaction XML is converted through XSLT in the same way as historical transaction which are imported through Customer Engagement’s ftp. However, no XSLT is required in this case as long as no special transformations are used.

​
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 Customer Engagement it is not possible to update it with new information.

​
Group currency and local currency

Group currency is the default currency for the specific Customer Engagement 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

Customer Engagement 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 Customer Engagement’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 Customer Engagement 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 Customer Engagement is calculated without the freight cost, and the amount for each item must sum to the total amount.
This is only true for the endpoint /receipts. For the /orders endpoint, Customer Engagement 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 grossPaidPrice – grossPaidPrice / (1 + taxPercent / 100)
  • createdDate should be in ISO8601 with time zone designator