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.


Accounts and Shops

Piggy Merchants first and foremost, consist of Accounts. Crudely put, a Piggy Merchant equals an Account. Each Merchant has their own Account, to which various other entities may be connected. In general - as both Loyalty and Giftcards require this step - Piggy Merchants connect one, or several, Shops to their Accounts, which can be both physical shops and web shops.

An Accounts is accessed by a User. A User can be created via https://business.piggy.eu/sign-up. Once you've registered a User, an email will be sent to you. Following the instructions in the email, you can create an Account. If you ever want to create more Accounts, you can do so by logging into the Dashboard, selecting your current Account, then going to Management, then Account. More Accounts can be created here if necessary.

During the Account creation, you are asked what type of shop you have. For whichever type you've chosen, a Shop will be created upon Account creation. You can simply use this Shop. If you have need of more Shop, you can create more in the Business Dashboard. Go to Management, then Shops to create more. Here, you may also find each Shop's shop_id. This ID can be found when clicking on the Shop here, the ID will appear in the URL.



Loyalty

Piggy Merchants connect a Loyalty Program to their Shops. Once customers of Piggy Merchants join the Merchant’s Loyalty Program, a Member is created for that customer. The Member, which in its basis consists of an email address, can have one or more Cards, either physical or digital. Receiving credits is represented by Credit Receptions, whereas claimed rewards are represented by Reward Receptions. Credit Balances store current amount of credits (i.e., Σ(Credit Receptions) - Σ(Reward Receptions)).

Loyalty Programs can, like so many other entities, be created in the Business Dashboard. Simply log into the Business Dashboard and go to Loyalty. 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 Loyalty module is activated, a Loyalty Program can easily be created here. You will then need to link your Shop(s) to your Loyalty Program under Linking. Rewards can be created in the Program as well. Note that each of the Rewards needs to be linked to a Shop separately.



Giftcards

Piggy Merchants connect a Giftcard Program to their Shops. Giftcards, which in their basis consist of a QR-code / hash, are added to the Giftcard Program and exist in either digital or physical form. There is no relation between Giftcards and Members, as physical Giftcards can be reused.

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. Different from the Loyalty module, you actually link Groups instead of Shops to a Giftcard Program. Groups are nothing more than collections of Shops. Whenever Shops are created, a individual Group is created automatically for that specific Shop, and the Shop is added to the 'All' group, which - as you might've guessed - consists of all of your Shops. The individual and All groups aren't editable, but more Groups may be created to generate any grouping of Shops.

The whole 'Groups' entity doesn't really play a role in building integrations, so you may disregard this for the most part.

Giftcards can be created either by using the Create Giftcard API call, or by using the 'Send Digital Giftcard' in the Business Dashboard. You access this functionality by going to 'Cards' in your Giftcard Program and clicking the plus button. This will create and send a digital giftcard by email.



Marketing

Piggy Merchants can create a Marketing Program, which is - in its basis - completely separate from the other entities (barring Accounts). To the Marketing Program, so-calledRecipients can be added. They're very much like Members, but they're program-specific. Members aren't much more than an email address, although program-specific Custom Attributes can be created. A Piggy Merchant may also synchronise their Marketing Program with (one of) their Loyalty Program(s). On each Loyalty Transaction, the Member will then be synchronised with the respective Marketing Program recipient (or one will be created if none exists).

Marketing Programs can, like so many other entities, be created in the Business Dashboard. Simply log into the Business Dashboard and go to Marketing. If a message pops up saying you need tos talk to Sales, please contact us. We can enable the necessary modules for you.

Once your Marketing module is activated, a Marketing Program can easily be created here. You can then synchronise your Marketing Program with your Loyalty Program under Sync. Under Recipients, you can (bulk) import your Marketing Recipients. You can create and sync Custom Attributes under Custom Attributes. For more information on Custom Attributes, read about the Custom Attribute entity further down the page.



Custom Attributes

Custom Attributes are program-specific properties that can be created for both Members and Recipients. They can be anything, from their first name, to their pet's birthday, their credit balance, to the date of their last visit. The Piggy Merchant can create highly customisable attributes, or use one of our presets. Custom Attributes are, as mentioned, program-specific. This means that once you've created the 'First name' attribute for your Members in a Loyalty Program, it has not been created for your Recipients in your Marketing Program or your Members im a different Loyalty Program. You can, however, synchronise them with one another once they're created for both (or more) Programs.

Custom Attributes can be created in the Business Dashboard. They are program-specific, which means that they need to be created for each Loyalty and Marketing program for which they're to be available. Go to the Program for which you'd like to create Custom Attributes, click on Custom Attributes and click the '+' button. You can choose to create your own attribute, or use on of our presets. You can still customise a preset after creation. In creating attributes, please choose the 'name' and data type with care. They cannot be changed afterwards, and are instrumental to syncing and updating through API calls.

There are currently seven data types for Custom Attributes, and it's important that the data type of a Custom Attribute sent in a PUT call matches the data type set in the Business Dashboard:

  • Text - string
  • Number - number
  • Select - array
  • Multi-select - array
  • Birthdate - date, Y-m-d
  • Date - date, Y-m-d
  • DateTime - dateTime, ISO 8601 (e.g., 2021-02-28T21:40:53+00:00)

You can also sync your Custom Attribute from another Custom Attribute, Customer property or System Property. Click on the Custom Attribute, and open the Synchronisation tab. You can choose from the aforementioned properties here. Other Custom Attributes are those that you've created in one of your programs. Customer Properties are values that are set on a Customer Profile. System Properties are (calculated) properties taken from the programs, such as the credit balance or last visit date. In syncing your Custom Attributes, please take note of a few things: (1) a Custom Attribute can be synced from one other property, (2) that property needs to have the same data type (for (multi-)select attributes, the available options should also be the same), and (3) you can only sync from a property, not to.

Formatting

In updating the Custom Attributes of a Member or Recipient using the API, you'll need the name of the attribute to be set and the value to which it must be set. Format the Custom Attributes in the body of a PUT call as follows:

{ "custom_attributes": { "name": "John Doe", "numberOfPets": 2, "favouriteAnimal": "Dog", "ownsAnimals": [ "Dog", "Fish" ], "birthDay": "1980-01-23", "firstVisit": "2021-03-11T16:30:30+00:00" } }


Devices

Piggy Merchants 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 Store App (iOS or Android).

Devices can be created in the Business Dashboard. Simply log into the Business Dashboard, go to Management, then In-Store Management (this option only appears if you have a Physical Shop added to your Account) and go to Devices. Go to Link codes and generate a code here. This code can then be entered into the Store App to link the Device. It will then show up at Linked devices.



Registers

Registers represent third-party POS registers of Piggy Merchants. Registers are the cornerstone for building POS integrations. Piggy Merchants can link Registersto Devices in our dashboard.

Registers can be created in the Business Dashboard. Simply log into the Business Dashboard, go to Integrations, then POS-Integration and go to Cash registers. Create a new Register here, give it a name (for internal purposes) and an ID, and select a Shop to which it must be linked. An API-key will be generated for you, which you can use in the integration.



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. Simply log into the Business Dashboard, go to Integrations, then OAuth Clients and create one here. Using the details provided there, an access token can be requested. For further information on using the OAuth Clients and requesting an access token, please see Authorization.



Customers vs Members

Whenever an end-user saves credits at any Loyalty Program for the first time - that is, the email address used was hitherto unknown - a Member can be created for that end-user. This Member can only be called upon by a Piggy Merchant if the Member in question has at least one Credit Reception at (one of) his Loyalty Program(s). The Piggy Merchant can then go ahead and add custom properties to their Member data (only accessible for that Piggy Merchant).

An end-user can also decide to create a Customer for their email address. They do so by creating an account in the Piggy Customer App or using the Piggy Customer Dashboard. This distinction between Customers and Members exists for the good of separation of data, for legal and privacy reasons.



Schematic Overviews

Loyalty: Entities & Relations

Loyalty Relations

Giftcards: Entities & Relations

Giftcards Relations

Related