Skip to main content

Voyado Engage

Register a purchase

When an identified contact finalizes a purchase, it should be sent to Engage and made available for segmentation and reporting. Most often a finalized purchase means that payment has been successfully processed.

Sending the data is normally done through the following endpoint:

POST /api/v2/receipts

Data sent to this endpoint cannot be reversed or updated, hence the importance of only sending finalized purchases.

Identification

To be able to store a receipt in Voyado, you'll need to connect it to a specific contact.

In this example the contact type is “Member” and the key type is “memberNumber” (normally a unique sequence created by Voyado). 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.

Example payload

{
    "contact": {
        "matchKey": "28972987289",
        "matchKeyType": "memberNumber",
        "contactType": "member"
    },
    "uniqueReceiptId": "20180906468464468",
    "receiptNumber": "468464468",
    "createdDate": "2018-09-06T15:55:54+01:00",
    "storeExternalId": "Store1337",
    "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": "Ipsum Wool Jacket",
        "articleGroup": "Jackets",
        "extraData": [{
            "name": "campaign",
            "value": "Socks 3 for 2"
        }, {
            "name": "size",
            "value": "M"
        }],
        "marginPercent": "25.00",
        "awardsBonus": false,
        "discounts": [{
            "type": "325",
            "description": "50% autumn discount",
            "value": -200.00
        }]
    }],
    "usedBonusChecks": [{
        "checkNumber": "2342"
    }],
    "usedPromotions": [{
        "promotionId": "6374dfaa-31c5-4e34-bb88-7ccfc5fe8bf7"
    }]
}

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.

After the POST operation returns a 202 (Accepted), a receipt is created.

Receipts can also be imported through an XML file format. Read more about in this article, Receipt XML import.

Find the complete list of Field definitions here.