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

### 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

 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)