Skip to main content

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, you can't always trust that the currency conversion is set up correctly in the backend, so it is strongly recommended that you include this field in your import file.

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

Tells Engage that this specific line item should not be included when calculating bonus. Values are 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. 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.

segmentsearch.png

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