How to configure Voyado

Last updated April 15th at 9:55am

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:

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, …)
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
- Order cancellation
- Forgotten password

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, gender 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

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

Log in to your Centra instance, then go to 'System' > 'Stores' in the main menu to the left and select your store
Add a new plugin method by clicking '+Add 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 - This can be used for segmentation purposes within Voyado. You can segment into a single store in Voyado or alternatively expand the segmentation further with the use of market or country parameters. See more details below for each of the three options:
  - Single store segmentation - Insert any value that matches the value in the External Store ID in the equivalent Voyado store. For example, you can insert the name of your Voyado tenant, such as ‘centra.com’. This ensures all transactions are mapped towards a single store in Voyado.
  - Market segmentation - Use the market parameter to ensure transactions are mapped to a Voyado store that has the ‘External Store ID’ field specified as a Centra market. Note that in Voyado the market should be the exact name of the Market set up in Centra. This can be set up in one of the three following ways:
    - {market} - assigns transactions to respective stores in Voyado based on Markets set up in Centra. For example: transactions from ‘Market A’ are assigned to Store A in Voyado, whereas transactions from ‘Market B’ are assigned to Store B in Voyado
    - centra.com/Europe - in this example we use the hardcoded value ‘Europe’, which results in all transactions being mapped to a Voyado store ID with ‘External store ID’ called ‘Europe‘
    - Europe - same as above
  If you use {market} in the External store ID, you must select a Default Market in the Store Settings under System -> Stores.
- Country segmentation - Use the country parameter to ensure transactions are mapped to a Voyado store that has the ‘External Store ID’ field specified as this country. Note that the Shipping country is used for transactional emails. Alternatively, if the customer was just created (i.e. through newsletter sign-up) and there are no orders placed by them, the Billing country is used instead. For example, an order with ‘Shipping country:Sweden’ is mapped to Voyado with ‘External store ID’ set as ‘Sweden’ . This can be set up in one of the three following ways:
  - {country} - assigns transactions to respective stores in Voyado based on countries. For example: transactions from country ‘Norway’ are assigned to Store ‘Norway’ in Voyado, whereas transactions from ‘Sweden’ are assigned to Store ‘Sweden’ in Voyado and so on
  - centra.com/Sweden - in this example we use the hardcoded value ‘Sweden’, which results in all transactions being mapped to a Voyado store ID with ‘External store ID’ called ‘Sweden‘
  - Sweden - same as above
Note that when hardcoded values are used with the {market} or {country} options, the content seen in the ‘External store ID’ field in Centra should match 100% with its equivalent on Voyado’s side.

The External store ID is passed to Voyado when a customer is created either through Centra or APIs, even if no order is placed. This happens for both members and contacts.
- 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.
Click '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