Skip to main content

Voyado Engage

Triggering purchase and return order flows

Purchase

In this example the purchase is matched to the contact with the attribute email, which is a recommended attribute since it can exist within multiple contact types. The attributes recommended to use are: email, mobilephone.

Endpoint/api/v2/orders

{
    "contact": {
        "matchKey": "your@email.com",
        "matchKeyType": "email"
    },
    "orderStatus": "Order_Confirmation",
    "paymentStatus": "Confirmed",
    "orderNumber": "435453435",
    "createdDate": "2021-06-22T15:55:54Z",
    "shippingDate": "2021-06-23T15:55:54Z",
    "statusChangedDate": "2021-06-23T15:55:54Z",
    "storeId": "1234",
    "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": "Sven",
        "ShippingAddressLastName": "Svensson",
        "ShippingAddressStreet": "Storgatan 1",
        "ShippingAddressZipCode": "111 22",
        "ShippingAddressCity": "Staden",
        "ShippingAddressCountry": "Sverige",
        "ShippingAddressPhone": "0707-11 22 33",
        "ShippingAddressEmail": "name@domain.com",
        "PaymentMethod": "Klarna",
        "BillingAddressFirstName": "Sven",
        "BillingAddressLastName": "Svensson",
        "BillingAddressStreet": "Storgatan 1",
        "BillingAddressZipCode": "111 22",
        "BillingAddressCity": "Staden",
        "BillingAddressCountry": "Sverige",
        "BillingAddressPhone": "0707-11 22 33",
        "BillingAddressEmail": "name@domain.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 needs to be negative.

When one or more line items are defined as “type” Return, the field “IncludesReturns” will automatically be set to true and can act as an input condition for starting a specific automation flow in Voyado.

{
    "contact": {
        "matchKey": "john.doe@voyado.com",
        "matchKeyType": "email"
    },
    "orderStatus": "RETURN",
    "paymentStatus": "CONFIRMED",
    "orderNumber": "435453435",
    "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": "john.doe@voyado.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"
        }
      ]
    }
  ]
}