Credit Receptions
Credit Receptions have been largely replaced by top level entities such as Orders, Visits and Bookings. Please use those instead. If your use case doesn't fit a
Credit Receptions
Credit Receptions have been largely replaced by top level entities such as Orders, Visits and Bookings. Please use those instead. If your use case doesn't fit any of these, please contact us at dev@leat.com to discuss.
Credit Receptions are instances of loyalty points transactions in the 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.
When using purchase amount as unit_name, use purchase amount as a float for unit_value (e.g. €10,40 translates to unit_value: 10.40).
POST
https://api.piggy.eu/api//credit-receptionsHeaders
Authorization
Bearer {{ access_token | api_key }}
Accept
application/json
Body
shop_uuid string
REQUIRED
The UUID of the Shop you want to create the Reward Reception for.
contact_uuid string
REQUIRED
The UUID of the Contact for whom the Credit Reception is to be created.
credits number
REQUIRED_IF
Number of Credits, required if unit_value is not set. Overrides any Loyalty Rules.
unit_value number
REQUIRED_IF
Value of the Unit to be given. This parameter is required if credits is not set. Subject to any Loyalty Rules.
unit_name string
OPTIONAL
Name of the Unit for the corresponding value. If both unit_name and credits are not set, then the default unit (purchase_amount) is used.
contact_identifier_value string
OPTIONAL
The value of the Contact Identifier linked to the Contact for whom the Credit Reception is to be created.
pos_transaction_uuid string
OPTIONAL
The UUID of the POS transaction that you want to link the Credit Reception to.
Response Example
{
"data": {
"type": "credit_reception",
"contact_identifier": null,
"contact": {
"uuid": "123",
"email": "spongebob@bikinibottom.sea",
"credit_balance": {
"id": 2625740,
"balance": 1642
}
},
"shop": {
"id": 15,
"uuid": "123123",
"type": "physical",
"name": "Krusty Krab",
"address": {
"id": 59,
"shop_id": 15,
"street": "Conch Street",
"housenumber": 12,
"postalcode": "9999YZ",
"city": "Bikini Bottom",
"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
1003
Invalid input.
1008
Shop not found.
55031
Contact not found.
60003
Contact identifier not found.
60007
Unit not found.
1015
Maximum amount of credits reached.
60001
Credit reception creating in progress.
55046
No default unit found.
1027
POS Transaction not found.
6001
The POS transaction is already linked to a credit reception.
Reverse Credit Reception
At times, an initial Credit Reception needs to be reversed, because of a refund for instance. This will create a new Credit Reception with the same data as initially used, but for the negative number of credits issued.
POST
https://api.piggy.eu/api//credit-receptions/{{credit_reception_uuid}}/reverseHeaders
Authorization
Bearer {{ access_token | api_key }}
Accept
application/json
Params
credit_reception_uuid string
REQUIRED
The UUID of the Credit Reception that needs to be reversed
Response Example
{
"data": {
"type": "credit_reception",
"contact_identifier": null,
"contact": {
"uuid": "123",
"email": "spongebob@bikinibottom.sea",
"credit_balance": {
"id": 2625740,
"balance": 1642
}
},
"shop": {
"id": 15,
"uuid": "123123",
"type": "physical",
"name": "Krusty Krab",
"address": {
"id": 59,
"shop_id": 15,
"street": "Conch Street",
"housenumber": 12,
"postalcode": "9999YZ",
"city": "Bikini Bottom",
"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
1003
Invalid input.
Calculate 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).
GET
https://api.piggy.eu/api//credit-receptions/calculateHeaders
Authorization
Bearer {{ access_token | api_key }}
Accept
application/json
Params
shop_uuid string
REQUIRED
The UUID of the Shop you want to create the Reward Reception for.
contact_uuid string
OPTIONAL
The UUID of the Contact for whom the credits are to be calculated.
unit_value number
REQUIRED
Value for which credits are to be calculated. Subject to any Loyalty Rules.
unit_name string
OPTIONAL
Name of the unit for the corresponding value. If both unit_name and credits are not set, then the default unit (purchase_amount) is used.
Response Example
{
"data": {
"credits": 10240
},
"meta": {}
}Code
Message
1003
Invalid input.
1008
Shop not found.
55031
Contact not found.
60007
Unit not found.
Loyalty Transactions
Loyalty Transaction is the umbrella term for both Credit Receptions and Reward Receptions, representing all the changes to a Credit Balance.
Rewards
Once end-users have saved up enough credits at a certain Loyalty Program, they can use those credits to redeem Rewards. These Rewards can be accessed through ou