Orisha Commerce

Introduction

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 Engage they can leverage Engage’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 Engage 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. Please check with the Orisha Commerce team to see if the version you are using is compatible with the Voyado Engage integration.

This integration between Orisha Commerce and Engage covers the following areas:

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

Prerequisites

To set up your integration you’ll need:

A login to Engage
An API key for the Engage API
A Treazure account

If you are using multiple markets in Engage, 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 Engage is called a “contact”. In Engage 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 Engage 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 Engage, 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 Engage.

Orisha Commerce is able to search for contacts in Engage 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 Engage 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 Engage API supports this. This is an example swagger page for the Engage 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 Engage 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 Engage 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 Engage 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.

https://mintcdn.com/voyado-partners/uzZabf3Vznawr8GM/icons/developer-link.png?fit=max&auto=format&n=uzZabf3Vznawr8GM&q=85&s=edcf2da0b17a913e2d7896d3f6e9aeb3

Learn about the /contacts endpoint

Orisha Commerce now fetches the contact’s full data from Engage, 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 Engage. 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 Engage, syncing the new values. See the Engage 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 Engage multichannel promotions. Read about the Engage API for promotions here:

Learn about the promotions endpoints

Creating a promotion

An Orisha Commerce promotion that uses data from Engage needs to be set up in both systems. The use of a unique ID (external promotion code) allows a Treazure voucher and a Engage multichannel promotion to be connected. Engage 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 an Engage multichannel promotions to a Treazure voucher.

Create a multichannel promotion in Engage

In Engage, 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 Engage 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 Engage 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 Engage 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 Engage and Treazure, the Engage promotion should now turn up for the specified customers when they are identified in the POS and their data is fetched from Engage. As for any external promotion in Engage, 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 Engage.

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 Engage /receipts endpoint. This is how that looks in the payload:

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

See the Engage documentation for more information:

Learn about registering a purchase

Handling receipts

A vital part of the integration between Orisha Commerce and Engage 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 Engage 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 Engage API using a contact’s contact ID as the key. Again, see the Engage documentation for details.

Engage 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 Engage will act as point follower. Read more about point follower here:

Learn about point follower

When Engage 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 Engage does not know about. So Engage 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 Engage.For this to work, point follower functionality must be enabled in Engage. Enabling this creates a connection between Engage and Treazure through Engage’s iPaaS, a middleware used for point syncing. It pulls the point balances from Treazure and updates them in Engage 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 Engage

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

2. Adding points in Treazure through Engage

When Engage is point follower, points added manually in the Engage UI or through Engage 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 Engage’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 Engage.When doing a remote points adjustment like this, you can add a description in the Engage 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, Engage 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 Engage UI.Since only the point balance is updated by the hourly sync, a webhook needs to be configured in Engage to fetch the full points history. This is done by your Voyado team in the Rewards module in the Engage 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 Engage through the point migration service. This is useful for customers who have a existing loyalty program in Treazure and want to go live with Engage as point follower. See how this is done here.

POS partners

Introduction

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

Engage as point follower

Learn about point follower

Learn about the point migration service

POS partners

​Introduction

​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

​Engage as point follower

Learn about point follower

Learn about the point migration service

Introduction

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

Engage as point follower