This guide describes how to use the Snapplify Voucher API to generate vouchers for users to redeem and gain access to Snapplify content.
This article is for DEVELOPERS. 😀
Vouchers are used to manage the sale of Snapplify products through a third-party. Once a voucher is redeemed, the customer receives their digital product, referred to as an ‘entitlement’.
Voucher API provides an interface for programmatically adding vouchers into the Snapplify administration system, and for users to redeem these vouchers (including querying these for verification upon redemption, etc.). This enables you to provide voucher codes to users following the sale of content, and facilitates the rollout of digital content in bulk to academic institutions and other organisations.
Voucher redemption user flow
This is the typical flow for using redeem.snapplify.com as the redemption point for the voucher generated on the customer’s side:
1. The user browses the website and makes a purchase, following your normal e-commerce workflow.
2. The user should be informed that the purchase is for a digital product and will require the Snapplify Reader app to read the ebook.
3. The user receives email order confirmation including a voucher number (this is generated as part of API calls) and instructions on how to redeem the voucher.
4. The user goes to redeem.snapplify.com and enters the voucher number. If the user has an existing Snapplify account, they can sign in and redeem the voucher; alternatively, they will be required to register a Snapplify account.
5. The user downloads the Snapplify Reader application on their device of choice, signs in with their user account, and has access to their entitlements.
Create voucher
Request
Endpoint |
https://api.snapplify.com/stores/{storeId}/applications/{appId}/vouchers?apiKey=YOUR_API_KEY |
||
Method |
POST |
||
Format |
JSON |
||
Parameter |
Required |
Description |
Example |
code |
false |
An optional code to be used for the voucher. If not specified, the code will be generated. |
MYVOUCHER123 |
reference |
true |
Your reference number. This should be unique on the third-party system. If you are sending one request, as in Example 1 (below), this could be the invoice number. If you are sending multiple requests, as in Example 2 (below), this could be the invoice number and the line number. |
INV4657 INV46571 INV46572 |
quantity |
true |
The number of voucher redemptions allowed. |
100 |
recipientEmail |
false |
An optional email address. If supplied, this email address will receive the newly created voucher via email. |
recipient@address.com |
assetIds |
true |
A list of assetIds in Snapplify for which the voucher entitles the user to. e.g. EAN. |
9781431017317 4571431017447 |
JSON Example 1
The following shows a request that will create a voucher.
When a user redeems this voucher, they will be entitled to 9781431017317:
{
"reference": "INV46571",
"quantity": 100,
"assetIds": [
"9781431017317"
]
}
JSON Example 2
When a user redeems this voucher, they will be entitled to both 9781431017317 and 4571431017447:
{
"reference": "INV4657",
"quantity": 100,
"assetIds": [
"9781431017317",
"4571431017447"
]
}
Response
Format |
JSON |
|
Parameter |
Description |
Example |
code |
The code to be distributed to users. |
MACM7T4YUY45368A |
reference |
The reference passed to the request. |
INV4657 |
quantity |
The quantity passed to the request. |
100 |
quantityRemaining |
The number of entitlements that are still available. |
100 |
assetIds |
A list of assetIds in Snapplify for which the voucher entitles the user to. e.g. EAN. |
9781431017317 4571431017447 |
JSON Example 1
{
"code": "MACM7T4YUY2I3A87",
"reference": "INV4657",
"quantity": 100,
"quantityRemaining": 100,
"assetIds": [
...
"9781431017317",
"4571431017447",
...
]
}
JSON Error Example
{
"status": 400,
"error": "Invalid Voucher",
"message": "Duplicate code"
}
Errors
Under some conditions errors may be returned.
Code |
Message |
500 |
Invalid store or appId. |
500 |
Duplicate code. |
401 |
Forbidden. Bad authentication. |
Query voucher
The query voucher API enables the programmatic verification of vouchers that have already been added to the Snapplify administration system.
Request
Endpoint |
https://api.snapplify.com/stores/{storeId}/applications/{appId}/vouchers/code/{VOUCHER_CODE}?apiKey=YOUR_API_KEY |
||
Method |
GET |
||
Parameter |
Required |
Description |
Example |
VOUCHER_CODE |
true |
The code of the voucher to query. |
MACM7T4YUY45368A |
Response
Format |
JSON |
|
Parameter |
Description |
Example |
code |
The code to be distributed to users. |
2653404087 |
reference |
The reference passed to the request. |
INV4657 |
quantity |
The quantity passed to the request. |
100 |
quantityRemaining |
The number of entitlements that are still available. |
98 |
assetIds |
A list of assetIds in Snapplify for which the voucher entitles the user to. e.g. EAN. |
9781431017317 4571431017447 |
JSON Example 1
{
"code": "MACM7T4YUY2I3A87",
"reference": "INV4657",
"quantity": 100,
"quantityRemaining": 98,
"assetIds": [
"9781431017317",
"4571431017447"
]
}
JSON Example 2
{
"code": "MACM7T4YUY45368A",
"reference": " INV46571",
"quantity": 100,
"quantityRemaining": 98,
"assetIds": [
"9781431017317"
]
}
JSON Error Example
{
"status": 400,
"error": "Invalid Voucher",
"message": "Code not found"
}
Voucher Email Example
Errors
Code |
Message |
500 |
Invalid store or appId. |
401 |
Forbidden. Bad authentication. |
Validate voucher
The following request is used to verify if a voucher code is valid. This includes whether the voucher exists, has available redemptions, or if this voucher has already been redeemed (if single use).
GET [/voucher/check/:voucher_code]
Request
Authentication:
Header |
Value |
Required |
Additional Notes |
Token |
String |
Yes |
The unique authentication token. |
Parameters:
Name |
Value |
Required |
Additional Notes |
voucher_code |
String |
Yes |
The unique voucher code. |
Response
Name |
Value |
Additional Notes |
voucher_code |
String |
The unique voucher code. |
valid |
Boolean |
Whether or not the voucher is valid. |
Example:
> GET
/voucher/check/5GR2ACM-UYT54
> RESPONSE
> STATUS 200 Ok
{
"voucher_code": "5GR2ACM-UYT54",
"valid": true
}
Errors
Code |
Message |
500 |
Invalid store or appId. |
Redeem Voucher
Redeem and check vouchers for redemption. The vouchers must first be created in order for redemptions to take place.
GET [/voucher/redeem/:voucher_code]
Redeem a specific voucher
Request
Authentication
Header |
Value |
Required |
Additional Notes |
Token |
String |
Yes |
The token received from user authentication. |
Parameters
Name |
Value |
Required |
Additional Notes |
voucher_code |
String |
Yes |
The unique voucher code. |
Response
Name |
Value |
Additional Notes |
success |
Boolean |
Whether or not the voucher was successfully redeemed. |
entitlements |
Array |
The list of product IDs associated with the voucher |
voucher_code |
String |
The unique voucher code. |
Example:
> GET
/voucher/redeem/5GR2ACM-UYT54
> RESPONSE
> STATUS 200 Ok
{
"success": true,
"voucher_code": "5GR2ACM-UYT54",
"entitlements": [
"item-id-one",
"item-id-two",
"item-id-three"
],
}
Optionally, you can call the API with your specific store identifier, explained below.
GET [/voucher/{storeId}/redeem/:voucher_code]
Redeem a voucher from a specific store
Authentication:
Header |
Value |
Required |
Additional Notes |
Token |
String |
Yes |
The unique authentication token |
Parameters:
Name |
Value |
Required |
Additional Notes |
storeId |
String |
Yes |
The store identifier. |
voucher_code |
String |
Yes |
The unique voucher code. |
Response:
Name |
Value |
Additional Notes |
success |
Boolean |
Whether or not the voucher was successfully redeemed. |
entitlements |
Array |
The list of product IDs associated with the voucher |
voucher_code |
String |
The unique voucher code. |
Example:
> GET
/voucher/redeem/5GR2ACM-UYT54
> RESPONSE
> STATUS 200 Ok
{
"success": true,
"voucher_code": "5GR2ACM-UYT54",
"entitlements": [
"item-id-one",
"item-id-two",
"item-id-three"
],
}
Errors
The following responses can occur for the /voucher/redeem and /voucher/check services.
Parameters:
Error Code |
Message |
220 |
Incorrect voucher code or voucher does not exist. |
221 |
Voucher redemption limit has been reached. |
222 |
Voucher already redeemed by user. |
Example:
> RESPONSE
> STATUS 200 Ok
{
"valid": false,
"error_code": 220,
"error_message": "Incorrect voucher code."
}
👉 Learn how to use Snapplify voucher API.
Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.