This article is for DEVELOPERS.


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

Once you’ve received your API key from Snapplify, you can easily create a voucher using the following endpoint with your supplied API key. 


Endpoint: https://api.snapplify.com/vouchers?apiKey=YOUR_API_KEY

Method: POST

Format: JSON


Use these parameters to create your voucher:

Parameter

Description

code


Required: 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


Required: Yes

Your voucher reference number. This is a unique identifier (not public facing). 

This could be the invoice number, for example.

Example: INV4657

quantity


Required: Yes

Maximum number of times that the voucher can be used before it becomes invalid.

Example: 1

recipientEmail


Required: No

An optional email address. If supplied, this email address will receive the newly created voucher via email.

Example: recipient@email.com

assetIds


Required: 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: 400

Message: Duplicate code


Code: 400

Message: You cannot re-activate a voucher that is already active.


Code: 400

Message: You cannot activate a voucher that is already active.


Code: 400

Message: You cannot activate a voucher with no associated assets.


Code: 400

Message: [ASSET_IDENTIFIER] is unavailable in your country due to territory restrictions set by the publisher.


Code: 400

Message: [ASSET_IDENTIFIER] has been removed from purchase by the supplier..


Code: 401

Message: 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)"
}


Need help? Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.