Skip to main content
Engage expects dates and times to be formatted according to ISO8601 with Time Zone Designators. For example:
This represents 10:14 on the 12th of November, 2021, in a time zone one hour ahead of UTC.
Use local time with an offset, like in the example shown, instead of converting to UTC time.

​
Transactions

The fields are as follows:
​
string
required
A value to match against the specified customerKeyType and contactType.
​
string
required
What the matchKeyType value represents. Options are: contactId, memberNumber, socialSecurityNumber, mobilePhone, externalId, email.
​
string
required
If used, matching will only be done for this contactType. If NOT used the default value will be “Member”.
​
string
required
If a transaction already exists with this uniqueReceiptId the new transaction with the same value will be seen as a duplicate and ignored.
​
datetime
required
Datetime when order was first created formatted according to ISO 8601. Example: 2017-09-06T15:55:54+01:00.
​
string
required
The external id for the store (usually a numerical code).
​
currency
required
The currency code according to ISO 4217 for the currency that the customer paid in (local currency). Example: NOK, SEK, EUR.
​
decimal
required
The total price paid by the customer including VAT. A decimal point (.) is always used as decimal separator. If the transaction is of type RETURN then totalGrossPrice should be negative.
​
rows
required
All payment methods used in this transaction.
​
rows
required
One row per line item in the transaction.
​
string
required
The transaction number, does not need to be unique.
​
decimal
Currency values for a transaction should be in the local currency. This multiplier is used to convert those to a group currency when storing them for segmentation and reporting. Omitting this will cause problems.
​
rows
One row per used reward voucher.
​
rows
One row per used promotion.
While exchangeRateToGroupCurrency is not mandatory, it’s recommended in order to ensure that currency conversions are correct. If no exchange rate is sent, Engage will use the fallback conversion set up in the back-end. If contact.matchKeyType is set to contactId, then contact.contactType is not a required field. In this case, if the value is not given, Engage will just use whatever your default contact type is.

​
paymentMethods[row]

​
string
required
A string, for example: “card”, “cash”, “creditcard”, “swish”, “klarna” (max 245 characters).
​
decimal
required
Amount as a decimal. This can’t be empty.
​
string
Descriptive text (max 255 characters).
​
array
Additional data regarding the specific payment method. This field is accepted in the request but is not stored, processed, or available for segmentation in Engage. If you need to act on or segment by this information, contact your Voyado team so they can advise on the best approach.

​
items[row]

​
string
required
A line item can either be a PURCHASE or a RETURN.
​
string
required
Stock keeping unit.
​
string
required
Can be the same as the SKU.
​
string
required
The name.
​
integer
required
Number of units sold in this line item. Must be negative for a return.
​
decimal
required
The paid price including VAT for this line item. Note: always withdraw discount values for the item itself or the distributed discount value for a total discount. Read more under Discounts.
​
decimal
required
The VAT paid for this line item.
​
decimal
required
The VAT (moms) percentage for this line item.
​
string
The group.
​
decimal
The margin in percent on this order line. Can’t be empty or negative. Note that your Engage instance needs to be activated for searching on margins. Please contact your Voyado team for configuration requests.
​
bool
Flag that controls if the line item should award points or not when generating reward points. Values are “true” or “false”. If not specified, this will default to “true”.
​
array
Key/value pairs for additional data regarding the transactional line item apart from the article meta-data.
​
rows
Could be several sources of discounts for the total discount. One row per discount type.
The grossPaidPrice value sent to Engage always reflects the total price paid for a specific item or multiples of that item. So if quantity for an item is greater than 1 (or less than -1) then grossPaidPrice is the total price of all those items. Or to put it another way, the calculation of (quantity * item price) is already done. Of course, if quantity is 1, then grossPaidPrice is just the single item price.
For returns, quantity is always negative but grossPaidPrice is still positive.

​
Discounts - items[row].discounts[row]

Engage requires discounts to be taken care of before the data is sent. The grossPaidPrice should always describe the amount the contact has paid for the item, meaning that the discount values withdrawn with the following patterns:
  • Full discounts (e.g. 20% off the whole purchase) should always be applied for every line item, equally distributed.
  • Specific transaction item discounts should be withdrawn for the specific line item only.
Regardless of the nature of a discount, item.discount can be used to tell Engage what discounts have been used. If a line item is exposed to both a full discount, for instance 20% on a whole purchase, and a 100 SEK off for that article, these are combined to make the total value withdrawn from the original price. These aggregated row values are stored as a parameter for searching in Engage.
Screenshot of Engage showing how the aggregated row values can be used as a search parameter

Aggregated row values as search parameter

In Engage the search locates every transaction connected to a particular contact that contains one or more items that have been exposed to discounts greater/less/equal to a total value or total percentage of the original price.
Searching using discounts needs to be activated in your set-up. Please contact your Voyado team about this.
​
decimal
required
Discount value in the local currency. Should always be negative. Searching for discounts in Engage is possible.
​
string
required
Type of discount.
​
string
A description.

​
usedRewardVouchers[row]

​
string
required
The unique ID number of the reward voucher to be redeemed when saving the transaction.

​
usedPromotions[row]

​
string
required
The ID for the main promotion. Can be used to link the purchase to a promotion.
​
string
required
The ID for the “instance” of the promotion assigned to a contact.
Don’t confuse the couponId (for an individual contact) with the promotionId (the “template” used).
Voyado recommends you use couponId over promotionId if possible, to avoid ambiguity in matching.

​
Validations

  • discounts.value should always be negative
  • A return should have item.type “RETURN” and the quantity should be negative
  • A purchase should have item.type “PURCHASE” and the quantity should be positive
  • A quantity should never be 0
  • Sum of all paymentMethods should equal totalGrossPrice
  • Sum of all grossPaidPrice should equal totalGrossPrice
  • The taxAmount should equal grossPaidPrice - grossPaidPrice / (1 + taxPercent / 100). The rounding error precision of this validation is by default 0.01. This value can be configured in the Engage backend to other values, or also turned off completely.
You can download the XSD schema on the example files page.