Skip to main content

Voyado Engage

Receipts - field definitions

The datetime format

Whenever a datetime is used, Engage expects it ti 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 the matching will only be done for this specific contactType. NOTE! 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

receiptNumber

string

The receipt number. Does not need to be unique

*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

*currency

currency

The curreny code according to ISO 4217 for the currency that the customer paid in (local currency). Ex: NOK, SEK, EUR

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.

*totalGrossPrice

decimal

The total price paid by he customer including VAT. A punctation(.) is always used as decimal separator. If the transaction is of type RETURN then totalGrossPrice should be negative.

*paymentMethods

[rows]

All payment methods used on this tranaction

*items

[rows]

One row per line item on the receipt

usedBonusChecks

[rows]

One row per used bonus check

usedPromotions

[rows]

One row per used promotion

Note that taxDetails is no longer required to be sent. Now it is calculated internally from the other data.

paymentMethods[row]

Field

Format

Description

*type

string

Pre-defined values can be set: “card”, “cash”, “creditcard”, “bonuscheck”, “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. Ex: [{ "name": "checkNumber", "value": "14546516465" }]

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 rebate 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 rebate. One row per discount type.

Discounts – items[row].discounts[row]

Voyado will always need rebates to be taken care of before sending the receipt to Voyado. The grossPaidPrice should always describe the amount the contact has paid for the item, i.e rebate 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 nature of a rebate, item.discount can be used to tell Voyado what discounts have been used. If a line item is exposed for both a receipt rebate, for instance 20% on a whole purchase, and a 100 SEK off for that article, both those values then adds up to the total value withdrawn from the original price. These row values aggregated are stored as a parameter for searching in Voyado.

segmentsearch.png

In Voyado the search mechanism looks for every receipt a contact has made containing one or several items that have been exposed to discounts greater/less/equal to a total value or total percentage of the original price.

Note

The Voyado instance needs to be activated for searching on discounts. Please contact your Voyado team for configuration requests.

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 the item.type=return and quantity should be negative

  • A purchase should have item.type=purchase and quantity should be positive

  • quantity should never be 0

  • Sum of all paymentMethods should equal totalGrossPrice.

  • Sum of all grossPaidPrice should equal totalGrossPrice

  • taxAmount should equal grossPaidPrice - grossPaidPrice / (1 + taxPercent / 100)

You can download the XSD schema from here.