Skip to main content

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.

When an identified contact finalizes a purchase, it should be sent to Engage and made available for segmentation and reporting. Usually a finalized purchase means that payment has been successfully processed. The data is sent to the following endpoint: 
POST /api/v3/receipts
Data sent here cannot be reversed or updated, hence the importance of only sending finalized purchases.

​
Identification

To be able to store a transaction in Voyado, you’ll need to connect it to a specific contact. The key has to be a unique data field for the specific contact type. One of these fields is used:
  • contactId
  • email
  • mobilePhone
  • memberNumber
  • externalId
  • socialSecurityNumber (actually a Swedish or Finnish Personal Identification Number)
However, the key used does NOT have to be the key value for the specific contact type. The default contact type is usually “Member”. To send transactions for any other contact type, include contactType in the request. This is not required if contactId is used as matchKeyType, since it uniquely identifies the contact.

​
Example

    "contact": {
        "matchKey": "e8a5a8ff-1616-4990-b16d-af9412999824",
        "matchKeyType": "email",
		"contactType" : "contact"
    }

​
Example payload

In the below example payload the key type is “contactId”. When using this key type, you do not need to specify contactType as contactId is always unique. 
{
    "contact": {
        "matchKey": "1c277c0a-ed93-4928-86cb-b0820090c111",
        "matchKeyType": "contactId"
    },
    "uniqueReceiptId": "20180906468464468",
    "receiptNumber": "468464468",
    "createdDate": "2018-09-06T15:55:54+01:00",
    "storeExternalId": "321",
    "currency": "NOK",
    "exchangeRateToGroupCurrency": 1.0,
    "totalGrossPrice": 200.00,
    "paymentMethods": [{
        "type": "Card",
        "description": "Debit Card",
        "value": 200.00
     }],
    "items": [{
        "type": "PURCHASE",
        "quantity": 2,
        "grossPaidPrice": 200.00,
        "taxAmount": 40.00,
        "taxPercent": 25.00,
        "sku": "10015563434",
        "articleNumber": "2324234",
        "articleName": "Gambeson",
        "articleGroup": "Jackets",
        "extraData": [{
            "name": "campaign",
            "value": "Socks 3 for 2"
        }, {
            "name": "size",
            "value": "M"
        }],
        "marginPercent": "25.00",
        "awardsPoints": false,
        "discounts": [{
            "type": "325",
            "description": "50% autumn discount",
            "value": -200.00
        }]
    }],
    "usedRewardVouchers": [{
        "voucherNumber": "2342"
    }],
    "usedPromotions": [
        {
           "couponId": "272cd4e4-5cb4-472f-8747-a61112083ccb"
        }
    ]
}
In the API v3 usedRewardVouchers has replaced usedBonusChecks and voucherNumber has replaced checkNumber.
If contact.matchKeyType is set to contactId, then contact.contactType is not a required field. If using any other matchKeyType and contactType is not provided, Engage will just use whatever your default contact type is (normally Member). A successful POST operation returns a 202 (Accepted). Transactions can also be imported through an XML file format. Read more about in this article, Receipt XML import. Find the complete list of transaction field definitions here.
In the “usedPromotions” section of the payload, send either ´couponId´ OR ´promotionId´ but not both. Voyado recommends that you use the ´couponId´ as shown here.