Orisha Commerce

Voyado Customer Engagement + Orisha Commerce integration

Orisha Commerce (formerly Cow Hills Retail) is a Dutch company providing omnichannel point-of-sale software for retailers. They are fully cloud-based and their POS can run on all kinds of hardware, including iOS and android, allowing staff to, for example, walk around the store and process customer’s purchases on the spot.

Orisha Commerce already have access to loyalty and promotion functions through their promotions engine, Treazure. But by using a standard POS integration with Voyado Customer Engagement they can leverage Customer Engagement’s automation capabilities and more to deliver a much richer experience. Note that this is a point-follower integration. This means that Treazure is the arbitrator of points and Customer Engagement will only send point updates whenever that happens in its system.

The integration is only supported by later versions of the Orisha Commerce / Treazure software. Check with the Orisha Commerce team to see if the version you are using is compatible with the Voyado Customer Engagement integration.

This integration between Orisha Commerce and Customer Engagement covers the following areas:

Identifying a contact
Registering a contact
Updating a contact
Sending transactions (receipts) to Customer Engagement
Assigning personal promotions
Applying promotions to purchases
Enabling Customer Engagement to act as point follower

Prerequisites

To set up your integration you’ll need:

A login to Customer Engagement
An API key for the Customer Engagement API
A Treazure account

If you are using multiple markets in Customer Engagement, these can be set up to work from a single Orisha Commerce instance.

Configuration

Orisha Commerce themselves take care of the configuration. Contact them for more details.

Contact page for Orisha Commerce

Contacts

An end-user in Customer Engagement is called a “contact”. In Customer Engagement there are many contact types: “Contact”, “Member” as well as custom types based on a retailer’s specific requirements. Orisha Commerce is able to search for contacts in Customer Engagement without specifying the contact type. This allows a search to be made for a contact, regardless of their contact type, using only an address or mobile number. However, all contacts registered and updated in-store through the Orisha Commerce POS will be saved as type “Member”. Your goal should be to have all your end-users as contact type “Member”. This allows them to be awarded loyalty in form of points and vouchers, making use of the power of Customer Engagement, and allows you the retailer to gather more useful data. All contact data displayed in the Orisha Commerce POS can be updated and saved. Custom attributes can also be added in the POS and then synced back to Customer Engagement.

Orisha Commerce is able to search for contacts in Customer Engagement without specifying the contact type. However, all contacts registered and updated in-store through the Orisha Commerce POS will be of type “Member”.

Identifying a contact

Orisha Commerce uses v1 of the Customer Engagement API endpoint /contacts. Version 1 is used because searching based on address and postal (zip) code is something still commonly done in retailers in the Netherlands amd v1 of the Customer Engagement API supports this. This is an example swagger page for the Customer Engagement API:

https://voyadodemoecom.voyado.com/api/v2/ui/index

Select “Voyado API v1” in the top-right dropdown to access the version 1 API. Now select “Contacts” and the first option “Get contacts through query”. Create your search query with the details you will use, and send it as the query parameter. For example, your query might be: ZipCode:“111 11” AND Street:“Examplegatan 5” The full API call in this example is then:

https://voyadodemoecom.voyado.com/api/v1/contacts?query=ZipCode%3A%22111%2011%22%20AND%20Street%3A%22Examplegatan%205%22

You must use version 1 of the /contacts endpoint in the Customer Engagement API to check if a contact exists. The contact type is not needed. Note that /contacts is the only v1 endpoint used; everything else in this integration uses the Customer Engagement v2 API.

Upon making this request, you will find out if this contact is already in the system, or if they are not. Here are the two situations and what happens in each:

The contact is already in the system

In this case, data in this format will be returned:

{
  "totalResults": 1,
  "results": [
    {
      "firstName": "Example",
      "lastName": "Examplesson",
      "email": "example@example.com",
      "socialSecurityNumber": null,
      "mobilePhone": null,
      "zipCode": "111 11",
      "street": "Examplegatan",
      "city": null,
      "externalId": "11de71a1-4bc6-4a11-a4ef-8ebac0480b11",
      "id": "d0011111-45f2-492f-8d31-aec500a07f11",
      "contactType": "Member",
      "memberNumber": "01010101010101"
    }
  ]
}

The value id returned contains the unique contact ID and will be used in the display step below.

The contact can't be found in the system

In this case, Orisha Commerce will create a new contact in Customer Engagement as contact type Member.This creates a contact and returns a data set containing id, their unique contact ID value.

Displaying a contact’s data

Now that the contact has been identified, Orisha Commerce takes their unique ID and performs a lookup against the /contactoverview endpoint in version 2 of the API.

Learn about the /contacts endpoint

Orisha Commerce now fetches the contact’s full data from Customer Engagement, containing such information as address, target audience, promotions, tier levels, purchase history, points and consents. This is used to populate the POS, depending on what the retailer wants to see. Orisha Commerce can also fetch extra contact attributes from Customer Engagement. These are configured under “sections” in Orisha Commerce.

Extra attributes are read-only in the POS and can’t be changed from there.

Updating a contact

If a contact’s details are updated in the POS, Orisha Commerce will send an update to Customer Engagement, syncing the new values. See the Customer Engagement API documentation to learn how this is done:

Learn about the /contacts endpoint

Promotions

In Treazure, coupons and vouchers are two different concepts.

Vouchers are connected to a customer’s profile and turn up automatically in the POS.
Coupons need to be physically taken to the store either on a mobile screen or on paper.

In this integration only Treazure vouchers will be used, together with Customer Engagement multichannel promotions. Read about the Customer Engagement API for promotions here:

Learn about the promotions endpoints

Creating a promotion

An Orisha Commerce promotion that uses data from Customer Engagement needs to be set up in both systems. The use of a unique ID (external promotion code) allows a Treazure voucher and a Customer Engagement multichannel promotion to be connected. Customer Engagement handles assignments of the promotion to the contact or contacts, and Orisha Commerce handles the actual price rule (20% off, 3 for 2, 20 kr discount, or whatever). Here’s how to connect a Customer Engagement multichannel promotions to a Treazure voucher.

Create a multichannel promotion in Customer Engagement

In Customer Engagement, go to Promotions / Active and then select the New promotion button. From the dropdown select Multichannel promotion.

This creates a new multichannel promotion.

Now you configure the promotion. Make it “Can be used in store” and select “External promotion code” in the dropdown. Decide on an external promotion code and fill it in.Then copy this external promotion code value and switch over to Treazure.

Create a voucher definition in Treazure

In Treazure, go to Voucher definition and select ”+ Add” to create a new voucher.

Configure your new voucher.

Now enter the external promotion code you copied from Customer Engagement into the Code box.Change Type to CRM since this is not a Treazure voucher but an external one.

Create a filter group in Treazure for the voucher

A voucher in Treazure is not linked directly to a promotion, it is instead added to a filter group first.So create a filter group of type “Voucher”.

Give it a Code (name) and a Description, and save it.

Select “Add” and select the Treazure voucher you made earlier from the list. Hit “Save”.

Now your filter group is ready.

Create a promotion and add the filter group

In Treazure, create a new promotion.

Give your promotion a name and description. Fill in the other fields.Under Article filter add the articles included in the promotion (write ALL for all).Under Voucher filter add the filter group you just made.

Add whatever other settings you need to your promotion under Promotion settings. Add the stores and validation period. Now your promotion is ready to use.

Since Customer Engagement uses an expiry date for its multichannel promotion, when you make your promotion in Treazure, you must set it to a date far in the future. This enables the Customer Engagement expiry date to be the one that decides if a promotion is still active or not.

Using a promotion

If the setup has been performed correctly in both Customer Engagement and Treazure, the Customer Engagement promotion should now turn up for the specified customers when they are identified in the POS and their data is fetched from Customer Engagement. As for any external promotion in Customer Engagement, the external promotion code is used by the POS to fetch the price rule from the external system (from Treazure, in this case). The Orisha Commerce POS can also show the normal promotions from Treazure that are not connected to any promotions in Customer Engagement.

Redeeming a promotion

Redeeming a promotion is currently done through the receipt. The discount is applied across all items and then the promotion’s unique ID is added to the “usedPromotions” array in the payload that is sent to the Customer Engagement /receipts endpoint. This is how that looks in the payload:

{
...
    "usedPromotions": [{
        "promotionId": "1234dfaa-31c5-2e22-bb88-7fffc5fe8bf7"
    }]
}

See the Customer Engagement documentation for more information:

Learn about registering a purchase

Handling receipts

A vital part of the integration between Orisha Commerce and Customer Engagement is handling receipts. Learn more here:

Handling receipts for purchases and returns

Handling purchases

If a customer makes a purchase, Orisha Commerce sends that receipt to the /receipts endpoint of the Customer Engagement API using contact ID as the identifier. If there is a promotion or discount used, it is first applied to as a discount across each line item. The relevant promotion ID will also be included on the receipt.

Handling returns

If a customer makes a return, Orisha Commerce sends that receipt to the Customer Engagement API using a contact’s contact ID as the key. Again, see the Customer Engagement documentation for details.

Customer Engagement as point follower

In this integration Treazure (Orisha Commerce’s Loyalty CRM) is the master of points and vouchers, allowing customers to buy items with points, create vouchers directly on the fly and also have different type of points-buckets. This means that Treazure decides what the points are, and Customer Engagement will act as point follower. Read more about point follower here:

Learn about point follower

When Customer Engagement is acting as point follower for Treazure, there are the three cases to consider:

1. Syncing point balance from Treazure (hourly update)

Since Treazure is the point master, point changes may occur that Customer Engagement does not know about. So Customer Engagement has to constantly sync its point balances to the values in Treazure. This is done on a schedule. Every hour, the current point balance for every contact is fetched from Treazure and sent to an specific API endpoint in Customer Engagement.For this to work, point follower functionality must be enabled in Customer Engagement. Enabling this creates a connection between Customer Engagement and Treazure through Customer Engagement’s iPaaS, a middleware used for point syncing. It pulls the point balances from Treazure and updates them in Customer Engagement using the endpoints below.

Endpoint in Treazure

https://[client].posengine.[environment].cloud/api/v1.0/LoyaltyVault/Balances/Get

Payload

{
  "mutatedFrom": "[[todays date - 2 hours]]",
  "mutatedTo": "[[todays date + 2 hours]]",
  "loyaltyPointDefinitionId": "[[loyaltyId]]"
}

https://[client].posengine.[environment].cloud[href]/result

Response href in Customer Engagement

https://[client].voyado.com/api/v2/point-accounts/balances

2. Adding points in Treazure through Customer Engagement

When Customer Engagement is point follower, points added manually in the Customer Engagement UI or through Customer Engagement automations are not added directly. A request is instead sent to Treazure, using the following webhook provided by Treazure. For this to work, you need to activate Customer Engagement’s webhook functionality.

Endpoint in Treazure

https://[client].posengine.[environment].cloud/api/v1.0/LoyaltyVault/Account/[contactId]/Transaction

Here, [client] and [environment] depend on your setup, and [contactId] is the GUID for the specific contact.The webhook returns the new point balance for that specific contact when is then set directly in Customer Engagement.When doing a remote points adjustment like this, you can add a description in the Customer Engagement UI. The Treazure API, however, limits the length of this description to 100 characters. Anything longer will cause an error and the update will not be accepted. So be sure to keep your description under 100 characters.

3. Fetching points history from Treazure

As well as fetching the point balances, Customer Engagement can fetch the total point history for a contact. This is useful, for example, for displaying the total points history on the contact card in the Customer Engagement UI.Since only the point balance is updated by the hourly sync, a webhook needs to be configured in Customer Engagement to fetch the full points history. This is done by your Voyado team in the Rewards module in the Customer Engagement back-end. The webhook looks like this:

Endpoint in Treazure:

https://[client].posengine.[environment].cloud/api/v1.0/LoyaltyVault/Account/[contactId]/LoyaltyPrograms/[loyaltyId]/History

It’s also possible to migrate points from Treazure to Customer Engagement through the point migration service. This is useful for customers who have a existing loyalty program in Treazure and want to go live with Customer Engagement as point follower. See how this is done here.

POS partners

Voyado Customer Engagement + Orisha Commerce integration

Prerequisites

Configuration

Contact page for Orisha Commerce

Contacts

Identifying a contact

Displaying a contact’s data

Learn about the /contacts endpoint

Updating a contact

Learn about the /contacts endpoint

Promotions

Learn about the promotions endpoints

Creating a promotion

Using a promotion

Redeeming a promotion

Learn about registering a purchase

Handling receipts

Handling receipts for purchases and returns

Handling purchases

Handling returns

Customer Engagement as point follower

Learn about point follower

Learn about the point migration service

​Voyado Customer Engagement + Orisha Commerce integration

​Prerequisites

​Configuration

Contact page for Orisha Commerce

​Contacts

​Identifying a contact

​Displaying a contact’s data

Learn about the /contacts endpoint

​Updating a contact

Learn about the /contacts endpoint

​Promotions

Learn about the promotions endpoints

​Creating a promotion

​Using a promotion

​Redeeming a promotion

Learn about registering a purchase

​Handling receipts

Handling receipts for purchases and returns

​Handling purchases

​Handling returns

​Customer Engagement as point follower

Learn about point follower

Learn about the point migration service

Voyado Customer Engagement + Orisha Commerce integration

Prerequisites

Configuration

Contacts

Identifying a contact

Displaying a contact’s data

Updating a contact

Promotions

Creating a promotion

Using a promotion

Redeeming a promotion

Handling receipts

Handling purchases

Handling returns

Customer Engagement as point follower