How to configure Voyado

Introducing Voyado

Voyado is a marketing automation platform with CRM and loyalty program features.

Integrating Centra with Voyado enables multiple useful exchanges of data between the systems, including:

  • Sending Customer data from Centra to Voyado to maintain a 360 degree customer view in Voyado
  • Sending Order data from Centra to Voyado, to be used e.g., for segmentation of campaigns
  • Triggering certain transactional emails to be sent by Voyado
    Please note: At the time of writing, it is not possible to transfer Customer data from Voyado into Centra.

Integration options

There are two principle ways of creating an integration between Centra and Voyado:

  1. Build a custom integration, connecting Centra and Voyado in the exact way that is needed to support your business, potentially also involving 3rd party systems (e.g., PoS, loyalty program, ERP, additional CRM, …)
  2. Use the off-the-shelf Voyado integration plugin available in Centra, enabling quick access to the most common workflows

The off-the-shelf Voyado integration plugin enables the following:

  • Sending Customer data to Voyado during first transaction (Centra does not override information in Voyado)
  • Sending separately newsletter subscription to Voyado
  • Triggering a one time data sync for all data created after a specified date
    • Customer data to Voyado
    • Transfer certain Order data to Voyado
    • Transfer certain Shipment data to Voyado
    • Transfer certain Returns data to Voyado
    • Transfer Newsletter subscriber data to Voyado
  • Marking Voyado promotions as redeemed when an Order is placed in Centra, redeeming a Voyado promotion
    • When the off-the-shelf Voyado integration in Centra is active, a frontend store implementation may submit a Voyado Promotion ID through Centra’s APIs when placing an order
    • Centra redeems promotions in Voyado and logs if the redemption was successful or not in the Order history in Centra (the order process is not blocked by unsuccessful redemption - it is merely logged)
    • The Voyado Promotion ID is stored in Centra and visible on the Order
  • Triggering transactional emails to be sent by Voyado with certain data:
    • Order creation
    • Payment successful
    • Payment failed
    • Shipment
    • Return
A custom integration can easily be deployed on PaaS infrastructure e.g., as a serverless worker, or using your preferred integration framework. When to use a custom integration When to use the off-the-shelf plugin
You want full control over what data is transferred and how the data is transformed The integration flows and features of the off-the-shelf plugin meet all of your needs
You want an integration that is not only simplex point-to-point from Centra to Voyado You are willing to adapt your processes somewhat and/or make some tradeoffs, to have the benefit of a standard integration
The cost associated with building and maintaining a custom integration is not an issue

General assumptions

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

Member Contact transactionalContact
All available customer data at first transaction Newsletter subscription data only e-mail and country. Used mainly for transactional communication with the client
All transactional info
All historical data
  • 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. Note that contacs will only be created if you have that flag registred on the Customer card in Centra, if you dont have that and you still want to create the Contact in Voyado you will have to send ALL. 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.

    The date on the reciept in Voyado will be based on the Shipment Created Date in Centra.

    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.