Using Snapplify Voucher API

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.

Ensure that no spaces are available in the code, to ensure the API handles the relevant request.

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.

See Voucher Email Example (below) for the email structure sent if a “recipientEmail” is added to the request.

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.