How do I configure an integration with Piggy?

This document describes what is currently supported in the integration with Piggy and how it must be configured.

Piggy works with contacts and identifiers. An identifier is essentially a loyalty card that can be used to look up the customer.
The saved and redeemed balance is linked to the contact, not to the identifier.
A contact may have multiple identifiers.

Saldo redemption is done through rewards. Rewards can be configured in advance in Piggy. When a customer wants to redeem saldo, this is done by redeeming a complete reward.

Configuration inside Piggy

API integration

To allow RetailVista to connect to Piggy, an API integration must be enabled.
For this, a POS integration must be created.

Go to the menu in the top-right corner (three dots), select Integrations, and then POS.

Select Link POS at the top-right and add a new POS, for example:

Then go to the tab Personal access tokens and create a personal access token.
Important: store this token. It cannot be viewed again later and will be required for configuration in RetailVista.

Rewards

Currently, RetailVista only supports redeeming rewards that apply a discount to the transaction (redeeming saldo).
Giving away free articles through Piggy rewards is not yet supported.

To configure this, several fixed attributes must be created in Piggy.
Go to the radar icon in the top-right, select Attributes, and then choose Reward at the top-right to create reward attributes.

The following attributes must be created:

Name	Data type	Options
discount_type	Select	Value: Amount — Internal value: absolute_discount Value: Percentage — Internal value: percentage_discount
discount_value	Number
apply_to	Select	Value: Entire order — Internal value: entire_order Value: Specific product — Internal value: specific_product
product_barcode	Number

The result should look like this:

Creating a new reward

To create a new reward, go to Loyalty and then Rewards:

Enter a clear title, for example “1 euro discount”.
One point normally equals one cent, so for a 1 euro discount set the required points to 100.

On the tab Advanced, the attributes created earlier are displayed.
Set discount_type to 'Amount' and apply_to to 'Entire order'.
At discount_value, enter the discount in cents.
For a 1 euro discount, enter 100:

Configuration inside RetailVista

Loyalty card connector

A loyalty card connector must be created in RetailVista as follows:

The regular expression is used to recognise the loyalty card (identifier in Piggy).
It is important to coordinate with Piggy which identifiers may be used.
It is not recommended to use numeric identifiers that may overlap with article numbers or barcodes.
A safe option is an alphanumeric code of 8 characters, which fits the regular expression shown above.

Provider Type must be Piggy.
Enter the URL exactly as shown above and specify the personal access token under Advanced settings using:
apitoken=[xxxxxx] where xxxxxx is the token created earlier in Piggy.

Regular expression: ^[a-zA-Z0-9]{8}$
Provider Type: Piggy
Url: https://api.piggy.nl/api/v3/register

Loyalty card type

A loyalty card type must also be created.
This type is used, for example, to print the saved and redeemed saldo on the POS receipt.
Set both the value and redeem value to 0.01, so that one point equals one cent:

Settings

Two settings are important:

Point of Sale section, tab Loyalty:
Set the External discount connector to the connector created above.

Loyalty section, tab eLoyalty:
Set the loyalty card type to the type created above so it will be used for Piggy loyalty cards.

POS

Synchronize the POS and restart it.
After this, scanning a Piggy identifier should be recognised.

Through Loyalty → Claim loyalty vouchers the rewards configured in Piggy will be visible.
If sufficient saldo is available, rewards can be activated here for redemption:

If desired, this screen can also be opened via a touchscreen button.

It is also possible to open this screen automatically after scanning a loyalty card when a certain point threshold is reached.
To enable this, set Minimum value for redemption in the loyalty card type in RetailVista.
For example, if the lowest reward is 1 euro and the minimum value for redemption is set to 1 euro, then this screen will open automatically when the loyalty card has more than 100 points.
This also indicates to the cashier that enough saldo is available to redeem a reward.