This guide has been created to assist Point of Sale (POS) solutions integrate to the Omneo CX Suite, the scope of which may include:
- Search, view, edit or create an Omneo Profile (which is Omneo's representative data record of a Customer or Member);
- Sync Omneo Profiles to the POS's Customer database;
- Get a Reward Balance;
- Create a Reward Redemption, Reversal or Refund;
- Create a Benefit Redemption, Reversal or Refund;
- Create, edit or delete Staff records;
In some environments, POS systems may also:
- Send Product data to Omneo;
- Send Transaction data to Omneo.
Introduction
The Omneo CX Suite is a group of applications collecting and using customer data to foster engagement and empower brands to create exceptional customer experiences. Detailed information about the Omneo CX Suite can be found in the section What is Omneo?
Any bolded term in the guide notates a term that is defined in the Omneo Terminology Glossary.
Primary Integration Functions
The following are critical integration points between a POS solution and Omneo.
POS Customer Management
Omneo maintains synchronisation and enrichment of customer data between platforms including POS, eCommerce, App's, Communications and Customer Support. Thus a POS-Omneo integration must enable a Staff member to manage Omneo Profiles (the data record that Omneo creates to represent a "Person") by allowing them to:
- Create a new Omneo Profile;
- Search the list of Omneo Profiles;
- View and edit a Profile.
We strongly recommend that the POS terminal invokes the Omneo Clienteling portal to replace native POS Customer management screens. In addition to simplifying the integration, an Omneo Profile record includes many additional attributes and the Omneo Clienteling application includes data validation tools.
The use of the Omneo Clienteling portal is described in further detail in the section below.
Redemption Management
Omneo manages the execution of customer loyalty and engagement programs, of which a common component includes some type of financial advantage such as:
- Rewards which are a dollar amount and processed in Transactions as a dollar discount;
- Points which are converted to a redeemable dollar figure and processed in Transactions as a dollar discount;
- Benefits which are an exclusive offer with some conditional logic such as a gift, percentage discount, buy one get one free, etc.
A POS can process on Omneo Redemption via one of two methods:
- Via calls to Omneo API endpoints (Reward Balance, Reward Redemption or Benefit Redemption); or
- Via Omneo Clienteling portal and POS Callbacks.
To create the best user experience for Staff we recommend implementing via the Omneo API so that the redemption process is part of the native functions of the POS solution.
Staff Record Management
POS is able to create, edit or delete Staff records in Omneo via the Staff endpoint. Staff records are referenced for two main purposes in Omneo:
- Relation to POS Transaction records; &
- Identification and security/access role definition of the Omneo Clienteling portal.
Synchronising Omneo Data to POS
POS integration should also synchronise Omneo Profiles (new/updated/deleted) to the POS. This is best achieved by creating an App to subscribe, ingest and process webhooks that the Omneo Plugin Framework provides to manage data synchronisation.
Detailed information about the Omneo Plugin Framework can be found in the section {Plugin Framework - coming soon}.
Other Data
Some deployments may also utilise the POS system as a source of the following data:
Transactions
To create, update or delete Transactions in Omneo - API documentation can be found at Transactions endpoint.
Note that Omneo does not store Orders, only finalised Transactions. For this reason an ERP solution will often be utilised as a Transaction source by Omneo.
Products
To create, update or delete Products in Omneo - API documentation can be found at Products endpoint.
In many deployments, enriched Product data such as that stored within a Product Information Management (PIM) solution or eCommerce platform which includes product images, descriptions and categorisations is utilised as a source by Omneo.
Omneo Clienteling Portal
The Omneo Clienteling portal is web based application which acts as the primary method for Staff to access Profiles and action service tasks. The Omneo Clienteling portal should replace any POS "Customer" or "Member" functions whereby the POS:
- Launches a chromeless browser window, loading the Omneo Clienteling portal;
- Adds variables to URI including the following details:
- Store ID;
- Staff ID;
- Terminal ID;
- Profile ID if customer has been natively POS identified such as via a membership card scan (otherwise the Omneo Clienteling portal will open to a default to the search page if no valid member is found).
- The Staff member may perform any customer service functions within the portal but ultimately want to close the window to:
- Attach the Member to a sale;
- Redeem a Reward that has been earned by the customer;
- Attach a Transaction ID and Member to begin a ‘return or exchange’ process;
- Attach Product(s) to a Transaction where a customer might be ‘buying’ a gift or service (non-stocked item);
- Redeem a Benefit that has been earned by the customer and has been approved to be applied to the sale.
Note that functionality of the Omneo Clienteling portal maybe enabled/disabled depending on the brands requirements.
Access & URL Structure
Each Omneo Tenant is provided with a unique Clienteling Service URL to access a production and staging environment of the Omneo Clienteling portal which generally resembles the following structure:
| Staging | https://{tenant}.clienteling-stg.omneo.io |
| Production | https://{tenant}.clienteling.omneo.io |
When making calls to the Clienteling Service URL, the following mandatory query parameters need to be present in the URL in order to automatically authenticate. Failure to authenticate will redirect the user to a login screen.
For example:
https://achmeshoeco.clienteling.omneo.io?staffID=0010&storeID=17&terminalID=POS7&type=POS
|
Parameter |
Type |
Description |
|
staffId |
String |
The ID of the staff. |
|
storeId |
String |
The ID of the store. |
|
terminalId |
String |
The ID of the current access device (terminal). |
|
type |
One of these values: Administration |
The type (context) of device that will be accessing the Clienteling portal. Available contexts may change according to individual implementations. |
|
max_redeem |
Int |
The current total of all items in the transaction which is the maximum of reward dollars that could be applied. |
Functions
The following Omneo Clienteling functions should replace the POS's native Customer or Loyalty screens/functions.
Search
The Omneo Clienteling search page should replace any customer/member search screen by invoking the following example URL:
{Clienteling Service URL}?staffID=0010&storeID=17&terminalID=POS7&type=POS
Profile Page
The Omneo Clienteling Profile page should replace any customer/member profile screen by invoking the following example URL:
{Clienteling Service URL}/profile/{profileId}?staffID=0010&storeID=17&terminalID=POS7&type=POS
where profileId is the Omneo Profile ID.
This enables you to pass a Profile id from your terminal/device and open the Profile record directly in the Omneo Clienteling portal.
Reward Redemption
The Omneo Clienteling redemption page can be used by POS systems where they are unable to make a live calls via the Omneo API. In this scenario the Omneo Clienteling redemption page will make the balance and redemption calls and can pass a callback to the POS.
You can link to the Redeem page for a Profile and set the redemption value limit in that page:
{serviceUrl}/redeem/{profileId}?staffID=0010&storeID=17&terminalID=POS7&type=POS
The Omneo redemption page enables the staff member (POS user) to set the amount the member wants to redeem (with a limit of transaction value or reward balance - whichever is lower). This value is then passed back to the POS.
POS Callbacks
The following actions made inside the Omneo Clienteling portal will communicate back to the invoked browser window to communicate actions for the POS to act on.
Return To POS
Where a user clicks BACK in the Omneo Clienteling portal, it will trigger the following event without attaching the current customer:
window.memberProfile_returnToPOS()
Attach Member
Where a user clicks ATTACH in the Omneo Clienteling portal, it will trigger the following event and the window should be closed by the POS:
window.memberProfile_addToSale(profileID)
Redeem Reward or Benefit
Where a user clicks REDEEM in the Omneo Clienteling portal, it will trigger:
window.redeemReward_returnConfirmation(profileID, willRedeem)
Load Transaction
Where a user clicks ATTACH TRANSACTION in the Omneo Clienteling portal, it will trigger:
window.memberProfile_loadTransaction(memberID, transactionID)
In this scenario the POS application needs to listen to this trigger and close window at the end of the process.
Requirements & Compatibility
Browser Compatibility
The Omneo Clienteling portal has been developed to run on modern browsers, and is fully tested the current public version of Google Chrome & a version prior. Support for any other browsers must be specified.
If you encounter any issues please send through support requests to support@omneo.io
Window Size
The recommended minimum window size to view the Store Portal is 1024 x 768.
Network
An active internet connection is required with a static IP address that will allow outbound http(s) connections from the POS via port 443.
IP Restrictions
Omneo maintains a an IP whitelist per Tenant and access to the Omneo Clienteling portal is only permitted by approved IP addresses. Please contact Omneo support at support@omneo.io in order to whitelist your IP address.
Omneo API
Documentation of the Omeno API is available at http://omneo.io/docs where you can learn about all API calls and methods, what they are for, and how they are used. Note that many of the methods described on these docs are not required as part of a typical POS integration.
Authentication
The Omneo API uses OAuth Authorisation using the client credentials grant type. Tokens are created within the Omneo CX Manager and provided to third parties. After you have acquired your token you can use it to access other resources within token's scope.
Further documentation can be found in the Authorisation endpoint documentation.
Customer Management
A Profile record lookup can be performed by ID or email address via the Profile List endpoint. Additionally a Member record can be created via the Create Profile endpoint.
However it is recommended that these functions are performed by invoking the Omneo Clienteling portal to ensure integrity of Member/Customer data. The Omneo Clienteling portal has many additional data points incorporates data validation tools to ensure data accuracy.
API documentation can be found at Profile endpoint.
Redemption Management
Redeeming Rewards
The process of redeeming an Omneo Reward has been customised to suit the requirements of in different POS integrations, however the ideal process is:
Step 1 - Identify the Customer
Identification of the customer can be performed several ways:
- By synchronising Omneo data with the POS then a local lookup could be performed to obtain the profile_id.
- Launching the Omneo Clienteling search screen (which has an Algolia powered instant and typo tolerant search feature), using the ATTACH PERSON button & associated callback to return the profileId.
Step 2 - Check the Reward Balance
Retrieve the redeemable value via the Reward Balance endpoint. Omneo will aggregate all 'rewards' to return a response which defines the live total dollar value of rewards available to be redeemed.
In the event that the POS can not make live API calls then please refer to the Omneo Clienteling section of this document to read about an alternative method involving POS Call Backs.
Reward Balance API documentation can be found at Reward Balance endpoint.
Step 3 - Process the Reward Redemption
Performed via the Reward Redemption endpoint to redeem any available reward balance. The redemption will fail if attempted redemption amount is more than the member’s total available balance.
In the event that the POS can not make live API calls then please refer to the Clienteling portal section of this document to read about an alternative method involving POS Call Backs.
Redemption API documentation can be found at Redemption endpoint.
Step 4 - Apply the Reward Value
The total Reward Redemption value should be apportioned to each Transaction Line as a discount based on a weighted dollar value. The example below shows a $50 Reward Redemption applied to a $250 transaction (before redemption) resulting in a post discount total of $200:
| Original Value | Reward 'Discount' | Net Value | |
| Line Item 1 | $65.00 | $13.00 | $52.00 |
| Line Item 2 | $115.00 | $23.00 | $92.00 |
| Line Item 3 | $25.00 | $5.00 | $20.00 |
| Line Item 4 | $45.00 | $9.00 | $36.00 |
| $250.00 | $50.00 | $200.00 |
Step 5 - Store Omneo Identifiers
The following Omneo data is required in a Transaction Record:
- profileId
- redemptionId
Reversing Reward Redemptions
In the event that there is a POS transaction processing failure such as a declined credit card, the redemption can be reversed using the redemptionId that was returned via the Reward Redemption response.
Redemption Management
Create a Redemption
A Reward or Benefit Redemption can be performed via the Redemption endpoint using the Members ID to redeem any available reward balance. The redemption will fail if attempted redemption amount is more than the member’s total available balance.
In the event that the POS can not make live API calls then please refer to the Clienteling portal section of this document to read about an alternative method involving POS Call Backs.
Redemption API documentation can be found at Redemption endpoint.
Reversing a Redemption
A Redemption Reversal is initiated in events where a transaction has failed and the Redemption needs to be reversed, the most common use arises in the event of a credit card processing failure. For this reason a reversal is only permitted within 10 minutes of the originating Redemption and the process returns the Benefit or Reward redeemed to its original state (same expiry, value, etc).
In other events such as a Sale Return or Refund, then a Redemption Refund should be initiated as described in the section below.
A Redemption Reversal can be performed using the Redemption ID that was returned via the initial Redemption response via the Redemption Reversal endpoint. Redemption Reversal API documentation can be found at Redemption Reversal endpoint.
Refunding a Redemption
A Redemption Refund differs from a Redemption Reversal in that it creates a new Benefit or Reward with attributes (such as name and expiry) defined by the Tenants configuration. In this case it is the POS's responsibility to define the value of the Refund to account for full or part returns of the original transaction.
Redemption Refund API documentation can be found at Redemption Refund endpoint.
Staff Management
Staff records are associated with Transactions, events performed within the Omneo Clienteling portal and some Interactions. POS or HRIS platforms are the most accurate platforms to source Staff data.
POS is able to create, edit or delete Staff records in Omneo via the Staff endpoint.