Entities
In order to fully understand how our system functions, some knowledge of our entities and how they relate is required. A schematic representation of these entities and their relations can be found below. In this section, terms such as the Business Dashboard, Customer Dashboard, Business App and Customer App will be used. Explanations on those can be found here.
Accounts, Users and Shops
Piggy Clients first and foremost, consist of Accounts. Crudely put, a Piggy Client equals an Account. Each Client has their own Account, to which various other entities may be connected. In general - as both our Loyalty and Giftcards tools require this step - Piggy Clients connect one, or several, Shops to their Accounts, which can be both physical shops and web shops.
An Account is accessed by a User. A User can be created via https://business.piggy.eu/sign-up and can have access to several Accounts. If the User is not yet linked or invited to an Account, they will be prompted to create a new Account upon verification. More Accounts can be created here if necessary, via the Business Dashboard.
A Shop will be automatically created upon Account creation, which usually represents a location or webshop (for retail Clients). For now, a Shop is required for many API calls.
Contacts
The end-users of Clients are represented by Contacts. Contacts are provided with basic attributes, such as an email address, first name, last name, and so forth. In essence, the email address is the unique identifier for a Contact in the Piggy system (though they can be anonymised). The other attributes are optional, and can be complemented with custom attributes by the Client (or through API).
Aside from their email address, other Contact Identifiers can be created for a Contact. Primarily, they represent Loyalty Cards provided by the Clients, although any other identifier can be used to create Contact Identifiers (please contact us if this is desired). Further, Contacts can have credit balances, prepaid balances and subscriptions, but more on that later.
Rewards
Using our Loyalty & Rewards tools, Clients can create their own Rewards system. To do so, Clients create a list of Rewards for their Contacts. In the basis, Rewards consist of a required number of credits (or points), a title and an image or emoji. There are, however, some more advanced attributes – such as cost price and a claim limit – and filters. They can also be complemented with custom attributes, which mostly serves integrating purposes, so you might want to keep this in the back of your mind. Rewards are usually defined in the Business Dashboard, and integrations typically want to list and show the available Rewards, as well as perform the claiming of Rewards. The latter we call the creation of a Reward Reception.
Two types
Currently, there are two types of Rewards: Standard and Digital Rewards.
Upon claiming a Standard Reward nothing much happens in the Piggy system, except for deducting the required number of credits from the balance of the contact in question. This type of Reward is typically claimed in a physical store, where the Client witnesses the claiming and then manually presents the Contact with the item represented by the Reward. As such, they are quite simple, though any further actions can be implemented through our Automations tool (like a Webhook).
A Digital Reward is a bit more complex. Firstly, unique codes are linked to a Digital Reward. What exactly the code represents, is entirely unknown by the Piggy system, nor is it relevant for the Piggy system. Piggy merely acts as a messenger. Usually, however, the codes are generated in a web shop or something similar and any logic is configured there. Upon claiming a Digital Reward, one of these unique – and not yet issued – codes is sent to the Contact by email. This is a standard email set up by the Piggy system. This email can easily be disabled however, if a different manner of conveying the code to the Contact is needed.
Most, if not all, purposes can be served using the Rewards system in combination with either API or our Automations tool, in which the Webhookis probably most useful. We are, however, exploring different types of Rewards, including the following options:
- Request code upon claim: Instead of uploading the codes beforehand, set up an endpoint to which the Piggy system should perform an API call, which then returns a code.
- Generate code upon claim and post to endpoint: Piggy generates a unique code upon claiming and then post this code, along with other Reward information, to an endpoint of your choice, where you add this code to your system.
If you'd like to have the above options or have a different idea, please let us know so we can discuss.
Credits
Contacts can earn points – or as we call them: Credits – and so build up a Credit Balance at an Account (they are Account specific, and not usable at any other Account). For customer loyalty programs, this usually happens through purchases, where the purchase amount represents some number of credits. For employee programs, hours worked or performance based events are normally used to dish out credits. The transaction made to give out points is called a Credit Reception. How many credits a Contact receives, and any rules concerned with how they are calculated, can be configured in the Business Dashboard, through the use of Loyalty Rules. The saved up Credits can then be used to claim Rewards.
Loyalty Tokens
A Loyalty Token is, simply put, a Credit Reception not yet assigned to a specific Contact. The Contact needs to 'claim' the credits reserved by the Loyalty Token through a link. Until that time, no Credit Reception is created. This way of creating Credit Receptions is especially beneficial if it is not (yet) known for whom it should be created or if the process of identifying the Contact is too lengthy to do it that time, and they'd rather do it at their leisure. Another benefit is that no API call is needed to create a Loyalty Token, so it's also a perfect option if a steady internet connection is not present or cannot be guaranteed.
Read up on how to create Loyalty Tokens here.
Units
As Clients can issue credits on whatever they like, such as purchase amount, hours worked, certain events, or even calories burnt, kilometers travelled, etcetera, they need to define one (or more) Units, which represent the aforementioned. When creating a Credit Reception via API, it's therefore necessary to define which Unit is being used, and the accompanying value (e.g. Unit equals 'purchase amount' and value being '25.00').
Webhooks
Using our Automation tool in the Business Dashboard, one can set up Webhooks for certain events. The payload of said event will then be sent to the specified endpoint. For more information, see our page concerning Webhooks.
Giftcards
Piggy Clients can also make use of our Giftcards tool. Giftcards, which in their basis consist of a QR-code/hash and a balance, exist in either digital or physical form. There is no relation between Giftcards and Contacts, as physical Giftcards can be reused, and are therefore anonymous. For Giftcards linked directly to a Contact, see our Prepaid Balance tool.
Piggy Clients connect a Giftcard Program to their Shops. Giftcard Programs can, like so many other entities, be created in the Business Dashboard. Simply log into the Business Dashboard and go to Giftcards. If a message pops up saying you need to talk to Sales, please contact us. We can enable the necessary modules for you. Once your Giftcard module is activated, a Giftcard Program can easily be created here. You will then need to link your Shop(s) to your Giftcard Program under Linking.
Devices
Piggy Clients may connect one or more Devices to their Shops. A Device can be linked to only one Shop. These Devices are smartphones and/or tablets running our Business App (iOS or Android), and are therefore solely used at physical locations. Devices can be created and linked in the Business Dashboard.
Registers
Registers represent third-party POS registers of Piggy Clients. Registers are the cornerstone for building POS integrations. Piggy Clients can link Registersto Devices in our dashboard. The Register contains the API key that's used for the integration, and as their Shop specific, for each Shop a Register needs to be created. Registers can be created in the Business Dashboard.
OAuth Clients
OAuth Clients aren't so much entities as the other ones mentioned here, but as they're instrumental in building an integration using OAuth Clients, it's important to mention them as well. OAuth Clients can be created in the Business Dashboard and then used to request an access token for API calls.
Schematic Overviews
Loyalty: Entities & Relations
Giftcards: Entities & Relations
