Voyado Loyalty Adapter

Overview

The Voyado Loyalty Adapter integrates Voyado Engage with Norce Checkout (NCO), enabling merchants to apply Voyado loyalty benefits to a Norce Checkout order. Voyado Engage is a customer loyalty and marketing-automation platform.

Unlike payment adapters, the Voyado Loyalty Adapter does not take payments. It participates in the checkout flow by:

• Linking a Voyado contact to the Norce Checkout order as customer.loyalty.
• Exposing the promotions and reward vouchers available for that contact in Voyado.
• Writing applied promotions and reward vouchers back to the order so that the Norce Adapter can translate them into discount line items in Norce Commerce.

The adapter is identified by the adapter id voyado_checkout_adapter and is configured per merchant/channel in Norce Checkout Admin.

Capabilities and Supported Flows

Supported Operations

Integration Type

• Loyalty / CRM integration; not a payment or shipping adapter.
• Runs inside the normal checkout flow (not as a post-purchase notification).
• The frontend is responsible for letting the customer identify themselves in Voyado and for calling the adapter with the resulting Voyado contact id.

Limitations

• The adapter does not register receipts or transactions in Voyado. Purchase data is not pushed to Voyado by this adapter. Receipt/transaction synchronization with Voyado is currently solved by third-party integration partners such as Nexer Group's Commerce Integration Platform, not by Norce Checkout.
• GET, apply, and remove for promotions and reward vouchers all require order.customer.loyalty.id to be set on the Norce order first via the loyalty/{orderId}/set endpoint.
• Reward vouchers require rewardVoucherLevels to be configured. A voucher amount that does not match any configured level fails with configuration-error.
• Promotions without an externalId and without a usable ECOM redemption channel value fail to apply with promotion-external-id-missing.

Prerequisites

From Voyado

To use the Voyado Loyalty Adapter you need the following from Voyado Engage:

• A Voyado Engage tenant with API access enabled.
• A Voyado API key (sent in the apikey header) that allows reading contacts, promotion assignments, and reward vouchers (api/v3/contacts/{id}, api/v3/promotion-assignments, api/v3/reward-vouchers/available).
• Your Voyado client identifier, used in the API URL (https://{client}.voyado.com or https://{client}.staging.voyado.com).

From Norce

• Norce Checkout enabled for your Norce Commerce account.
• A configured merchant and channel in Norce Checkout Admin.
• The Norce Adapter configured on the same order so that loyalty promotions and reward vouchers can be translated into Norce Commerce discount lines.
• Norce discount externalId values that correspond to each configured rewardVoucherLevel.maxAmount, and to any promotion that is expected to be redeemed through ECOM.

Environments

The Voyado Loyalty Adapter URLs follow the standard NCO pattern:

Replace {slug} with your organization's slug provided by Norce.

Voyado API environments used by the adapter:

Replace {client} with your Voyado client identifier.

Configuration in Norce Checkout Admin

The Voyado Loyalty Adapter is configured per merchant/channel in Norce Checkout Admin. Configuration is validated against the voyado_adapter JSON schema published by the adapter.

Required configuration

Reward voucher levels

rewardVoucherLevels maps Voyado reward vouchers to Norce discount externalId values based on the voucher amount.

Levels are evaluated in ascending maxAmount order. The first level whose maxAmount is greater than or equal to the voucher amount wins. If no level matches the voucher amount, applying the voucher fails with configuration-error.

Example configuration:

{
  "$schema": "https://{slug}.api-se.playground.norce.tech/checkout/voyado-adapter/openapi/v1/schemas/voyado_adapter.json",
  "id": "voyado_adapter",
  "active": true,
  "adapter": {
    "internalUrl": "https://voyado-adapter.checkout.playground.internal.norce.tech",
    "publicUrl": "https://{slug}.api-se.playground.norce.tech/checkout/voyado-adapter"
  },
  "apiSettings": {
    "apiUrl": "https://yourclient.voyado.com",
    "apiKey": "***"
  },
  "rewardVoucherLevels": [
    { "maxAmount": 100, "externalId": "VOYADO_VOUCHER_100" },
    { "maxAmount": 250, "externalId": "VOYADO_VOUCHER_250" },
    { "maxAmount": 500, "externalId": "VOYADO_VOUCHER_500" }
  ]
}

Matching Voyado codes to Norce Commerce promotions

Every externalCode that the Voyado Loyalty Adapter writes to the order (from a Voyado promotion or from a rewardVoucherLevels[].externalId) must exist as a Promotion in Norce Commerce Admin. Without a matching Promotion, the order still carries the loyalty entry but no discount line item is generated in Norce Commerce.

For each expected externalCode, create a Promotion in Norce Commerce Admin with:

• Status — Active.
• Code — a unique code for the promotion (free-form, for example RewardVoucher-600).
• Requirement — If the external discount code is <externalCode>, where <externalCode> is exactly one of:
  • A Voyado promotion externalId.
  • The value of the Voyado promotion's ECOM redemption channel (when externalId is empty).
  • A rewardVoucherLevels[].externalId value from the adapter configuration (for example VOYADO_VOUCHER_100 or RewardVoucher-600).
• Effect — the discount that should be applied when the code matches (for example THEN Discount all in basket with 600,00 SEK incl. VAT).

When a Voyado promotion or reward voucher is applied through the Voyado Loyalty Adapter, the Norce Adapter looks for a Norce Commerce Promotion whose requirement matches the externalCode written on the order and adds the corresponding discount line item to the cart. If no matching Promotion exists, no discount is applied.

Example: reward voucher Promotion in Norce Commerce Admin

A Norce Commerce Promotion that matches a Voyado reward voucher of 600 SEK (mapped by rewardVoucherLevels to externalId = "RewardVoucher-600") might look like this in Norce Commerce Admin:

Key fields:

• Status: Active.
• Requirement: IF External discount code is RewardVoucher-600.
• Effect: THEN Discount all in basket with 600,00 SEK incl. VAT.

Example: Voyado promotion Promotion in Norce Commerce Admin

A Norce Commerce Promotion that matches the Voyado NEWCUSTOMER promotion (whose externalCode resolves to NEWCUSTOMER either from the Voyado externalId or from the ECOM redemption channel value) might look like this in Norce Commerce Admin:

Key fields:

• Status: Active.
• Requirement: IF External discount code is NEWCUSTOMER.
• Effect: THEN Discount all in basket with 10,00 %.

How the Voyado Loyalty Adapter uses the Norce order

The adapter reads and writes order.customer.loyalty on the Norce Checkout order:

• order.customer.loyalty.id — Voyado contact id. Set by POST /api/v1/loyalty/{orderId}/set and required by every other endpoint.
• order.customer.loyalty.provider — always "Voyado" when set by this adapter.
• order.customer.loyalty.promotions[] — list of applied Voyado promotions. Each entry contains the Voyado id, the resolved externalCode, and the promotion name.
• order.customer.loyalty.rewardVouchers[] — list of applied reward vouchers. Each entry contains the Voyado id, voucherNumber, name, and the Norce discount externalCode resolved from rewardVoucherLevels.

Applied promotions and reward vouchers are written to the order, and the Norce Adapter then converts them to discount line items in Norce Commerce. The Voyado Loyalty Adapter itself does not modify the cart totals.

Promotion externalCode resolution

When applying a promotion, the adapter picks an externalCode to write to the order using the following rule:

1. If the Voyado Promotion.externalId is non-empty, it is used as-is.
2. Otherwise, the adapter looks up the redemption channel with type == "ECOM" on the promotion and uses its value (string or number).
3. If neither is available, applying the promotion fails with promotion-external-id-missing.

Reward voucher externalCode resolution

When applying a reward voucher, the adapter picks an externalCode based on the configured rewardVoucherLevels:

1. The voucher's value.amount is compared against rewardVoucherLevels sorted by maxAmount ascending.
2. The externalId of the first level with maxAmount >= voucher.value.amount is used.
3. If no level matches, applying the voucher fails with configuration-error.

Calls to Voyado Engage

The Voyado Loyalty Adapter calls the following Voyado Engage endpoints. All calls include the configured apiKey as the apikey header.

A 404 response from Voyado is translated into voyado-contact-not-found.

Error Handling and Troubleshooting

Error codes

Troubleshooting checklist

• Verify apiSettings.apiUrl points to the correct Voyado environment (staging.voyado.com in test, voyado.com in production).
• Verify apiSettings.apiKey is valid and has permissions for the contacts, promotion-assignments, and reward-vouchers/available endpoints.
• Verify order.customer.loyalty.id is present before calling promotion or reward-voucher endpoints.
• Verify that Voyado promotions intended for ECOM have either an externalId or a non-empty ECOM redemption channel value.
• Verify that rewardVoucherLevels covers every voucher amount used by your Voyado reward setup.
• Verify that every externalCode written to the order has a matching Promotion in Norce Commerce Admin whose requirement is If the external discount code is <externalCode>. Without it, no discount line item is created in Norce Commerce even though the loyalty entry is present on the order.

Links and References

Norce Checkout API References

• NCO Order API
• NCO Configuration API
• NCO Notification API

Norce Checkout Overview

• Norce Checkout Introduction
• Working with Norce Checkout
• Loyalty Adapters Overview
• Voyado Loyalty Adapter Developer Guide

External Documentation

• Voyado Engage (contact Voyado for API documentation)