Voyado

The Voyado integration supports the following

• Synchronization of customers
  • One-way sync (Omnium as Master)
  • Two-way sync
• Export of receipts
  • Order receipts
  • Return receipts
  • Receipt enrichment (from product data)
• Promotions/Personal offers

Customers

Mapping Options

Contact types

The Omnium-Voyado integration provides several options for customizing the sync of customers to Voyado. In Voyado Engage there is the concept of contact-types, which separates between Contacts and Members. This is somewhat analogous to the separation between customers and customer club members in Omnium. In the default setup, this separation is mirrored between Omnium and Voyado, mapping PrivateCustomers to Voyado-Contacts and CustomerClubMembers to Voyado Members. However, depending on the use case, different customers might require different behaviors. The Omnium-Voyado integration supports several options for this flow.

Other options

Sync of customers from Omnium to Voyado

Sync of customers from Omnium to Voyado is done synchronously every time a customer is updated in Omnium. This is done by setting up the VoyadoExporter to implement IPrivateCustomerExporter, which creates a client exporting contacts to the Voyado Engage API. To relate customers in Omnium and Contacts in Voyado, Omnium stores the Voyado ContactId as an externalId on the private customer object in Omnium. Should the export of a customer fail, an error message will be displayed on the customer card in Omnium, with the option to inspect the error message returned from the Voyado Engage API.

The following table shows the various operations used in syncing data from Omnium to Voyado.

Sync of customers from Voyado to Omnium

Sync of customers from Voyado to Omnium is performed asynchronously by polling the endpoint /api/v2/contacts/changes in the Voyado Engage API at regular intervals. This process is configured through the scheduled task VoyadoContactSync, where you can specify the frequency of the polls. The minimum allowed interval is once every minute.

Receipts

Export of both order and return receipts from Omnium to Voyado can be configured through workflow steps in Omnium. As receipts in Voyado cannot be altered once created, it is recommended that the export of order receipts is always set up at the very end of an order's workflow.

Receipt enrichment

Transaction objects (receipts) that are exported to Voyado are lightweight objects with limited information on the products sold. It is possible to enrich the receipts by exporting product data from Omnium to Voyado. This is set up as an XML export that exports information about all products in Omnium to Voyado. The frequency of this export is configurable through the scheduled task VoyadoProductDataExport, but the recommended setting is once a day. The export file conforms to the format specified here: https://developer.voyado.com/resources/Article_enrichment_example.xml

Exclude selected products from receipts

It is possible to exclude selected products from all receipts exported to Voyado. Order lines with custom property ExcludeFromVoyadoReceipts = true will be excluded. This property should be set on products and enriched onto order lines. The enrichment can be configured from Configuration → Orders → Order line under "Enrich order line from products". All properties specified here will be copied from the products onto the corresponding line item on the order.

Multiple Voaydo instances

Omnium supports connecting multiple Voyado instances. To keep track of which Voyado instance an externalId in Omnium belongs to, you can define a connector prefix in the Voyado connector settings.

⚠️ The prefix should be configured during setup and must not be changed once the integration is live.

For a multi-instance setup, the Voyado connectors should also have "EnabledForMarkets" and/or "DisabledForMarkets" configured in Omnium. This ensures that each connector only operates within its intended scope.

If a prefix is specified, the resulting externalIds in Omnium will follow this format:

<ConnectorPrefix>_VoyadoContactId

Store mapping

Store Mapping

By default, Omnium will use the StoreId from an order as the StoreExternalId on a receipt when sending it to Voyado.

However, in cases with multiple Voyado integrations or when the store structure differs between Omnium and Voyado, there might not be a 1-to-1 match between store IDs. To support flexible mapping, you can set an external store ID from Voyado as an externalId on the store entity in Omnium. This ensures that receipts are linked to the correct store in Voyado.

The providerName of the externalId in Omnium should by default be VoyadoExternalStoreId. The id should match the ExternalId of the corresponding store in Voyado.

Example:

{
    "providerName": "VoyadoExternalStoreId",
    "id": "1100"
}

As it is possible to have multiple connectors in Omnium it is also important to remember to include a potential connector-prefix in the provider name to ensure the externalId is related to the correct Voyado instance.

Market-Specific Store Mapping

Sometimes, a single store in Omnium might serve multiple markets. In such cases, it can be useful to have separate stores in Voyado for each market, even if they map to the same store in Omnium.

To handle this, you can add the MarketId as a postfix to the providerName, separated by an underscore (_). This allows Omnium to determine the correct Voyado store based on the order’s market context.

Example with multiple store references separated by market context:

[
  {
    "providerName": "VoyadoExternalStoreId_NOR",
    "id": "1100"
  },
  {
    "providerName": "VoyadoExternalStoreId_SWE",
    "id": "1100"
  }
]

In summary the provider name should have the following format for in multi instance scenario, where there are multiple stores in Voyado per store in Omnium:

<ConnectorPrefix>_VoyadoExternalStoreId_<MarketId>

Full example with connector prefix "BikeShop" and market specific stores in Voyado for single store in Omnium:

[
  {
    "providerName": "BikeShop_VoyadoExternalStoreId_NOR",
    "id": "1100"
  },
  {
    "providerName": "BikeShop_VoyadoExternalStoreId_SWE",
    "id": "1100"
  }
]

Promotions

The Omnium-Voyado integration supports Promotions (personal offers) in Voyado Engage. The integration manages import and redemption of coupons created in Voyado Engage so that coupons assigned to customers can be used through all sales channels in Omnium. Each discount coupon is applicable only once.

In order to use dicount coupons from Voyado in Omnium, it is required that the promotion also exist in Omnium. The discount itself will also be specified through the promotion configured in Omnium.

The following is required to use a discount coupon from Voyado in Omnium:

• Create a promotion in Voyado Engage.
  • The promotion must be of type "Multichannel" and have redemptionchannel with type ECOM and valueType EXTENALOFFER
• Create a promotion in Omnium
  • Must have IsPersonalCouponPromotion = true
  • Must have a DiscountCode specified - this must be the same as the one in Voyado
• Set up workflow steps for checking and redeeming personal discount coupons
  • CheckPersonDiscountCoupons should be applied just before capture payment and should have StopOnError = true
  • TryRedeemPersonalDiscountCoupons should be applied just after capture payment
• Assign the Voyado coupon to customers in Voyado (note that the job exporting the coupons from Voyado runs at an interval so the coupon will not be available immediately in Omnium)

Vouchers

Voyado can be used to accumulate bonus points from purchases and convert these point to bonus checks. The Omnium-Voyado integration supports import and redemption of bonus checks generated and assigned in Voyado when placing orders in Omnium. In Omnium the corresponding concept is called Vouchers.

How it works

1. Voyado generates vouchers from accumulated bonus points.
2. Omnium has a scheduled task that retrieves both new and redeemed vouchers from Voyado.
   • New Vouchers from the import are created in Voyado and assigned to the private customer connected to the voyado contact that was assigned the voucher.
   • If this customer does not already exist in Omnium, Omnium will try to create it by fetching data from Voyado.
   • Vouchers redeemed in Voyado will be redeemed in Omnium as well, in case a voucher is redeemed through another channel.
3. The vouchers should now be available to inspect from either the private customer cart in Omnium or retrieved using the Omnium voucher-api.
4. In order to use a voucher in Omnium, apply it to a cart. This can be done through the UI under payments -> voucher or through the api-endpoint api/cart/{cartId}/ApplyVoucher/{voucherId}
5. This will add the voucher as an authorized payment on the order as well as updating the voucher status to Applied (thus preventing multiple uses of the same voucher in Omnium).
6. When completing an order, the capture payment workflow step will set the voucher payment to “captured” and update the voucher status to “Redeemed”
7. The voucher in Voyado will be marked redeemed once the receipt is exported to Voyado. This happens on the workflow step “Export Order” that is usually executed on the last order status.

Setup

1. Toggle “Use Vouchers” in the Voyado integration settings UI.
2. Set up the FTP Connection to Voyado.
3. Set the DefaultCurrency-setting under Voyado order settings. This will determine the currency on imported vouchers and should be the same as the group currency in Voyado.
4. In Voyado the Voucher export file must be configured to contain contactId, this is required to connect the voucher to the correct customer in Omnium.
5. Add the paymenttype “Voucher” in Omnium settings. The only thing that needs to be set in the payment type settings is Vue-template = “voucher-payment”
6. Setup scheduled task VoucherExpirationScheduledTask in order to enforce the expiration dates on vouchers. It is sufficient for this task to run once a day. Only vouchers with status “Available” will be affected by this task. This means that all vouchers that are applied before the expiration date can still be captured after the expiration date.

Future work

The current file export does not export the voucherId. Voyado requires this to work with their vouchers through the API, for instance when trying to reactivate vouchers.

After the implementation of this feature Voyado have launched webhooks for retrieving the Vouchers. This will provide Omnium with the VoucherIds needed to redeem vouchers directly upon capture payment as well as reactivating them when a payment is credited.

Transactional emails

The Omnium-Voyado integration supports sending transactional emails through Voyado. By setting up workflow steps in Omnium it is possible to inform Voyado about an order status change in Omnium, to trigger communication with the customer from Voyado.