Purchases and returns
The /orders endpoint is used to trigger automation flows in Engage for purchases and returns sent from an e-commerce system or store. This method is called every time a change happens that you want to be able to act on in Engage.
All the data needed must be sent with every call, since this endpoint saves no data concerning orders. The endpoint used is:
POST /api/v2/orders
If you need to access saved data use the /receipts endpoint instead.
Purchase
In this example the purchase is matched to the contact using the attribute email, which is a recommended attribute and exists within multiple contact types. The other recommended attribute is mobilePhone.
Call the endpoint above with this payload:
{
"contact": {
"matchKey": "example@example.com",
"matchKeyType": "email"
},
"orderStatus": "Order_Confirmation",
"paymentStatus": "Confirmed",
"orderNumber": "435453431",
"createdDate": "2021-06-22T15:55:54Z",
"shippingDate": "2021-06-23T15:55:54Z",
"statusChangedDate": "2021-06-23T15:55:54Z",
"storeId": "9999",
"currency": "SEK",
"language": "sv",
"totalGrossPrice": 1595.00,
"freightFee": {
"value": 95.00,
"tax": 19.00
},
"totalTax": 319.00,
"extraData": {
"CreatedDate": "2021-06-22",
"ShippingDate": "2021-06-23",
"ReturnDate": "2021-08-05",
"TrackingNumber": "234567",
"TrackingLinkHTML": "http://trackinglink.se",
"ShippingMethod": "DHL ombud",
"ShippingAddressFirstName": "Example",
"ShippingAddressLastName": "Examplesson",
"ShippingAddressStreet": "Examplegatan 1",
"ShippingAddressZipCode": "123 45",
"ShippingAddressCity": "Examplestan",
"ShippingAddressCountry": "Sweden",
"ShippingAddressPhone": "+46739111111",
"ShippingAddressEmail": "example@example.com",
"PaymentMethod": "Klarna",
"BillingAddressFirstName": "Example",
"BillingAddressLastName": "Examplesson",
"BillingAddressStreet": "Examplegatan 1",
"BillingAddressZipCode": "123 45",
"BillingAddressCity": "Examplestan",
"BillingAddressCountry": "Sweden",
"BillingAddressPhone": "+46739111111",
"BillingAddressEmail": "example@example.com",
"CurrencyBeforePrice": "£",
"CurrencyAfterPrice": "Kr",
"PromotionDescription": "VIP discount",
"PromotionValue": "-199",
"RewardVoucher": "-50",
"GiftCard": "-300",
"TotalGrossPriceAfterDiscount": "1046",
"TotalTaxAfterDiscount": "269,20"
},
"items": [{
"type": "purchase",
"sku": "15615624",
"quantity": 2,
"grossPaidPrice": 1200.00,
"taxAmount": 240.00,
"taxPercent": 25.00,
"description": "Bitz pastakom Ø20 cm mat",
"imageUrl": "https://www.voyado.com/api/products/sku/image/44460-02",
"targetUrl": "https://www.voyado.se/api/products/sku/redirect/44460-02",
"extraData": {
"Size": "20 cm",
"Brand": "Bitz"
}
},
{
"type": "purchase",
"sku": "1001556",
"quantity": 4,
"grossPaidPrice": 300.00,
"taxAmount": 60.00,
"taxPercent": 25.00,
"description": "Bitz jumbo teacup",
"imageUrl": "https://www.voyado.com/api/products/sku/image/36828-02",
"targetUrl": "https://www.voyado.se/api/products/sku/redirect/36828-02",
"extraData": {
"Size": "",
"Brand": "Bitz"
},
"discounts": [{
"type": "325",
"description": "4 for the price of 3",
"value":-100.00
}]
}]
}Returns
Returned items always need to have type set to "return" and the quantity given needs to be negative.
When one or more line items are defined as type "return", this can be used to trigger automations flow in Engage.
{
"contact": {
"matchKey": "example@example.com",
"matchKeyType": "email"
},
"orderStatus": "RETURN",
"paymentStatus": "CONFIRMED",
"orderNumber": "435223435",
"createdDate": "2017-09-06T15:55:54+01:00",
"shippingDate": "2017-09-06T15:55:54+01:00",
"statusChangedDate": "2017-09-06T15:55:54+01:00",
"storeId": "1234",
"currency": "SEK",
"language": "sv",
"totalGrossPrice": -50.00,
"freightFee": {"value":50.00},
"totalTax": -20.00,
"items": [{
"type": "return",
"sku": "1001556",
"quantity": -1,
"grossPaidPrice": 100.00,
"taxAmount": 20.00,
"taxPercent": 25.00,
"description": "Riely KAVAJ STANTON WOOL STRETCH",
"imageUrl": "http://image.voyado.com",
"targetUrl": "http://stuff.com/cool"
}]
}Best practice for discounts
This is an example of how you would handle an order with a 3 for 2 campaign. The order contains three items where the original price was 100 SEK for item.
{
"contact": {
"matchKey": "example@example.com",
"matchKeyType": "email"
},
"orderStatus": "PENDING",
"paymentStatus": "PENDING",
"orderNumber": "435453437",
"createdDate": "2019-05-06T09:20:11.0412318+02:00",
"shippingDate": "2019-05-13T09:20:11.0412318+02:00",
"statusChangedDate": "2019-05-06T09:20:11.0412318+02:00",
"storeId": "1234",
"currency": "SEK",
"language": "sv",
"extraData": {
"foo": "bar"
},
"totalGrossPrice": 200.01,
"totalTax":39.99,
"items": [
{
"type": "PURCHASE",
"sku": "df07d70e-1",
"quantity": 1,
"grossPaidPrice": 66.67,
"taxAmount": 13.33,
"taxPercent": 25,
"description": "Item One",
"imageUrl": "http://some.image.example.com",
"targetUrl": "http://some.target.example.com",
"extraData": {
"foo": "bar"
},
"discounts": [
{
"value": -33.33,
"type": "3 for 2",
"description": "3 for 2 campaign"
}
]
},
{
"type": "PURCHASE",
"sku": "df07d70e-2",
"quantity": 1,
"grossPaidPrice": 66.67,
"taxAmount": 13.33,
"taxPercent": 25,
"description": "Item Two",
"imageUrl": "http://some.image.example.com",
"targetUrl": "http://some.target.example.com",
"extraData": {
"foo": "bar"
},
"discounts": [
{
"value": -33.33,
"type": "3 for 2",
"description": "3 for 2 campaign"
}
]
},
{
"type": "PURCHASE",
"sku": "df07d70e-3",
"quantity": 1,
"grossPaidPrice": 66.67,
"taxAmount": 13.33,
"taxPercent": 25,
"description": "Item Three",
"imageUrl": "http://some.image.example.com",
"targetUrl": "http://some.target.example.com",
"extraData": {
"foo": "bar"
},
"discounts": [
{
"value": -33.33,
"type": "3 for 2",
"description": "3 for 2 campaign"
}
]
}
]
}