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.

Get or Create Customers from Voyado

Omnium supports integrating the Voyado connector with the workflow step
GetOrCreateCustomerFromOrder. This is enabled by configuring VoyadoExporter as the connector for the workflow step.

When the Voyado connector is attached, the behavior of the workflow step is modified as described below.

Customer resolution logic

When customerId is provided

1. Look up customer in Omnium
   Omnium attempts to find an existing customer whose externalId matches the provided customerId (i.e. customers that have already been synchronized from Voyado).

2. Fallback 1: Look up contact in Voyado based on contactId
   If no matching customer is found in Omnium, Omnium attempts to locate a contact in Voyado with a matching contactId.

3. Fallback 2: Try to find existing Omnium customer with matching customerId
   If no matching customer has been found and order.customerId is set, Omnium tries to find an existing Omnium customer with the corresponding Id.

4. Fallback 3: Look up contact in Voyado based on phone/email If no matching customer has been found, Omnium attempts to locate a contact in Voyado based on phone/email. If CustomerClubMemberId is set on the order Omnium will search for a Member in Voyado, if not Omnium will seach for any contact.

5. Fallback 4: Try to create Voyado contact If neither lookup succeeds, Omnium will try to create the contact in Voyado and in Omnium based on the information available on the order.

6. Fallback 5: Default Omnium behavior
   If no matching customer has been found, Omnium falls back to the default behavior of GetOrCreateCustomerFromOrder and gets or creates a customer in Omnium based on the provided customerId.

When customerId is not provided

• Omnium uses the phone number and email address from the order to search for a matching customer in Voyado.
• If a match is found, the customer is imported from Voyado into Omnium.

Notes

• In this setup, customerId may refer to either:
  • the Voyado ContactId, or
  • the Omnium customerId.

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) exported to Voyado are lightweight and contain limited product information. To provide more context, receipts can be enriched with product data from Omnium.

This is done via an XML export that includes all products in Omnium and sends them to Voyado. The export frequency is managed by the scheduled task:

• Task: VoyadoProductDataExport
• Recommended Frequency: Once daily
• Format Specification: Voyado Enrichment XML Format

See section below for details on the xml product feed.

Voyado Product Data Export – Field Mappings

Standard Field Mappings

Category Mapping Logic

The category hierarchy is resolved using a parent traversal algorithm.

1. Main Category Determination

• First checks Product.MainCategoryId
• If empty and the product has variants, checks Variant.MainCategoryId for the specific variant
• Falls back to the first category marked as IsMainCategory in ProductCategories
• Final fallback: the first category in the ProductCategories list

2. Hierarchy Traversal

• Starting from the main category, traverses upward through parent categories using ParentId

• Creates a linked list:

  Main Category → Parent (Secondary) → Grandparent (Tertiary) → ...

• Maximum of 20 iterations to prevent infinite loops

3. Category Assignment

• maincategory = resolved main category name
• productcategory = parent of the main category (secondary level)
• subcategory = grandparent of the main category (tertiary level)

Example Hierarchy

Clothing (Tertiary – subcategory)
└── Outerwear (Secondary – productcategory)
    └── Winter Jackets (Main – maincategory)

Skip Root Category

If the category tree has a generic root node (e.g. "All Products") that should not appear in the Voyado product feed, this option can be enabled in the product export settings. When enabled, the root category is excluded and the remaining levels below it are used for maincategory, productcategory and subcategory instead.

All Products (Root – skipped)
└── Clothing (maincategory)
    └── Outerwear (productcategory)
        └── Winter Jackets (subcategory)

Custom Fields (spare1–spare10)

Custom properties are mapped to spare1 through spare10 fields based on connector configuration.

• Configuration: VoyadoProductDataCustomProperties connector setting

• Format: Comma-separated list of property names Example:

  Material,Weight,Collection

• Mapping order:

  • 1st property → spare1
  • 2nd property → spare2
  • …

• Retrieval:

  • Product.GetProperty(propertyName, skuId) (supports variant-specific values)

Export Process

1. Products are processed in batches of 1000

2. For products with variants, each variant is exported as a separate article

3. Products with SKUs (no variants) are exported directly

4. XML files are generated with a timestamp:

   OmniumArticleExport_yyyy-MM-dd-HH-mm-ss-fff.xml

5. Files are uploaded to:

   ftp://{host}/articleImport/{filename}

Product Assortment Filtering

When the Voyado connector has market restrictions configured, the product data export will automatically filter products based on their market assignments. This ensures that only products relevant to the connector's configured markets are included in the export.

The filtering uses the following connector settings:

Products without any market assignment (MarketIds or MarketGroupIds not set) are always included in the export, regardless of market restrictions.

If none of the above settings are configured on the connector, no market filtering is applied and all products are exported.

Required Fields

Products are skipped if any of the following fields are missing:

• skuId
• ProductId
• name (variant name)
• mainCategoryId (and its corresponding category)

Excluding Products from Receipts and Bonus Calculations

Certain products can be excluded from appearing in receipts or from contributing to bonus point calculations in Voyado. This is achieved by adding specific custom properties to those products and ensuring these properties are enriched onto order lines.

1. Exclude from Receipts

To exclude products from receipts entirely:

• Custom Property: ExcludeFromVoyadoReceipts = true

When present on an order line, Omnium will omit that line from the exported receipt.

2. Exclude from Bonus Point Calculation

To exclude products from bonus point rewards:

• Custom Property: ExcludeFromVoyadoBonusPoints = true

When present, Voyado will ignore the order line when calculating bonus points.

Configuration Steps

To implement either exclusion:

1. Set the appropriate custom property (ExcludeFromVoyadoReceipts or ExcludeFromVoyadoBonusPoints) on the relevant products.
2. Ensure these properties are enriched onto order lines during the order process.

Refer to the Order Line Enrichment Configuration section below.

Order Line Enrichment Configuration

To ensure custom product properties are copied to order lines:

• Navigate to:
  Configuration → Orders → Order line
• Under "Enrich order line from products", add the necessary custom properties (ExcludeFromVoyadoReceipts and/or ExcludeFromVoyadoBonusPoints)

All properties listed here will be copied from products to the corresponding order line items automatically.

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" / "DisabledForMarkets" or "EnabledForMarketGroups" / "DisabledForMarketGroups" 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

Multiple Voyado Instances

Omnium supports integration with multiple Voyado instances. To manage this effectively, you can define a connector prefix in the Voyado connector settings. This helps associate each externalId in Omnium with the correct Voyado instance.

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

Connector Scoping

For multi-instance setups, each Voyado connector should be scoped using one of the following configurations in Omnium:

• EnabledForMarkets / DisabledForMarkets
• EnabledForMarketGroups / DisabledForMarketGroups

This ensures that each connector operates only within its intended scope and does not interfere with others.

External ID Format

When a prefix is defined, externalId's in Omnium will be generated in the following format:

<ConnectorPrefix>_VoyadoContactId

This structure ensures that each externalId is unique and clearly associated with the correct Voyado instance.

Stores

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 (Voyado ↔ Omnium)

The Omnium–Voyado integration supports Promotions (Personal Offers) from Voyado Engage. This integration handles the import and redemption of discount coupons created in Voyado so that coupons assigned to customers can be used across all sales channels in Omnium.

Each discount coupon is single-use and can only be redeemed once.

Important To use a discount coupon from Voyado in Omnium, the corresponding promotion must also exist in Omnium. The discount logic itself (percentage, amount, etc.) is configured in Omnium, not in Voyado.

Setup

To use Voyado discount coupons in Omnium, the following setup is required.

1. Create a Promotion in Voyado Engage

• Promotion type must be Multichannel

• The promotion must include a redemption channel with:

  • type: ECOM
  • valueType: EXTERNALOFFER

2. Create a Promotion in Omnium

The promotion in Omnium must meet the following requirements:

• IsPersonalCouponPromotion = true

• A DiscountCode must be specified

  • This must match the discount code used in Voyado

3. Configure the Voyado Connector

In the Voyado settings UI, configure the following:

Under scheduled tasks - ensure that the scheduled task Voyado Voyado - Coupon synchronization is running.

4. Configure Workflow Steps in Omnium

The order workflow must include steps for validating and redeeming personal discount coupons.

Add the following workflow steps:

1. CheckPersonalDiscountCoupons

   • Connector: VoyadoExporter
   • StopOnError = true

2. TryRedeemPersonalDiscountCoupons

   • Connector: VoyadoExporter
   • StopOnError = true

5. Assign Coupons to Customers in Voyado

• Assign the Voyado promotion to customers in Voyado Engage.
• Coupons are exported from Voyado on a scheduled interval, so they will not be available immediately in Omnium after assignment.

Workflow Placement Recommendation

The workflow steps for checking and redeeming coupons should be placed either:

• On order status New (recommended), or
• Just before payment capture

Recommendation

Placing the steps on status New is recommended because it:

• Prevents customers from placing multiple orders using the same coupon
• Ensures coupons are validated early in the checkout flow

Both placements will prevent multiple completed orders from using the same coupon.

How It Works

1. Omnium runs a scheduled task (VoyadoPromotionSyncScheduledTask) that imports personal offers from the Voyado SFTP server.

   • Files are read from the /couponExport/ directory
   • Failed imports are moved to /couponExport/failed/ for troubleshooting
   • The import frequency is configured through the scheduled task settings

2. The import handles three types of promotion events:

   • Assigned: New coupons assigned to customers
   • Redeemed: Coupons redeemed through other channels (e.g., POS)
   • Deleted: Coupons revoked or expired in Voyado

3. Imported coupons are stored on the customer entities in Omnium.

   • If a customer doesn't exist in Omnium, the system attempts to create them using the contact's email or phone number (based on CustomerUniqueIdentifier setting)

4. Once imported, coupons can be applied:

   • Via API (e.g., CartAddCouponCodeToCart)
   • Via the Omnium cart UI

5. When a cart is converted into an order:

   • The workflow executes
   • Coupon validity is checked against Voyado API
   • The coupon is redeemed in Voyado (/api/v2/promotions/codes/{promotionId}/redeem) if the order completes successfully

Troubleshooting

Common Redemption Errors

Import Issues

• Check the /couponExport/failed/ directory for failed XML files
• Verify the SFTP connection is configured correctly via RelatedConnector
• Ensure SyncPromotions is enabled in the connector settings

Summary

• Voyado manages assignment of personal coupons

• Omnium manages discount logic and redemption

• Coupons are:

  • Imported on a schedule from SFTP
  • Stored per customer
  • Validated and redeemed through order workflows
  • Restricted to single use
  • Synchronized bi-directionally (redemptions in other channels are reflected 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.

Voyado Order API - V2

The Omnium-Voyado integration enables sending transactional emails via Voyado, using the Voyado Order API v2.

Setup

1. Activate the Exporter Enable the VoyadoOrderExporter from the Voyado settings UI in Omnium.

2. Configure the Workflow In Omnium, add the ExportOrder action to any workflow step where you want to trigger a Voyado action.

   • Set the Connector to VoyadoOrderExporter.

How It Works

1. Setting up Omnium

   For each order status in Omnium where a transactional email in should be triggered in VOyado, add a workflow step called ExportOrder using the connector VoyadoOrderExporter.

   Note: Do not confuse VoyadoOrderExporter with VoyadoExporter, which handles receipt exports.

   The ExportOrder step will:

   • Map the Omnium Order to Voyado's OrderModel.
   • Send the order data to Voyado's /api/v2/orders endpoint.

2. Configuring Email Triggers in Voyado

   In Voyado, configure transactional emails to trigger upon receiving an order with one of the relevant statuses from Omnium.

Voyado Order API – V3

Omnium now supports Voyado Order API V3, a more flexible and powerful version than its predecessor. This integration enables triggering various order-related actions in Voyado directly from Omnium.

Setup

1. Activate the Exporter Enable the VoyadoOrderV3Exporter from the Voyado settings UI in Omnium.

2. Configure the Workflow In Omnium, add the ExportOrder action to any workflow step where you want to trigger a Voyado action.

   • Set the Connector to VoyadoOrderV3Exporter.

   • OPTIONAL: In the Properties tab of the workflow step configuration modal:

     • Add a property with key: VoyadoOrderAction

     • Set the value to: "ACTION_NAME" (Replace ACTION_NAME with the specific action to trigger in Voyado.)

     • To add data to the order action: Add properties with keyGroup VoyadoActionExtraData and key equaling the propertyName in Omnium. The property name can point to string values on order/shipment/return root or custom properties on the order, shipment, or return.

     • To add line-item level data to the order action: Prefix the property key with LineItem. (e.g., LineItem.Color). This will resolve the property for each line item in the shipment (or order form if no shipment) and include it in the action payload under an itemLevel array.

Example of how the export workflow step JSON should look:

{
   "name": "ExportOrder",
   "active": true,
   "runAfterOrderIsSaved": false,
   "stopOnError": false,
   "connector": "VoyadoOrderV3Exporter",
   "properties": [
      {
            "key": "VoyadoOrderAction",
            "value": "<ActionName>"
      },
      {
            "key": "<PropertyName1>",
            "value": "",
            "keyGroup": "VoyadoActionExtraData"
      },
      {
            "key": "<PropertyName2>",
            "value": "",
            "keyGroup": "VoyadoActionExtraData"
      },
      {
            "key": "LineItem.<PropertyName3>",
            "value": "",
            "keyGroup": "VoyadoActionExtraData"
      }
   ]
}

How It Works

The Omnium–Voyado integration operates by executing hooks in the Omnium order workflow that initiate an export to Voyado and trigger a specific action.

Here's a step-by-step outline:

1. Triggering the Export When a configured workflow step executes the ExportOrder action, Omnium initiates an export to Voyado containing the specified order action as an embedded order action.

2. Polling for Completion Omnium receives a job reference from Voyado and continuously polls the API to monitor the status of the order import job.

3. Error Handling If an error occurs (e.g., a failed import or API error), it is logged in Omnium and associated with the affected order. These errors are visible from both the Order Detail Page and the Order List.

Note: Due to the asyncronous nature of this part of the integration Omnium will perform steps 2-3 asynchronously in the backgroud. The order workflow will continue to execute in the meantime, and there is no guarantee that action in Voyado is completed nor successful at time the next workflow step in Omnium is executed.

Return Order Exports

The VoyadoOrderV3Exporter also supports exporting return orders to Voyado. This allows triggering Voyado actions when a return is processed in Omnium (e.g., sending a return confirmation email).

Setup

1. In Omnium, add the ExportReturn action to the relevant return workflow step.
2. Set the Connector to VoyadoOrderV3Exporter.
3. OPTIONAL: Configure a VoyadoOrderAction property and VoyadoActionExtraData properties on the workflow step, just like for order exports.

How It Works

The return export follows the same pattern as order exports:

1. Omnium maps the return order form to the Voyado Order V3 format, including the return status.
2. If a VoyadoOrderAction is configured on the workflow step, it is included as an embedded order action on the request.
3. Omnium sends the return data to Voyado. If the return has been exported previously (tracked via externalId), Omnium will update the existing order in Voyado. Otherwise, a new order is created.
4. Omnium polls the job status asynchronously to verify completion, the same as for order exports.

Notes

• The return exporter resolves the Voyado contact using the same customer lookup logic as the order exporter (private customer first, then business customer).
• If the VoyadoOrderV3Exporter connector is configured as a related connector, the main connector settings are used for customer lookup.
• The return externalId key uses the connector prefix (if configured) to support multi-instance setups.

Order Action Extra Data

Order/Shipment/Return Level Properties

When configuring VoyadoActionExtraData properties on a workflow step, the property key refers to a property name on the entity being exported. The resolution order depends on the export type:

• Order exports: Shipment properties are checked first, then order properties.
• Return exports: Return order form properties are checked first, then order properties.

For each property, the system first checks custom properties on the entity, and then falls back to built-in properties on the entity root (e.g., Status, Id).

Line-Item Level Properties

To include per-line-item data in the order action, prefix the property key with LineItem. in the VoyadoActionExtraData configuration.

For example, configuring LineItem.Color will:

1. Iterate over all line items in the shipment (or order form if no shipment is present).
2. For each line item, resolve the Color property (first from custom properties, then from built-in fields).
3. Include the result in an itemLevel array in the action data payload.

Each entry in the itemLevel array contains the line item's id and the resolved property values.

Example resulting action payload:

{
  "action": "ActionName",
  "language": "sv-SE",
  "data": {
    "trackingUrl": "https://example.com/track/123",
    "itemLevel": [
      {
        "id": "line-item-1",
        "color": "Red"
      },
      {
        "id": "line-item-2",
        "color": "Blue"
      }
    ]
  }
}

Multiple LineItem.* properties can be configured. If multiple properties are specified for the same line item, they are merged into a single entry per line item.