Skip to main content

Voyado Engage

Magento 2 (e-com)

Caution

This Voyado Engage extension has been developed to work with a default Magento 2 installation. If your Magento 2 implementation has had custom development, Voyado can't guarantee that the extension will work as intended, nor will Voyado be able to support you technically if any issues arise because of this.

Caution

This integration is one-way, meaning that customer and order data are sent only from Magento 2 to Engage and not in the other direction. If you want to support that, you will need to patch and add custom development to this extension.

This Magento extension gives you the foundation for using Voyado Engage as your customer experience platform, enabling you to deliver a more personalized experience to your customers.

You can always adapt and adjust the extension to support your customer journey even more than is shown here with the hep of your development team/agency.

3.3.0, 2022-12-19
-----------------
- Ticket #146957: load product for specific store to have the correct URLs generated.
- Ticket #146950: export complete address in order contact attributes.
- Ticket #147243: don't let an empty default tracking url break the code.
- Ticket #146987: set store ID in promotion / voucher message to redeem in correct Voyado account.
- Ticket #138806: default to an empty string instead of 'f' when gender in Magento is empty.
- Ticket #147245: for the credit receipt, take the created date from the credit memo.
- Ticket #146720: only send accepts email, others are handled by Voyado internally.
- Ticket #146864: reset cached subscriber if another one must be loaded.

3.2.1, 2022-11-15
-----------------
- Ticket #145753: add shipping costs incl. tax to the order header.

3.2.0, 2022-11-09
-----------------
- Ticket #145753: add refunded shipping tax to the total_tax and improve logic to detemine refunded quantity.

3.1.0, 2022-11-02
-----------------
- Ticket #144186: use a delay before sending create customer calls to Voyado.
- Ticket #143416: load customer from quote if it isn't in the session (for use with GraphQL).
- Ticket #145317: take the freigth fee from the credit memo as refunding it is optional and add refunded freight fee in credit memo receipt.
- Ticket #143417: add URL to Magento Shipping Track page with configurable tracking information in the order body.
- Ticket #145692: always load orders and creditmemos from database to prevent using cached data (as happens with get() ).

3.0.1, 2022-09-20
-----------------
- Ticket #143105: show contact attributes in log entry as normal array.

3.0.0, 2022-08-25
-----------------
- Ticket #132642: only send cart rule to Voyado if it has been changed.
- Ticket #140836: support per store view API endpoint. Each queue message holds the store ID to be used.
- Ticket #140654: fix deletion of customers in Voyado and always set contact type for customers to a member.
- Ticket #130611: support multiple voucher codes using module amasty/coupons.

2.3.0, 2022-07-26
-----------------
- Ticket #138807: Send the export receipt at all times regardless of whether the order can be exported.

2.2.0, 2022-07-12
-----------------
- Ticket #138099: load customer with email and for it's own store to check subscription.
- Ticket #140192: cast order store ID to int to avoid strict errors.
- Ticket #138658: support Magento 2.4.4 and PHP 8.1

2.1.0, 2022-06-03
-----------------
- Ticket #137498: add configuration to redeem after invoicing or after placing the order.
- Ticket #137573: support extra_data for customers which is extendable with an after plugin.

2.0.1, 2022-03-09
-----------------
- No ticket. Cast customer ID to required type int.

2.0.0, 2022-03-03
-----------------
- Ticket #125852: support Voyado promotions.
- Ticket #126019: support Voyado vouchers.
- Ticket #127419: export company and shipping customer name to Voyado.
- Ticket #128392: keep current contactType when subscribing a customer to a newsletter.
- Ticket #129665: support Magento commerce feature 'Giftwrap'.
- Ticket #130181: set optional consents in the contact attributes.
- Ticket #132775: Avoid duplicate api calls to Voyado.

1.0.2, 2021-09-15
-----------------
- Ticket #125197: product ID could be a string, remove strict type.

1.0.1, 2021-08-27
-----------------
- Ticket #11857: fix typo in module registration.

1.0.0, 2021-08-25
-----------------
- Ticket #118857: initial version.

Prerequisites

Voyado Engage

You need an active Voyado Engage license. You also need an API key to access the API from Magento.

Magento

You need an active license on Magento 2.4.4 or higher.

RabbitMQ

You need to install RabbitMQ both for logging the requests made to Engage as well as the errors received.

Extension & SDK

You will need an agreement with Voyado giving the right to use the Magento Extension and SDK. You will also at this time receive access to download the extension and SDK.

Capabilities

Contacts

Integration 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.

magento1.png

magento2.png
{
    "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": [],
}
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.

magento3.png

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.

Magento4.png

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.

magento-shipment-settings-yes.png

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.

magento-shipment-settings-no.png
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.

magento5.png

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.

  1. Navigate to Marketing > Cart price rules in Magento admin and click on Add new rule.

  2. Name the price rule in the field Rule name and set it as active.

    magento6.png
  3. Choose which websites the price rule is valid on.

  4. Choose your customer groups (all of them can be chosen).

    magento7.png
  5. 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.

    magento8.png
  6. A new drop down list will appear after implementing the extension called Voyado type. The Voyado type should be set to Promotion.

  7. 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)

    magento10.png
  8. 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:

  1. Navigate to the promotion in Engage, created by Magento 2.

  2. Tick the box Can be used in store.

  3. 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:

  1. Name the price rule in the field Rule name and set it as active.

    magento11.png
  2. Choose the coupon to be a Specific coupon and tick the Use Auto Generation.

    magento12.png
  3. Set Uses per coupon to 1.

  4. Set the Voyado type to Voucher.

  5. Under Actions set Apply to Voyado voucher and save the cart price rule.

    magento13.png
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.

magento-redemption.png

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.