> ## Documentation Index
> Fetch the complete documentation index at: https://partner-integrations.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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. 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.
## 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:
```http theme={null}
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:
```http theme={null}
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:
In this case, data in this format will be returned:
```json theme={null}
{
"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.
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.
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:
## 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:
### 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.
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.
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.
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.
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:
```json theme={null}
{
...
"usedPromotions": [{
"promotionId": "1234dfaa-31c5-2e22-bb88-7fffc5fe8bf7"
}]
}
```
See the Engage documentation for more information:
## Handling receipts
A vital part of the integration between Orisha Commerce and Engage is handling receipts. Learn more here:
### 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:
When Engage is acting as point follower for Treazure, there are the three cases to consider:
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.
```http Endpoint in Treazure theme={null}
https://[client].posengine.[environment].cloud/api/v1.0/LoyaltyVault/Balances/Get
```
```json Payload theme={null}
{
"mutatedFrom": "[[todays date - 2 hours]]",
"mutatedTo": "[[todays date + 2 hours]]",
"loyaltyPointDefinitionId": "[[loyaltyId]]"
}
```
```http theme={null}
https://[client].posengine.[environment].cloud[href]/result
```
```http Response href in Engage theme={null}
https://[client].voyado.com/api/v2/point-accounts/balances
```
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.
```http Endpoint in Treazure theme={null}
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.
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:
```http Endpoint in Treazure: theme={null}
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.