If you’re supplying content to users using Snapplify technology, you can easily provide them with a voucher code.
Since users gain automatic access to their content as soon as the voucher is redeemed, this is also a simple way to facilitate the bulk rollout of digital content to academic institutions and other organisations.
Using the Snapplify Ecommerce plugin for WordPress may alleviate the need to write code for creating vouchers. Find out more about integrating the Snapplify Ecommerce plugin on WordPress.
Setting up your voucher
- Obtain your API key from Snapplify.
- Endpoint: https://api.snapplify.com/vouchers?apiKey=YOUR_API_KEY
- Method: POST
- Format: JSON
Use these parameters to create your voucher:
| Parameter | Required | Description |
| code | No | The code users will redeem to gain access to the products assigned to the voucher. If not specified, the code will be generated. Ensure that no spaces are available in the code, to ensure the API handles the relevant request. Example: MYVOUCHER123 |
| reference | Yes | Your voucher reference number. This is a unique identifier (not public facing). This could be the invoice number, for example. Example: INV4657 |
| quantity | Yes | Maximum number of times that the voucher can be used before it becomes invalid. Example: 1 |
| recipientEmail | Yes | An optional email address. If supplied, this email address will receive the newly created voucher via email. Example: recipient@email.com |
| assetIds | Yes | A list of assetIds in Snapplify for which the voucher entitles the user to (e.g. EAN). Example: 9781431017317 |
Practical considerations
You can set how many times the same voucher code can be redeemed before the code is invalid. For example, if the quantity is 5, then 5 different users will be able to redeem the voucher and each get the same ebook(s).
You can create a voucher with just one asset (e.g. an ebook) or multiple assets assigned to it. You can also specify how many times that voucher can be redeemed by different users.
In the following request example, one user will be able to redeem the voucher (because the quantity is set to 1) and be entitled to the ebook with ISBN 9781431017317.
{
"reference": "INV46571",
"quantity": 1,
"assetIds": [
"9781431017317"
]
}In the below example, when a user redeems this voucher, they will be entitled to two unique ebooks (i.e. ISBN 9781431017317 and 9781431017447). Again, note that the quantity is 1 but can be increased to allow for multiple redemptions of the same voucher:
{
"reference": "INV4657",
"quantity": 1,
"assetIds": [
"9781431017317",
"9781431017447"
]
}Valid API response
Errors
Under some conditions, errors may be returned via the API.
| Code | Message |
| 400 | Duplicate code You cannot re-activate a voucher that is already active. You cannot activate a voucher that is already active You cannot activate a voucher with no associated assets. [ASSET_IDENTIFIER] is unavailable in your country due to territory restrictions set by the publisher. [ASSET_IDENTIFIER] has been removed from purchase by the supplier. |
| 401 | Forbidden. Bad authentication |
JSON error example:
{
"status":400,
"message":"Could not create voucher: (Your Customer Name) - Voucher code must be unique. VoucherDto(code=VOUCHER_CODE,reference=VOUCHER_REFERENCE,label=VOUCHER_LABEL,quantity=QUANTITY,recipientEmail=VOUCHER_USER_EMAIL,assetIds=[ASSET_IDENTIFIER],redeem=AUTO_REDEEM,user=USER_ID)"
}Once set up is complete, it's always advisable to run a test. You can place test orders using the Voucher API to ensure everything is working correctly. Ensure you Prefix vouchers with "QA" or "Test_" for easy identification and Snapplify with exempt these from reporting.
Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.
