Skip to main content
Here you’ll learn how to integrate your Point-of-Sale (POS) system with Voyado Customer Engagement. In this article we will cover how to:
  • Connect to the Customer Engagement API
  • Sync and manage customer data
  • Handle transactions
  • Deliver digital receipts
  • Set up personalized promotions and vouchers
  • Migrate existing data
In Customer Engagement, customers are called contacts. This includes members, subscribers and prospects.

​
1. Basic requirements

To start building an integration with Customer Engagement, here’s what you need:
  • Base URL - Your Customer Engagement environment endpoint
  • API Key - Your authentication key generated in Customer Engagement
  • Source - A string identifying the system or integration sending the data (such as “ECOM”)
  • StoreExternalId - A unique identifier per store, site, or market
The storeExternalId attribute is a unique string for each store and it should always reflect the store location, such as for example “store03-stockholm” or “online_store_finland”.

Learn about the Customer Engagement API

​
2. Handling customers

The flow begins with identifying the customer.

​
2.1 Identifying a customer

FIrst check if the customer already exists in Customer Engagement. The default unique identifier for contacts in Customer Engagement is email but other options exist:
  • Mobile phone number
  • Member number
  • Personal identify number

See how to search for a contact in Customer Engagement

Finding a customer

​
2.2 Registering a customer

If no match is found, you will need to create a new Customer Engagement contact for the customer. To keep it fast and easy at checkout, build your integration so that only one identifier (email or phone) is required from the customer to add them. Registering a new contact will starts Customer Engagement’s automation workflows (if one is set up).

See how to create a contact in Customer Engagement

​
2.3 Data to include

When posting a contact’s data to Customer Engagement, always include the following in your payload:
  • Source: For example “ECOM”
  • StoreExternalId: Reflects the customer’s market/shipping country
  • Country: Set from address, site geo-location, or store settings
  • Language: Based on site language or customer choice (ISO 639-1)

Learn about contact fields

​
2.4 Displaying customer info

The Customer Engagement /contactoverview endpoint can be used fetch the customer’s full data profile (known as their enriched profile).

Learn about the contactoverview endpoint

Here are some useful data points from the enriched profile:
  • First name
  • Last name
  • Address
  • Gender
  • Birthday
  • Communication preferences
  • Loyalty level
  • Points
  • Available vouchers
  • Available promotions
  • Consents
Use this to display relevant loyalty data on “My Pages” and in checkout:
Show customer info

​
2.5 Update customer profile

When a customer updates their data (for example name or address or marketing preferences), you’ll need to push that update to Customer Engagement.

Learn about updating contacts

Only include the fields you want to change in your update payload. Empty values will in the update payload will overwrite the existing data that is stored in Customer Engagement.

​
3. Working with receipts

Customer Engagement uses receipts (the total data of a customer’s transactions) to track purchases and power customer segmentation, enabling personalized experiences and analytics.

​
3.1 Registering purchases

Send each completed receipt from your POS to Customer Engagement.

Learn about registering purchases

Be sure to include any discounts, vouchers and promotions and:
  • Spread the discount value across all item lines
  • Include promotionId or voucherNumber if applicable

Learn about working with discounts

​
3.2 Local currency support

If your POS operates in a different currency than the customer’s group currency, include a currency conversion in your payload (as the attribute exchangeRateToGroupCurrency). If your POS is unable to include a currency conversion rate in the transaction. then a conversion scheme to handle this can be set up in Customer Engagement.

Learn about fields in the transaction payload

A currency code must always be included in the transaction.

​
3.3 Registering returns

When a return is made, you must send a return receipt containing the details of the returned products.

Learn about returns

​
3.4 Sending digital receipts post-purchase

You can send digital receipts post-purchase from Customer Engagement, which include:
  • Customer details
  • Order and item information
This is done through the /orders endpoints:

The orders API endpoints

When the state of orders change, marketing automation flows in Customer Engagement can be triggered:

Learn about order actions

Custom data can be included in the order via data or on then item level using item.ExtraData.

​
4. Personalized promotions in POS

You can use Customer Engagement’s segmentation and automation tools to assign individual promotions or vouchers, such as “10% off for Gold members” or “€10 Voucher“. Some important points about promotions (and vouchers):
  • Promotions are created in Customer Engagement and referenced in the e-com by an external ID
  • It is the e-com that handles pricing rules and redemption logic
  • It is Customer Engagement that handles personal assignments of the discount

Learn more about promotions

​
4.1 Welcome promotion at sign-up

If your loyalty program offers welcome promotions, customers often expect to receive and redeem such a promotion immediately, especially during an in-store purchase. To enable this, you can directly assign a personal promotion in Customer Engagement using the request:
By doing this you can:
  • Avoid delays caused by asynchronous automation flows
  • Prevent queue build-up and customer frustration in physical stores.
  • Ensure the promotion can be redeemed during the same transaction where the customer signs up

​
4.2 Creating promotion in POS

Create the promotion in the POS system first. For example:
  • Promotion name: Welcome 10%
  • Discount logic: 10% off first purchase
  • Promotion code: WELCOME10
This promotion will be responsible for price handling at checkout.

​
4.3 Creating promotion in Customer Engagement

Now create a corresponding promotion in Customer Engagement for the welcome offer. This promotions references the POS promotion you just made through its external promotion code (externalId) which must match the POS promotion code / internal ID if the POS owns the price logic. What Customer Engagement does here is:
  • Controls the assignment
  • Controls the validity period
  • Connects the promotion to the contact
  • Makes it available on the customer’s profile

​
4.4 In-store sign-up flow

Here is how the promotion is handles in the sign-up flow.
1

Customer signs up in store

  • Customer registers as a loyalty member in the POS
  • POS either updates the customer in Customer Engagement or creates them there
2

POS assigns the welcome promotion

Immediately after successful sign-up, the POS must call:
With:
  • The customer identifier (contactId)
  • The promotion identifier (promotionId)
This makes the promotion personal and instantly available.
3

Promotion can now be redeemed in the same purchase

Immediately after successful purchase, the POS must call:
With:
  • The promotion assignment identifier (assigmentId)
  • The redemption channel as “POS” (“redemptionChannel” : “POS”)

​
5. Assigning vouchers

Points are converted to vouchers in Customer Engagement and created as a personally assigned monetary discount in the POS. Customer Engagement handles the pricing rules and the POS then redeems the voucher using the Customer Engagement API.

Learn about vouchers in Customer Engagement

​
6. Data migration (before go-live)

Before going live, you must migrate into Customer Engagement your:
  • Historical customer data
  • Historical transaction data

Historical customer data

Historical transaction data

You can choose what to sync and and how far back to sync it.
Voyado recommendeds you go back a maximum of 24 months for receipts (transactions).