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. For doing that, 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 since it can exist within multiple contact types. The other recommended attribute is mobilePhone. The endpoint used is:
{
"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-SE",
"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": "3 for the price of 4",
"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 act as an input condition for starting a specific automation 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-SE",
"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 each.
{
"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-SE",
"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 för 2",
"description": "3 för 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 för 2",
"description": "3 för 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 för 2",
"description": "3 för 2 campaign"
}
]
}
]
}