Receipts - field definitions

The datetime format

Engage expects dates and times to be formatted according to ISO8601 with Time Zone Designators. For example:

2021-11-12T10:14:00+01:00

This represents 10:14 on the 12th of November, 2021, in a time zone one hour ahead of UTC.

Caution

Use local time with an offset, like in the example shown, instead of converting to UTC time.

Transactions

Note

Items marked with * in the tables are mandatory

Field	Format	Description
*contact.matchKey	string	A value to match against the specified customerKeyType and contactType
*contact.matchKeyType	string	Valid options: contactId, memberNumber, socialSecurityNumber, mobilePhone, externalId, email
*contact.contactType	string	if used, matching will only be done for this contactType. If NOT used the default value will be "Member"
*uniqueReceiptId	string	If a receipt already exists with the same uniqueReceiptId this will be seen as a duplicate and ignored
*createdDate	datetime	Datetime when order was first created formatted according to ISO 8601. 2017-09-06T15:55:54+01:00
*storeExternalId	string	The external id for the store (usually a numerical code)
*currency	currency	The currency code according to ISO 4217 for the currency that the customer paid in (local currency). Ex: NOK, SEK, EUR
*totalGrossPrice	decimal	The total price paid by he customer including VAT. A decimal point (.) is always used as decimal separator. If the transaction is of type RETURN then totalGrossPrice should be negative.
*paymentMethods	[rows]	All payment methods used in this transaction
*items	[rows]	One row per line item on the receipt
receiptNumber	string	The receipt number. Does not need to be unique
exchangeRateToGroupCurrency	decimal	All currency values for a receipt should be in local currency and this multiplier is used to convert o a group currency when storing the values for segmentation and reporting purposes. Voyado will have to store an exchangeRate if omitted and the paid currency differs from the group currency.
usedBonusChecks	[rows]	One row per used bonus check
usedPromotions	[rows]	One row per used promotion

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]

Field	Format	Description
*type	string	Pre-defined values can be set: “card”, “cash”, “creditcard”, “swish”, “klarna”. If your value does not match one of the above, it will be categorized as custom: “custom: [value]” (max 245 characters)
*description	string	Descriptive text (max 255 characters)
*value	decimal	Amount as a decimal. This can't be empty.
extraData	array of name value pairs	Additional data regarding the specific payment method.

items[row]

Field	Format	Description
*type	string	A line item can either be a PURCHASE or a RETURN
*sku	string	Store keeping unit.
*articleNumber	string	Can be the same as sku.
*articleName	string
articleGroup	string
*quantity	integer	Number of units sold in this line item. Must be negative for a return.
*grossPaidPrice	decimal	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 complete receipt discount. Read more under "discounts".
*taxAmount	decimal	The paid VAT for this line item.
*taxPercent	decimal	The VAT (moms) percentage for this line item
marginPercent	decimal	The margin in percent on this order line. Can't be left empty or a negative value. Note! The Voyado instance needs to be activated for searching on margins. Please contact your Voyado team for configuration requests.
awardsBonus	bool	Tells Voyado that this specific line item should not be included when calculating bonus. TRUE or FALSE
extraData	array of name value pairs	key/value pairs for additional data regarding the transactional line item a part from the article meta-data.
discounts	[rows]	Could be several sources of discounts for the total discount. One row per discount type.

Important

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 if 1, then grossPaidPrice is just the single item price.

Important

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 to Voyado. 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 receipt discounts (e.g. 20% off the whole purchase) should always be applied for every line item, equally distributed.
Specific receipt 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 receipt 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.

In Engage the search looks for every receipt 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.

Note

Searching using discounts needs to be activated in your set-up. Please contact your Voyado team about this.

Field	Format	Description
value*	decimal	Discount value in local currency. Should always be negative. Search for discounts is in Voyado possible.
type*	string	Type of discount
description	string
extraData	array of name value pairs	key/value pairs for additional data regarding the discount. Ex: [{ "name": "category", "value": "75" }]

usedBonusCheck[row]

Field	Format	Description
*checkNumber	string	The unique bonus check number to be redeemed when saving the receipt

usedPromotion[row]

Field	Format	Description
*promotionId	string	The promotion ID for the specific customer assignment. Be careful to not use the ID for the main promotion here -- this is the specific promotion ID for this contact.

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)

You can download the XSD schema on the example files page.

In this section:

Voyado Engage