> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Field definitions
## The datetime format
Engage expects dates and times to be formatted according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) 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](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
Use local time with an offset, like in the example shown, instead of converting to UTC time.
## Transactions
A value to match against the specified `customerKeyType` and `contactType`.
What the `matchKeyType` value represents. Options are: contactId, memberNumber, socialSecurityNumber, mobilePhone, externalId, email.
If used, matching will only be done for this contactType. If NOT used the default value will be "Member".
If a transaction already exists with this `uniqueReceiptId` the new transaction with the same value will be seen as a duplicate and ignored.
Datetime when order was first created formatted according to ISO 8601. Example: 2017-09-06T15:55:54+01:00.
The external id for the store (usually a numerical code).
The currency code according to ISO 4217 for the currency that the customer paid in (local currency). Example: NOK, SEK, EUR.
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.
All payment methods used in this transaction.
One row per line item in the transaction.
The transaction number, does not need to be unique.
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.
One row per used reward voucher.
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]
Predefined 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).
Amount as a decimal. This can't be empty.
Descriptive text (max 255 characters).
Additional data regarding the specific payment method.
## items\[row]
A line item can either be a PURCHASE or a RETURN.
Stock keeping unit.
Can be the same as the SKU.
The name.
Number of units sold in this line item. Must be negative for a return.
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.
The VAT paid for this line item.
The VAT (moms) percentage for this line item.
The group.
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.
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".
Key/value pairs for additional data regarding the transactional line item apart from the article meta-data.
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.
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.
Discount value in the local currency. Should always be negative. Searching for discounts in Engage is possible.
Type of discount.
A description.
Key/value pairs for additional data regarding the discount.
## usedBonusCheck\[row]
The unique ID number of the reward voucher to be redeemed when saving the transaction.
## usedPromotion\[row]
The ID for the main promotion. Can be used to link the purchase to a promotion.
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](/docs/file-based-transfer/example-files).