Credit Receptions
Credit Receptions are the backbone of the Piggy Loyalty system. It lets our end-users collect credits and it's therefore the basis for virtually every loyalty integration. Before starting to build your integration, we ask you read the recommended flows.
Refunds and reversing Credit Receptions
At times, initially issued credits need to be reverted, when an order was refunded for instance. In such a case, it's important to note that creating a Credit Reception with a negative unit_value is inadvisable. Due to the possibility of Loyalty Rules dependent on variables (e.g. time-based filters or Tier-based filters) being present, the resulting number of credits issued can differ from the initial transaction to be corrected.
Instead, use the Reverse Credit Reception API call to reverse an initial transaction.
Partial refunds
In case of partial refunds, it gets a bit more tricky. To account for time-based and attribute-based filters as best as possible, we recommend to calculate the percentage of the order that was refunded, take that percentage of the credits initially issued, and create a Credit Reception with that negative amount of credits (do not useunit_value (e.g. initial transaction of €50.00 issued 80 credits, €20.00 was refunded, so new Credit Reception for -32 credits).
Create Credit Reception
In creating a Credit Reception, you may either choose to set the unit_value alongside the relevant unit_name, or the credits, or both. In any case, one of either must be set. If only purchase amount is set, then the number of credits are determined by any Loyalty Rules set on the Loyalty Program. Loyalty Rules are rules that Clients can set in their Business Dashboard, which can apply multiplication or rounding rules for instance.
To mimic in-store behaviour as closely as possible, we recommend setting unit_nameand unit_valueonly. If unit_nameis not set, then the default unit will be used (purchase_amount).
If, however, the number of creditsto be given should be set explicitly - for instance when the Credit Reception doesn't concern a transaction or a (partial) refund needs to be made - then the credits can be set. In this case, unit_valueis optional.
https://api.piggy.eu/api//credit-receptionsBearer {{ api_key }}application/jsonBody
contact_uuidstringREQUIREDcreditsnumberREQUIRED_IFunit_valuenumberREQUIRED_IFunit_namestringOPTIONALcontact_identifier_valuestringOPTIONALpos_transaction_uuidstringOPTIONAL1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
"data": {
"type": "credit_reception",
"contact_identifier": null,
"contact": {
"uuid": "123",
"email": "john@doe.com",
"credit_balance": {
"id": 2625740,
"balance": 1642
}
},
"shop": {
"id": 15,
"uuid": "123123",
"type": "physical",
"name": "Amsterdam Pop-up Store",
"address": {
"id": 59,
"shop_id": 15,
"street": "Sesame Street",
"housenumber": 12,
"postalcode": "9999YZ",
"city": "Duckburg",
"state": "NH",
"country": "NL",
"latitude": null,
"longitude": null,
"house_number": null,
"postal_code": null
}
},
"credits": 10,
"created_at": "2023-11-06T09:12:32+00:00",
"uuid": "294183c2-20f2-4f86-a5e5-17e71c4b0660",
"unit": {
"id": 112,
"name": "test",
"label": "Calories",
"prefix": "",
"is_default": true
},
"unit_value": null,
"someAttribute": null,
"someAttribute2": null,
"someAttribute21123": null
},
"meta": {}
}
}Code
Message
100310085503160003600071015600015504610276001Push Credit Reception to End Screen
If you're using a 'With Device' flow, but prefer to create the Credit Reception on the Register, the Push Credit Reception to End Screen call can be used to send the created Credit Reception data to the iPad, where the Contact can then claim Rewards.
https://api.piggy.eu/api//credit-receptions/{credit_reception_uuid}/pushBearer {{ api_key }}application/jsoncredit_reception_uuidstringREQUIRED1
2
3
4
{
"data": [ ],
"meta": [ ]
}Code
Message
1003102855024Calculate Credits
Without actually creating a Credit Reception, this API call can be used to calculate how many credits would be issued if a Credit Reception was to be made with the given values. Please note, that there is a (small) possibility of a divergence in credits between the calculation and the actual Credit Reception, if loyalty rule filters are in place that are time-based (e.g. a happy hour rule).
https://api.piggy.eu/api//credit-receptions/calculateBearer {{ api_key }}application/jsoncontact_uuidstringOPTIONALunit_valuenumberREQUIREDunit_namestringOPTIONAL1
2
3
4
5
6
{
"data": {
"credits": 10240
},
"meta": {}
}Code
Message
100310085503160007