Using the extension
This is how to use the Magento 2 - Engage extension.
Contacts
This integration with Engage supports the sync of customers (Members), guests (e-com customers) and Newsletter subscribers.
These contact types are captured in Magento and exported to Engage via the extension. Depending on contact type you will be able to import transactional data and personal details. The data you import allow you to build segments and communicate with your contacts in a highly personalized way.
Each customer type can be individually toggled on/off.
{
"consents": [],
"contactType": "member",
"email": "john.doe@voyado.com",
"externalId": "10",
"firstName": "John",
"gender": "",
"lastName": "Doe",
"preferences": {
"acceptsEmail": true,
"acceptsPostal": true,
"acceptsSms": true
}
}{
"city": "Stockholm",
"contactType": "member",
"countryCode": "SE",
"email": "john.doe@voyado.com",
"externalId": "10",
"firstName": "John",
"gender": "M",
"lastName": "Doe",
"street": "Janes street 12",
"zipCode": "151 51"
"preferences": {
"acceptsEmail": true,
"acceptsPostal": true,
"acceptsSms": true
},
"consents": [],
}Capabilities
Receipts
You can sync your customers purchases and refunds and act on them in Engage – and use that information for segmentation to personalize your communication and to predict churn.
The purchases (invoices) and returns (credit memos) are synced to both customers and guests.
Each receipt type can be individually toggled on/off.
A purchase receipt will be synced to Engage when the order is set to Invoiced in Magento and a return receipt will be synced when a Credit memo is booked on the order.
{
"contact": {
"contactType": "member",
"matchKey": "f0352103-7143-4a44-a20d-af3300c58d7f",
"matchKeyType": "ContactId"
},
"createdDate": "2022-11-08T12:49:43+00:00",
"createdDateForXml": "2022-11-08T12:49:43+00:00",
"currency": "EUR",
"items": [
{
"articleName": "Joust Duffle Bag",
"articleNumber": "24-MB01",
"awardsBonus": true,
"extraData": [],
"grossPaidPrice": 85,
"quantity": 2,
"sku": "24-MB01",
"taxAmount": "17.0000",
"taxPercent": "25.0000",
"type": "PURCHASE"
}
],
"paymentMethods": [
{
"description": "Payment for: 000000034",
"type": "checkmo",
"value": 85
}
],
"receiptNumber": "000000034",
"storeExternalId": "opensource_demostore",
"taxDetails": {
"description": "TAX",
"percent": "25.0000",
"totalExcludingTax": 68,
"totalIncludingTax": 85,
"value": "19.5000"
},
"totalGrossPrice": 85,
"uniqueReceiptId": "000000034"
}{
"contact": {
"contactType": "member",
"matchKey": "f0352103-7143-4a44-a20d-af3300c58d7f",
"matchKeyType": "ContactId"
},
"createdDate": "2022-11-08T12:49:43+00:00",
"createdDateForXml": "2022-11-08T12:49:43+00:00",
"currency": "EUR",
"items": [
{
"articleName": "Joust Duffle Bag",
"articleNumber": "24-MB01",
"awardsBonus": true,
"extraData": [],
"grossPaidPrice": 42.5,
"quantity": -1,
"sku": "24-MB01",
"taxAmount": "8.5000",
"taxPercent": "25.0000",
"type": "RETURN"
}
],
"paymentMethods": [
{
"description": "Refund payment for: 000000034",
"type": "Refund",
"value": -42.5
}
],
"receiptNumber": "000000034",
"storeExternalId": "opensource_demostore",
"taxDetails": {
"description": "TAX",
"totalExcludingTax": 34,
"totalIncludingTax": 42.5,
"value": "8.5000"
},
"totalGrossPrice": -42.5,
"uniqueReceiptId": "34-20"
}Order communication
Trigger communication based on the following order statuses ”out of the box”. The extension allows you send transactional emails on the different order states below:
Order confirmed
Order shipped
Order cancelled
Order returned (triggered when a credit memo is registered)
Each order status can be individually toggled on/off.
Status “Pending” connects to an order confirmation
Status “Processing” connects to an order that has been shipped
Status “Complete” connects to an order that has been invoiced
Status “Canceled” connects to an order that has been canceled
Transactional communication data
Below you can see the "out of the box" data included in the transactional emails:
{
"contact": {
"matchKey": "f0352103-7143-4a44-a20d-af3300c58d7f",
"matchKeyType": "ContactId"
},
"createdDate": "2022-10-19T12:02:20+00:00",
"currency": "EUR",
"extraData": {
"billing_city": "Stockholm",
"billing_company": null,
"billing_country": "SE",
"billing_street": "Test 1",
"billing_zipcode": "702 81",
"customer_firstname": "Jane",
"customer_lastname": "Doe",
"customer_middlename": null,
"customer_telephonenumber": "+46111111111",
"payment_method": "Check / Money order",
"shipping_amount": 10,
"shipping_city": "Stockholm",
"shipping_company": null,
"shipping_country": "SE",
"shipping_description": "Flat Rate - Fixed",
"shipping_firstname": "Jane",
"shipping_lastname": "Doe",
"shipping_method": "Flat Rate - Fixed",
"shipping_middlename": null,
"shipping_street": "Test 1",
"shipping_telephonenumber": "+46111111111",
"shipping_track_number": "12345",
"shipping_track_url": "https://voyadotracking.se/",
"shipping_track": "https://voyado-demo-com.test.xsarus.net/shipping/tracking/popup?hash=b3JkZXJfaWQ6NDpiODAzN2QzNTMwMTk0MWI5ZTAxOGU5NDcxMjkzOTQ2MA%2C%2C",
"shipping_zipcode": "702 81",
"website_code": "1"
},
"freightFee": {
"value": "10.0000"
},
"handlingFee": {
"value": 0
},
"items": [
{
"description": "Montana Wind Jacket",
"extraData": {
"description": "Montana Wind Jacket"
},
"grossPaidPrice": 49,
"imageUrl": "https://voyado-demo-com.test.xsarus.net/media/catalog/product/cache/6459e7a90b650d887389432cc6b6dc3f/m/j/mj03-black_main_1.jpg",
"quantity": "1.0000",
"sku": "MJ03-S-Green",
"targetUrl": "https://voyado-demo-com.test.xsarus.net/montana-wind-jacket.html",
"taxAmount": "0.0000",
"taxPercent": "0.0000",
"type": "PURCHASE"
},
{
"description": "Jupiter All-Weather Trainer ",
"extraData": {
"description": "Jupiter All-Weather Trainer "
},
"grossPaidPrice": 56.99,
"imageUrl": "https://voyado-demo-com.test.xsarus.net/media/catalog/product/cache/6459e7a90b650d887389432cc6b6dc3f/m/j/mj06-blue_main_1.jpg",
"quantity": "1.0000",
"sku": "MJ06-S-Blue",
"targetUrl": "https://voyado-demo-com.test.xsarus.net/jupiter-all-weather-trainer.html",
"taxAmount": "0.0000",
"taxPercent": "0.0000",
"type": "PURCHASE"
}
],
"language": "en-US",
"orderNumber": "000000004",
"orderStatus": "processing",
"paymentMethods": [
{
"description": "Payment for: 000000004",
"type": "checkmo",
"value": 115.99
}
],
"paymentStatus": "Reserved",
"storeId": "demostore",
"totalDiscounts": 0,
"totalGrossPrice": 115.99,
"totalItemsPrice": 105.99,
"totalNetPrice": "115.9900",
"totalOriginalPrice": "115.9900",
"totalTax": 0
}If you want to extend the order payload with the additional product attributes in Magento, follow the instructions in the README.md file in Gitlab under the section "Extending".
If you don't have access to the file on Gitlab, try this article.
Shipment settings
Setting this option to “Yes” will add the default tracking link provided by Magento.
Setting this option to “No” will allow you to add your transporter's tracking URL. When the transactional email is sent, the first tracking number found will be added to the URL and sent in the payload.
Soft identification
When you send a newsletter or email with a link to your customers in Engage, the links are encrypted with a contact identifier.
The extension decrypts the link when a customer clicks on it and you can choose to automatically push the identifier to front-end (dataLayer) and use it for various actions, such as triggering abandoned carts or product views through Engage's tracking script, or personalize the experience on-site since Engage knows who the visitor is.
This functionality can be toggled on/off.
The Decryption Key, 32 characters long, is configured in the Engage backoffice. Ask your Voyado team to get it.
Assign personal promotions through Engage
When the extension is implemented you will be able to assign personal discounts in Engage and enable the end-consumer to apply the discount in checkout. Once it has been applied and the purchase is made, the extension will automatically redeem the promotion in Engage so that it can’t be used again.
The master of the price logic is Magento and it should always be created in Magento Admin first under the section “Cart price rule”. Once it is created with the correct settings (explained further down), a promotion will automatically be created as a Draft in Voyado with the correct reference code.
How do I create a cart price rule connected to Voyado Engage?
The example below demonstrates how to generate a 20% off welcoming offer.
Navigate to Marketing > Cart price rules in Magento admin and click on Add new rule.
Name the price rule in the field Rule name and set it as active.
Choose which websites the price rule is valid on.
Choose your customer groups (all of them can be chosen).
Choose the coupon to be a Specific coupon and enter the coupon code. The coupon code is the key reference between the promotion in Voyado and the Cart price rule in Magento. The coupon code will also be the code to communicate to the customers by email or SMS.
A new drop down list will appear after implementing the extension called Voyado type. The Voyado type should be set to Promotion.
Finally you can set the rules for the discount. A promotion in Engage can be connected to the four different rules below:
Percent of product price discount
Fixed amount discount
Fixed amount discount for whole cart
Buy X get Y for free (discount amount is Y)
After setting up the rules click Save and the promotion will be created in Engage as a draft and from there you can choose to assign the discount to your customer segment either manually or through our marketing automation platform.
How is the discount applied in checkout?
What the extension supports “out of the box” is that the end-consumer has to input the code, which has been communicated to them by email or sms, manually in the discount code field in checkout. This will automatically apply the discount value to the basket.
If you, for example, want to present all available promotions to the end-consumer where they can choose, just by clicking, which promotion to use then this will require front-end development in order to connect the dots.
Combining promotions online & offline
Since a promotion is automatically created in Engage when creating a Cart price rule in Magento 2, you can choose that promotion to also be valid in store (POS).
Following the steps below will enable a promotion to be used in store:
Navigate to the promotion in Engage, created by Magento 2.
Tick the box Can be used in store.
Choose the type of promotion: Monetary discount, Discount in percent or External promotion code and enter the value of the discount.
Note
This requires you to have an integration towards the POS that supports multichannel promotion assignment in Engage. The type of promotion may vary depending on the integration towards the POS.
Reward vouchers in checkout
The extension enables the end-consumer to apply a reward voucher as a discount in checkout. A reward voucher is a monetary discount converted from X amount of points earned by the consumer.
The voucher is also connected to a “Cart price rule” in Magento but of a different type.
As a client you will have to create ONE master template that will be connected to the vouchers in Voyado. Once the extension has identified the existing customer in Engage it will automatically enable the usage of their available vouchers.
How do I create a Cart price rule connected to the Reward vouchers?
Note
You are only required to create this Cart price rule once and have it active as a master template. The extension handles the rest.
Follow the steps below:
Name the price rule in the field Rule name and set it as active.
Choose the coupon to be a Specific coupon and tick the Use Auto Generation.
Set Uses per coupon to 1.
Set the Voyado type to Voucher.
Under Actions set Apply to Voyado voucher and save the cart price rule.
How is the voucher applied in the checkout?
What the extension supports “out of the box” is that the end-consumer has to input the checknumber, which has been communicated to them by email or sms, manually in the discount code field in checkout. This will automatically apply the monetary voucher value as a discount to the basket.
Once the purchase in finalized, the extension will redeem the voucher in Engage so that it cannot be used again in other channels.
If you want to present all available vouchers to the end-consumer where they can choose, just by clicking, which voucher to apply to the purchase then this will require front-end development in order to connect the dots.
Redeeming a promotion / voucher
This setting allows you to decide at what stage in a purchase a promotion / voucher is redeemed in Engage.
The options are:
Redeem when the order has been fulfilled ("Invoice")
Redeem at the order confirmation stage ("Order")
If the order is not initially booked as an invoice in Magento admin, you should choose the option “Order” as in the image. This will redeem the promotion / voucher as soon as the order has been submitted.