How to configure Voyado

What is Voyado?

Voyado is a marketing automation platform with CRM and loyality program features. You can set it up as the default mailer in your Centra by following these configuration steps. If you have not signed an agreement with Voyado yet, but would like to use the Voyado plugin, please contact Voyado’s sales department first.

Voyado integration consists of two plugins: Voyado v2 CRM plugin and Voyado E-mail trigger:

  • Voyado v2 (found under category "CRM") - this plugin is used to fully sync your customer data with Voyado and send e-mails on order confirmation, order shipment and returns if needed,
  • Voyado (found under category "E-mail triggers") - this is a mailer plugin which can be used to send e-mails on order confirmation, order shipment and returns.

Depending on your requirements, you can either set up both of them (if you want to fully sync orders data with Voyado) or just the second one (for sending e-mails only). If you choose the full sync option, every time a new order comes in, Centra will check if the customer has a Voyado ID assigned (meaning they are a member in Voyado), and if not found, a new contact of the type specified will be created in Voyado, recording all given consents and triggering appropriate e-mails.

Centra implementation of Voyado supports three types of Voyado clients: member, transactionalContact and contact:

  • member - This is a Voyado client, for which all order details and history is synced with Voyado. You should use this type if you plan to fully use Voyado functionality for analysis and statistics. In that case, you should configure both Voyado plugins and specify member as "Custom transactional contact type" in Voyado v2 plugin, so that new clients are registered as full members. If that client has made orders in the past and create an order after activating Voyado v2 plugin - all previous transactions will be sent to Voyado as well.
  • transactionalContact - This is a Voyado client who does not share order details and history with Voyado, and only uses Voyado to receive e-mails on order confirmation, order shipment and order return. In that case, you should configure Voyado v2 plugin and specify specify "Custom transactional contact type" with the type received from Voyado (for example transactionalContact).
  • contact - This is a Voyado client that is a newsletter subscriber in Centra. If someone only subscribes to newsletter, Centra will send that client as a contact to Voyado, or if the client subscribes to newsletter and places an order - Centra will send that client as a contact and member to Voyado, if set accordingly in the plugin.

Configure your account in Voyado

  1. Add at least one store
    You can add a store in Voyado by browsing to Administration > Stores > Stores. Once configured, it will look similar to this:

  2. Add at least one "Member" contact type
    You can add a contact in Voyado by browsing to Administration > Contacts > New contact. Make sure the type of the contact is "Member" (or "Medlem").

  3. Ask Voyado to add proper order status and payment type tags to your configuration
    This step needs to be done by Voyado. By default we use 3 order statuses: ORDER_CREATED, ORDER_SHIPPED and ORDER_RETURNED, and 3 payment statuses: PENDING, SUCCESS and FAILED.

  4. Ask Voyado to set e-mail address as identifier key in your Voyado setup Part of Voyado configuration is deciding which attribute will be the key identifying a client. You can see which fields are required when you add new clients in Voyado -> Contacts -> New contact. It's important your Voyado account is configured to use e-mail as identifier, same as Centra does.

Setup Voyado v2 plugin in Centra

  1. Log in to your Centra instance, then go to SYSTEM > STORES and select your store,
  2. Add a new Plugin Method, activate it, set the name (e.g. "Voyado"). Select Voyado v2 from under "CRM". Fill in the following fields:

    • Voyado instance domain - e.g. https://company.staging.voyado.com. This is a URL which allows Centra and Voyado communicate, you get this from Voyado,
    • API Key - Enter the API Key you got from Voyado,
    • External store ID - enter the store ID you configured in Voyado. It may be expanded with a {market} parameter (please make sure each such store ID exists in Voyado), for example:
      • example.com
      • example.com/{market}
      • {market}

    If you use {market} in the External store ID, you must select a Default Market in the Store Settings under System -> Stores.

    • Transfer Customers & orders, shipments and returns to Voyado - select Centra type of customer that you want to have sent to Voyado as member type. We have registered and non-registered customers, also you can select only customers that have a Voyado ID sent from the front-end to Centra. The latter option might be helpful if you want to divide clients for those that have Voyado ID and for those that do not, and for latter just send transactional e-mails. If you do not want to send any of those customer types to Voyado, you need to select an option None.
    • Transfer Newsletter subscribers to Voyado - that option is used for sending Centra customer type newsletter subscribers as a contact type to Voyado. You can send both subscribers only and subscribers that made a transaction. In the latter case, two types of contacts will be sent to Voyado for one Centra customer: member and contact, according to the setup above.
    • Transfer historical data to Voyado according to setup - this means that you have the possibility to transfer historical data of your Centra customers to Voyado. Transfer is dependent on the same setup as normal Centra-Voyado data exchange, so Centra will send those customers which you selected in the settings above. That is a one-time action. You can select preferred customers that you want to send and you can select the date from which you want to get an update. You will be able to observe the synchronisation status on the field Synchronisation status (it will have value pending during the synchronisation and synchronised date after it). Important: If any data were changed already in Voyado itself - Centra will not override it.

    Further configuration options are:

    • Custom transactional contact type - with that field you can decide if all of the customers you want to send to Voyado as members (those who have a Voyado ID) or to some you just want to send a transactional email. This is how the end customer is defined in Voyado and determines what type of content/emails should be delivered. That field you can just fill with type:
      • member
      • transactionalContact
      • contact

    This field is case sensitive and should be written exactly as listed above.

    • Send transactional email - After deciding on the contact type you want to have for you unassigned contacts, you can choose whether you want to send transactional emails with Voyado as well. Select Yes if you want to do that.
    • Other configs can be left default for emails. E-mail tags should be also configured in Voyado exactly the same as in Centra.

    Remember to set Send Refund Email: Yes in your store settings if you want to send refund emails.

    • Mailer restrictions - You can restrict your plugin and each setup per additional filters: Pricelist-restrict, Market-restrict and Country-restrict. That means that you can send emails from Voyado only per specific Market/Pricelist/Country. It works the same way as in all other Centra restrictions, you need to select those that you want to use with that plugin. No selections means All.

    If you will enable Voyado with other mailer integration without any restriction or with the restrictions for the same Market/Pricelist/Country, email will be triggered from the fastest mailer.

  3. Save. You've now connected Voyado to Centra!

Testing

Since sending e-mails in Voyado test environment is disabled by default, you need to contact Voyado before you begin your testing. There are two ways they can enable the test e-mails sending for your account:

  • You can ask them to enable e-mail automations for e-mail types: Order Confirmation, Order Shippinig and Refund order. This will allow Voyado to send those e-mails for contacts which are configured with Accepts email: No (which translates to newsletter subscription and is disabled by default).
  • You can also ask Voyado to add your test e-mail to the whitelist of addresses allowed to send e-mails from the test environment. This can only be done by Voyado.

In order to create a Voyado client with Accepts email: Yes, simply add "newsletter": true to customer address when calling POST /payment.

You are required to test all order flows in the QA environment and get approval from both Centra and Voyado before setting up your production environment.

Once both Voyado and the Centra plugin are configured, you can place a test order to see if e-mail sending works as expected. They will be visible on the bottom of the order details page:

If the e-mail failed to trigger, you will see it in red. Expand the details to see the error message. For example, if you did not ask Voyado to add proper tags to your configuration, you may see an error 422 like below:

Voyado POST /orders returned 422: 
{
  "message": "Order is not valid",
  "validationErrors": [
    {
      "validationErrorCode": "InvalidOrderStatus",
      "field": "OrderStatus",
      "errorDescription": "Specified order status 'ORDER_CREATED' in request is not a valid status. Valid statuses are []."
    },
    {
      "validationErrorCode": "InvalidPaymentStatus",
      "field": "PaymentStatus",
      "errorDescription": "Specified payment status 'SUCCESS' in request is not a valid status. Valid statuses are []"
    }
  ]
}

Data Centra sends to Voyado

Transactional e-mails (/orders endpoint)

  1. Order confirmation
    Log: Order details have been sent to Voyado /orders endpoint

Request:

{
    "contact": {
        "matchKey": "xxxx@mail.io",
        "matchKeyType": "email"
    },
    "orderNumber": "2348981",
    "createdDate": "2020-06-16T20:00:58+02:00",
    "orderStatus": "ORDER_CREATED",
    "paymentStatus": "SUCCESS",
    "storeId": "brand.com",
    "currency": "USD",
    "items": [
        {
            "type": "purchase",
            "sku": "113185-L30-W31",
            "quantity": 1,
            "description": "Tight Shirt Blue Ocean",
            "grossPaidPrice": "199.00",
            "imageUrl": "https://brand.centraqa.com/client/dynamic/images/5000_1fbca8f904-113185_01_tight_shirt_blue_ocean.jpg",
            "targetUrl": "",
            "taxAmount": "0.00",
            "taxPercent": "0.00",
            "extraData": {
                "size": "W31/L30",
                "variation": "",
                "isSale": false, // COMMENT: The logic was to add a true/false if an item was sold on sale. That is decided based on the prices: if “grossPaidPricePerUnit” differs from “originalUnitPrice” than we send “true”
            },
            "discounts": [],
            "grossPaidPricePerUnit": "199.00",
            "originalPrice": "199.00",
            "originalPricePerUnit": "199.00",
            "discounted": false
        }
    ],
    "exchangeRateToGroupCurrency": 9.3657699999999995,
    "freightFee": {
        "value": "0.00",
        "tax": "0.00"
    },
    "handlingFee": {
        "value": "0.00",
        "tax": "0.00"
    },
    "paymentMethods": [
        {
            "type": "Free",
            "description": "N/A",
            "value": "199.00"
        }
    ],
    "extraData": {
        "billingAddressFirstName": "Tax",
        "billingAddressLastName": "Tax",
        "billingAddressStreet": "Tax",
        "billingAddressStreet2": "",
        "billingAddressCity": "Atherton",
        "billingAddressPostalCode": "0427",
        "billingAddressCountry": "United States",
        "billingAddressState": "",
        "billingTelephoneNumber": "", // COMMENT: If the format is wrong, we send an error to FE and than repeat the call without phone number 
        "shippingAddressFirstName": "Tax",
        "shippingAddressLastName": "Tax",
        "shippingAddressStreet": "Tax",
        "shippingAddressStreet2": "",
        "shippingAddressCity": "Atherton",
        "shippingAddressPostalCode": "0427",
        "shippingAddressCountry": "United States",
        "shippingAddressState": "CA",
        "shippingMethod": "UPS Express Saver",
        "trackingNumber": "",
        "trackingLinkHTML": "",
        "customerNumber": "759860",
        "taxDeduction": "0.00",
        "orderPlaced": "2020-06-16 20:00:58",
        "methodForPayemnt": "Klarna"
    },
    "taxDetails": [],
    "totalOriginalPrice": "199.00",
    "totalGrossPrice": "199.00", // COMMENT: totalGrossPrice on the return is the total value of the whole return, it includes the sum of gross prices from all the items in the return 
    "totalItemsPrice": "199.00",
    "anyReturnItems": false
}

Expected response code: 202.

  1. Shipping confirmation
    Log: Order details have been sent to Voyado /orders endpoint

Request:

{
    "contact": {
        "matchKey": "ingridSE0609@nj.io",
        "matchKeyType": "email"
    },
    "orderNumber": "2348955",
    "createdDate": "2020-06-09T09:42:26+02:00",
    "orderStatus": "ORDER_SHIPPED",
    "paymentStatus": "SUCCESS",
    "storeId": "nudiejeans.com",
    "currency": "SEK",
    "items": [
        {
            "type": "purchase",
            "sku": "113128-L32-W32",
            "quantity": 1,
            "description": "Steady Eddie II Dry Ace Selvage",
            "grossPaidPrice": "2999.00",
            "imageUrl": "https://nudie.centraqa.com/client/dynamic/images/4787_448971040a-113128_01_steady_eddie_ii_dry_ace_selvage.jpg",
            "targetUrl": "",
            "taxAmount": "599.80",
            "taxPercent": "25.00",
            "extraData": {
                "size": "W32/L32",
                "variation": "",
                "isSale": false
            },
            "discounts": [],
            "grossPaidPricePerUnit": "2999.00",
            "originalPrice": "2999.00",
            "originalPricePerUnit": "2999.00",
            "discounted": false
        }
    ],
    "exchangeRateToGroupCurrency": 1,
    "freightFee": {
        "value": "0.00",
        "tax": "0.00"
    },
    "handlingFee": {
        "value": "0.00",
        "tax": "0.00"
    },
    "paymentMethods": [
        {
            "type": "Credit Card",
            "description": "N/A",
            "value": "2999.00"
        }
    ],
    "extraData": {
        "billingAddressFirstName": "Ingrid",
        "billingAddressLastName": "Budbee",
        "billingAddressStreet": "Majorsgatan 4",
        "billingAddressStreet2": "",
        "billingAddressCity": "Göteborg",
        "billingAddressPostalCode": "41308",
        "billingAddressCountry": "Sweden",
        "billingAddressState": "",
        "billingTelephoneNumber": "+46707881719",
        "shippingAddressFirstName": "Ingrid",
        "shippingAddressLastName": "Budbee",
        "shippingAddressStreet": "Majorsgatan 4",
        "shippingAddressStreet2": "",
        "shippingAddressCity": "Göteborg",
        "shippingAddressPostalCode": "41308",
        "shippingAddressCountry": "Sweden",
        "shippingAddressState": "",
        "shippingMethod": "Hemleverans kl. 17-22",
        "trackingNumber": "",
        "trackingLinkHTML": "https://www.nudiejeans.com/budbee/",
        "customerNumber": "759844",
        "taxDeduction": "0.00",
        "orderPlaced": "2020-06-09 09:42:26",
        "paymentMethodName": "Klarna"
    },
    "taxDetails": [
        {
            "description": "25%",
            "value": "599.80"
        }
    ],
    "totalOriginalPrice": "2999.00",
    "totalGrossPrice": "2999.00",
    "totalItemsPrice": "2999.00",
    "anyReturnItems": false,
    "shippingDate": "2020-06-09T11:10:03+02:00"
}

Expected response code: 202.

  1. Returns
    Log: Order details have been sent to Voyado /orders endpoint

Request:

{
    "contact": {
        "matchKey": "noretfreight@nj.io",
        "matchKeyType": "email"
    },
    "orderNumber": "2348855",
    "createdDate": "2020-05-18T15:22:22+02:00",
    "orderStatus": "ORDER_RETURNED",
    "paymentStatus": "SUCCESS",
    "storeId": "nudiejeans.com",
    "currency": "EUR",
    "items": [
        {
            "type": "purchase",
            "sku": "170232-B21-002",
            "quantity": 1,
            "description": "Boxers Chambray Indigo",
            "grossPaidPrice": "29.00",
            "imageUrl": "https://nudie.centraqa.com/client/dynamic/images/1219_dd0dbe9fac-170232b21-01-boxers-chambray-indigo.jpg",
            "targetUrl": "",
            "taxAmount": "5.03",
            "taxPercent": "21.00",
            "extraData": {
                "size": "Medium",
                "variation": "Indigo",
                "isSale": false
            },
            "discounts": [],
            "grossPaidPricePerUnit": "29.00",
            "originalPrice": "29.00",
            "originalPricePerUnit": "29.00",
            "discounted": false
        }
    ],
    "exchangeRateToGroupCurrency": 10.610300000000001,
    "freightFee": {
        "value": "0.00",
        "tax": "0.00"
    },
    "handlingFee": {
        "value": "-10.00",
        "tax": "-1.74"
    },
    "paymentMethods": [],
    "extraData": {
        "billingAddressFirstName": "Noret",
        "billingAddressLastName": "Freight",
        "billingAddressStreet": "calle bailen",
        "billingAddressStreet2": "",
        "billingAddressCity": "Barcelona",
        "billingAddressPostalCode": "HSI12",
        "billingAddressCountry": "Spain",
        "billingAddressState": "",
        "billingTelephoneNumber": "+34708845456",
        "shippingAddressFirstName": "Noret",
        "shippingAddressLastName": "Freight",
        "shippingAddressStreet": "calle bailen",
        "shippingAddressStreet2": "",
        "shippingAddressCity": "Barcelona",
        "shippingAddressPostalCode": "HSI12",
        "shippingAddressCountry": "Spain",
        "shippingAddressState": "",
        "shippingMethod": "UPS Standard",
        "trackingNumber": "",
        "trackingLinkHTML": "",
        "customerNumber": "759815",
        "taxDeduction": "0.00",
        "orderPlaced": "2020-05-18 15:22:22"
    },
    "taxDetails": [
        {
            "description": "21%",
            "value": "3.30"
        }
    ],
    "totalOriginalPrice": "29.00",
    "totalGrossPrice": "19.00", // COMMENT: totalGrossPrice on the return is the total value of the whole return, it includes the sum of gross prices from all the items in the return
    "totalItemsPrice": "29.00",
    "anyReturnItems": true,
    "shippingDate": "2020-05-19T11:41:02+02:00"
}

Expected response code: 202.

Full members' data sync (/receipts endpoint)

  1. Order creation
    Log: 'Receipt for order 192 has been sent to Voyado and returned with code 202'

Request:

{
    "contact": {
        "matchKey": "fd927adf-f4e0-4737-8fbe-abf900adce2c",
        "matchKeyType": "contactId"
    },
    "uniqueReceiptId": "189-1", // COMMENT: ”Order ID - delivery appendix”
    "receiptNumber": "189-1",
    "createdDate": "2020-07-24T09:17:15+02:00",
    "storeExternalId": "centra.com",
    "currency": "SEK",
    "exchangeRateToGroupCurrency": 1,
    "totalGrossPrice": "2.00",
    "taxDetails": [
        {
            "description": "25%",
            "value": "0.40"
        }
    ],
    "paymentMethods": [
        {
            "type": "Credit Card",
            "description": "N/A",
            "value": "2.00"
        }
    ],
    "items": [
        {
            "type": "purchase",
            "quantity": 1,
            "grossPaidPrice": "2.00",
            "taxAmount": "0.40",
            "taxPercent": 25,
            "sku": "TEST-DISC456789",
            "articleNumber": "TEST-DISC",
            "articleName": "Test Product Discounted",
            "articleGroup": "shop",
            "extraData": [
                {
                    "name": "size",
                    "value": ""
                },
                {
                    "name": "variation",
                    "value": "Red"
                },
                {
                    "name": "isSale",
                    "value": true
                }
            ],
            "discounts": [
                {
                    "type": "Discount",
                    "description": "Discount",
                    "value": "-198.00"
                }
            ]
        }
    ]
}

Expected response code: 202.

  1. Return creation
    Log: 'Receipt for return id 10 for order 189 has been sent to Voyado and returned with code 202'

Request:

{
    "contact": {
        "matchKey": "fd927adf-f4e0-4737-8fbe-abf900adce2c",
        "matchKeyType": "contactId"
    },
    "uniqueReceiptId": "189-1-10", // COMMENT: ”Order ID - delivery appendix - return ID”
    "receiptNumber": "189-1-10",
    "createdDate": "2020-07-24T09:19:41+02:00",
    "storeExternalId": "centra.com",
    "currency": "SEK",
    "exchangeRateToGroupCurrency": 1,
    "totalGrossPrice": "-2.00",
    "taxDetails": [
        {
            "description": "25%",
            "value": "0.40"
        }
    ],
    "paymentMethods": [
        {
            "type": "Credit Card",
            "description": "N/A",
            "value": "-2.00"
        }
    ],
    "items": [
        {
            "type": "return",
            "quantity": -1,
            "grossPaidPrice": "2.00",
            "taxAmount": "0.40",
            "taxPercent": 25,
            "sku": "TEST-DISC456789",
            "articleNumber": "TEST-DISC",
            "articleName": "Test Product Discounted",
            "articleGroup": "shop",
            "extraData": [
                {
                    "name": "size",
                    "value": ""
                },
                {
                    "name": "variation",
                    "value": "Red"
                },
                {
                    "name": "isSale",
                    "value": true
                }
            ],
            "discounts": [
                {
                    "type": "Discount",
                    "description": "Discount",
                    "value": "-198.00"
                }
            ]
        }
    ]
}

Expected response code: 202.