Register a purchase

When an identified contact finalizes a purchase, it should be sent to Customer Engagement 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

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. If you do send contactType, it will be used in the matching logic and has to match.

{
    "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, Customer Engagement 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.

Deleting transaction

If a receipt was registered by mistake, or has to be removed (for example because of a fraudulent transaction or a customer request), you can delete it using its external ID and this endpoint:

DELETE /api/v3/receipts/{externalId}

The externalId here is the external ID that identifies the receipt in Customer Engagement.

Deleting a receipt is permanent. The receipt is removed together with its line items and related data, and this cannot be undone. The deletion is also written to the audit log.

string

A free-text reason for the deletion, sent in the query string. The reason is saved in the audit log, so it’s good practice to always include one. Example values are “Fraudulent transaction” or “Customer request”.

An example request:

DELETE /api/v3/receipts/12345678?reason=Customer%20request

There is no payload sent with this request. Once a receipt has been deleted, the same external ID can be used again straight away, so you can register a corrected version of the receipt with POST /api/v3/receipts.

Responses

200 OK: The receipt was deleted.
400 Bad Request (ValidationError): The request was not valid.
404 Not Found (NoMatchingReceipt): No receipt with that external ID could be found.

This endpoint is for removing individual receipts. Don’t use it for bulk clean-up of transactions.

Contacts

Transactions

Orders

Loyalty

Product data

Ratings and Reviews (BETA)

Product Discovery

Identification

Example

Example payload

Deleting transaction

Responses

​Identification

​Example

​Example payload

​Deleting transaction

​Responses

Identification

Example

Example payload

Deleting transaction

Responses