List Vouchers
Retrieve a paginated list of all Vouchers for an Account, with the option to filter by Promotion, Contact, Voucher status, and more.
https://api.piggy.eu/api//vouchersBearer {{ access_token | api_key }}application/jsonpromotion_uuidstringOPTIONALcontact_uuidstringOPTIONALstatusstringOPTIONALlimitnumberOPTIONALpagenumberOPTIONAL1
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
{
"data": [
{
"uuid": "57d93a44-1c9d-4548-8c0e-e6cd71d6170a",
"code": "ABC123",
"status": "ACTIVE",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"expiration_date": null,
"activation_date": "2023-03-02T14:45:52+00:00",
"redeemed_at": null,
"is_redeemed": false,
"attributes": {
"shipping": null,
"shipping_region": null,
},
"contact": null,
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"media": {
"type": "image",
"value": "https://example.com/image.jpg"
}
}
},
{
"uuid": "96ab0da0-f502-4e6d-9b7d-c5b0f5c18795",
"code": "DEF456",
"status": "ACTIVE",
"name": "Free Krabby Patty",
"description": "Free Krabby Patty",
"expiration_date": null,
"activation_date": "2023-03-02T14:45:52+00:00",
"redeemed_at": null,
"is_redeemed": false,
"attributes": {
"shipping": null,
"shipping_region": null,
},
"contact": {
"uuid": "eac16058-d08e-44f3-8bb3-d42afef192cfs",
"email": "bubble1@bikinibottom.sea"
},
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Free Krabby Patty",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"media": {
"type": "image",
"value": "https://example.com/image.jpg"
}
}
},
{
"uuid": "1390b1e6-ac11-413e-8d20-143640fab2f4",
"code": "GHI789",
"status": "ACTIVE",
"name": "Free Krabby Patty",
"description": "Free Krabby Patty",
"expiration_date": null,
"activation_date": "2023-03-02T14:45:52+00:00",
"redeemed_at": null,
"is_redeemed": false,
"attributes": {
"shipping": null,
"shipping_region": null,
},
"contact": {
"uuid": "9504d4b2-03c5-41d8-8423-4b1821b6aa00",
"email": "spongebob@bikinibottom.sea"
},
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Free Krabby Patty",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"media": {
"type": "image",
"value": "https://example.com/image.jpg"
}
}
}
],
"meta": {
"current_page": 1,
"from": 1,
"last_page": 9,
"per_page": "3",
"to": 3,
"total": 10
}
}Code
Message
10038000255031Create Voucher
Creates a new Voucher for a Promotion. Only the promotion_uuid is required. A specific code can be given to be used, or else a code will be generated by the system. Similarly, if no activation_date and/or expiration_date is given, the system will calculate those dates by the validity rules set up for the promotion. It is recommended to send in the expiration and activation date only if business logic demands its, and the validity logic in the Piggy system is unable to handle that logic. Note: If you do send in activation- or expiration dates, keep in mind they need to be in ISO 8601 format and will be stored in UTC time. If the date-time you're sending in is not already in UTC time, please either parse it to UTC beforehand, or pass along the timezone.
https://api.piggy.eu/api//vouchersBearer {{ access_token | api_key }}application/jsonBody
promotion_uuidstringREQUIREDcodestringOPTIONALcontact_uuidstringOPTIONALexpiration_datestringOPTIONALactivation_datestringOPTIONALtotal_redemptions_allowedintegerOPTIONALcustom_attributesarrayOPTIONAL1
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
{
"data": {
"uuid": "62f6dc8c-4ff1-4c42-99ba-713c68ed10a0",
"code": "EXAMPLE-CODE-03785",
"status": "ACTIVE",
"name": "Free Krabby Patty",
"description": "Free Krabby Patty",
"expiration_date": "2023-12-12T10:00:00+00:00",
"activation_date": "2023-12-10T10:00:00+00:00",
"redeemed_at": null,
"is_redeemed": false,
"attributes": {
"joker": null,
"joker2": null,
"jokertje1233": null,
"someName2": "meer"
},
"contact": {
"uuid": "123",
"email": "spongebob@bikinibottom.sea"
},
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Free Krabby Patty",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"joker": null,
"joker2": null,
"jokertje1233": null,
"someName2": "meer"
}
},
"meta": []
}Code
Message
100380002800038000855031Create Batch of Vouchers
Create multiple Vouchers at once for a specific Promotion. Specify the quantity and, optionally, a Contact UUID, activation_date and/or expiration_date. The system will generate a batch of Vouchers according to the Promotion's rules.
https://api.piggy.eu/api//vouchers/batchBearer {{ access_token | api_key }}application/jsonBody
promotion_uuidstringREQUIREDquantityintegerREQUIREDcontact_uuidstringOPTIONALexpiration_datestringOPTIONALactivation_datestringOPTIONALcustom_attributesarrayOPTIONAL1
2
3
4
5
6
7
8
9
10
{
"data": {
"uuid": "bfada889-6a69-4fcf-aed6-42933ae9084d",
"type": "vouchers",
"quantity": 30,
"status": "PENDING",
"created_at": "2023-11-27, 17:59"
},
"meta": []
}Code
Message
1003800028000855031Find Voucher
Finds a Voucher by its unique code. This call will help you with identifying individual Vouchers and viewing their specifications like whether the Voucher is redeemed or not or when it expires.
https://api.piggy.eu/api//vouchers/find?code={{code}}Bearer {{ access_token | api_key }}application/jsoncodestringREQUIRED1
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
{
"data": {
"uuid": "62f6dc8c-4ff1-4c42-99ba-713c68ed10a0",
"code": "EXAMPLE-CODE-03785",
"status": "REDEEMED",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"expiration_date": "2023-12-12T10:00:00+00:00",
"activation_date": "2023-12-10T10:00:00+00:00",
"redeemed_at": "2023-11-13T08:51:00+00:00",
"is_redeemed": true,
"redemptions_remaining": 0,
"times_redeemed": 1,
"total_redemptions_allowed": 1,
"attributes": {
"plu": "ABC123",
},
"contact": {
"uuid": "123",
"email": "spongebob@bikinibottom.sea"
},
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"media": {
"type": "image",
"value": "https://example.com/image.jpg"
}
}
},
"meta": []
}Code
Message
100380004Update Voucher
Update the status of a Voucher. This endpoint allows you to activate or deactivate a Voucher, changing its usability status as needed.
https://api.piggy.eu/api//vouchers/{{voucher_uuid}}Bearer {{ access_token | api_key }}application/jsonvoucher_uuidstringREQUIREDBody
statusstringREQUIREDcustom_attributesarrayOPTIONALexpiration_datestringOPTIONAL1
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
{
"data": {
"uuid": "62f6dc8c-4ff1-4c42-99ba-713c68ed10a0",
"code": "EXAMPLE-CODE-03785",
"status": "ACTIVE",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"expiration_date": "2023-12-12T10:00:00+00:00",
"activation_date": "2023-12-10T10:00:00+00:00",
"redeemed_at": null,
"is_redeemed": false,
"redemptions_remaining": 5,
"times_redeemed": 0,
"total_redemptions_allowed": 5,
"attributes": {
"plu": "ABC123",
},
"contact": null,
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"media": {
"type": "image",
"value": "https://example.com/image.jpg"
}
}
},
"meta": []
}Code
Message
100380004Check Voucher Validity
Validates if the Voucher can be redeemed at this point by the Contact.
https://api.piggy.eu/api/v3/oauth/clients/vouchers/{{voucher_uuid}}/validateBearer {{ personal_access_token }}application/jsonvoucher_uuidstringrequiredcontact_uuidstringrequired if no Contact linkedshop_uuidstringrequiredRedeem Voucher
Redeems a Voucher for a Contact. If the Voucher is already linked to a Contact – because it was sent in an automated email for instance – the call only requires the Voucher's code for redeeming it.
If the Voucher isn't yet linked to a Contact – because a series of Vouchers were printed as flyers to be given away for instance – then the contact_uuidis required as well as the Voucher code.
Please note that when using locked Vouchers, you should send in your release_keyhere as well.
https://api.piggy.eu/api//vouchers/redeemBearer {{ access_token | api_key }}application/jsonBody
codestringREQUIREDshop_uuidstringREQUIREDcontact_uuidstringREQUIRED_IFrelease_keystringOPTIONAL1
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
{
"data": {
"uuid": "62f6dc8c-4ff1-4c42-99ba-713c68ed10a0",
"code": "EXAMPLE-CODE-03785",
"status": "REDEEMED",
"name": "Free Krabby Patty",
"description": "Krabby Patty of your choice",
"expiration_date": "2023-12-12T10:00:00+00:00",
"activation_date": "2023-12-10T10:00:00+00:00",
"redeemed_at": "2023-11-13T08:51:00+00:00",
"is_redeemed": true,
"redemptions_remaining": 0,
"times_redeemed": 1,
"total_redemptions_allowed": 1,
"attributes": {
"plu": "ABC12"
},
"contact": {
"uuid": "123",
"email": "spongebob@bikinibottom.sea"
},
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Choice of Original or Double Deluxe",
"voucher_limit": 25012,
"limit_per_contact": null,
"expiration_duration": null,
"plu": "ABC12"
},
"voucher_redemption": {
"uuid": "8fsl298-oaisdf98-asdf923-afsdoij",
"created_at": "2023-11-13T08:51:00+00:00"
}
},
"meta": []
}Code
Message
10038000480006800058001280014Lock Voucher (Optional)
Using the lock functionality, you can make sure that a Voucher cannot be used by another process at the same time as well as return the Voucher to its ACTIVE state when a failure occurs on your side (using the Release call). Using the locking method, you can make sure the Voucher only reaches a REDEEMED state when everything completed successful on your side.
When locking a Voucher, a release key is returned which should then be used to either redeem the Voucher later on, or to restore the Voucher to its ACTIVE state using the release call.
If the lock is not released within an hour, the lock will be released by the system automatically and the Voucher will be restored to its ACTIVE state.
https://api.piggy.eu/api//vouchers/{{voucher_uuid}}/lockBearer {{ access_token | api_key }}application/jsonvoucher_uuidstringREQUIRED1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"data": {
"voucher": {
"uuid": "11fe9574-800a-4832-ae64-e90d0192ca9a",
"status": "LOCKED"
},
"lock": {
"release_key": "5cc7e94a-7aa2-4f4a-8a8c-c20ab3a086ce",
"locked_at": "2023-11-13T09:01:46+00:00",
"unlocked_at": null,
"system_release_at": "2023-11-13T10:01:46+00:00"
}
},
"meta": []
}Code
Message
10038000480006800058001280017Release Voucher (Optional)
When using Voucher locking, there is also the process of releasing the Voucher. Using the call you can release the Voucher from its lock using the release key that was retrieved during the initial lock.
Extra information:
When redeeming a Voucher that was previously locked, the system will release the lock automatically (you need to provide the release key as well). However, if your system wants to release the Voucher manually you can do so using this call. If the release is not done within the hour, the system will release it automatically.
https://api.piggy.eu/api//vouchers/{{voucher_uuid}}/releaseBearer {{ access_token | api_key }}application/jsonvoucher_uuidstringREQUIREDBody
release_keystringREQUIRED1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"data": {
"voucher": {
"uuid": "11fe9574-800a-4832-ae64-e90d0192ca9a",
"status": "ACTIVE"
},
"lock": {
"release_key": "5cc7e94a-7aa2-4f4a-8a8c-c20ab3a086ce",
"locked_at": "2023-11-13T09:01:46+00:00",
"unlocked_at": "2023-11-13T09:03:32+00:00",
"system_release_at": null
}
},
"meta": []
}Code
Message
1003800048000680005Reverse Voucher Redemption
Reverses a Voucher Redemption.
https://api.piggy.eu/api//vouchers/{{uuid}}/reverseBearer {{ access_token | api_key }}application/jsonuuidstringREQUIREDCode
Message
100380004Multi Redeem Voucher
Redeems a Voucher multiple times at once for a Contact.
If the Voucher isn't yet linked to a Contact – because a series of Vouchers were printed as flyers to be given away for instance – then the contact_uuidis required as well as the Voucher code.
Please note that when using locked Vouchers, you should send in your release_keyhere as well.
https://api.piggy.eu/api//vouchers/multi-redeemBearer {{ access_token | api_key }}application/jsonBody
codestringREQUIREDnumber_of_timesintegerREQUIREDcontact_uuidstringREQUIRED_IFshop_uuidstringREQUIREDrelease_keystringOPTIONAL1
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
{
"data": {
"voucher: {
"uuid": "62f6dc8c-4ff1-4c42-99ba-713c68ed10a0",
"code": "EXAMPLE-CODE-03785",
"status": "REDEEMED",
"name": "Free Krabby Patty",
"description": "Choice of Original or Double Deluxe",
"expiration_date": "2023-12-12T10:00:00+00:00",
"activation_date": "2023-12-10T10:00:00+00:00",
"redeemed_at": "2023-11-13T08:51:00+00:00",
"is_redeemed": true,
"attributes": {
"plu": "ABC12"
},
"contact": {
"uuid": "123",
"email": "spongebob@bikinibottom.sea"
},
"promotion": {
"uuid": "123",
"name": "Free Krabby Patty",
"description": "Choice of Original or Double Deluxe",
"voucher_limit": 1000,
"limit_per_contact": null,
"expiration_duration": null,
"plu": "ABC12"
}
},
"voucher_redemptions": [
{
"uuid": "abc123-890asd-d8a6s7e",
"created_at": "2023-11-13T08:51:00+00:00"
},
{
"uuid": "789bacs-asd1234-d8a6s7e",
"created_at": "2023-11-13T08:51:00+00:00"
},
{
"uuid": "fsa12aa-g332as-xv234a",
"created_at": "2023-11-13T08:51:00+00:00"
}
]
},
"meta": []
}Code
Message
100380004800068000580012800148001980020