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.

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.

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."
}