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
Items marked with * are mandatory.
Field | Format | Description |
*contact.matchKey | string | A value to match against the specified customerKeyType and contactType |
*contact.matchKeyType | string | What the matchKeyType value represents. Options are 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 transaction already exists with this uniqueReceiptId the new transaction with the same value 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). Example: NOK, SEK, EUR |
*totalGrossPrice | decimal | 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. |
*paymentMethods | [rows] | All payment methods used in this transaction |
*items | [rows] | One row per line item in the transaction |
*receiptNumber | string | The transaction number, does not need to be unique |
exchangeRateToGroupCurrency | 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. |
usedBonusChecks | [rows] | One row per used bonus check (reward voucher) |
usedPromotions | [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]
Field | Format | Description |
*type | string | 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) |
*value | decimal | Amount as a decimal. This can't be empty. |
description | string | Descriptive text (max 255 characters) |
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 the sku. |
*articleName | string | The name |
*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 total discount. Read more under Discounts. |
*taxAmount | decimal | The VAT paid for this line item. |
*taxPercent | decimal | The VAT (moms) percentage for this line item |
articleGroup | string | The group |
marginPercent | 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. |
awardsBonus | 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, the default is "true". |
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. 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.
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 the local currency. Should always be negative. Searching for discounts in Engage is possible |
*type | string | Type of discount |
description | string | A description |
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 (reward voucher) number to be redeemed when saving the transaction. |
usedPromotion[row]
Field | Format | Description |
*promotionId | string | The promotion ID used to create the individual promotion assignments. |
*couponId | string | The ID for the "instance" of the promotion that is assigned to a contact. Don't confuse the couponId (for an individual contact) with the promotionId (the "template" used). |
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.