POST v3/redemptions/bulk - Redeem Codes (bulk)

Create and Redeem codes for multiple users at one time for processing. Currently, the only valid values for the license terms are: positive # of days or "perpetual."

Note: This API is designed around the callback URL premise. In order to receive status on your submission you must pass VitalSource an HTTPS callback URL. 

 Verb/URI

POST https://api.vitalsource.com/v3/redemptions/bulk.xml

Data Definitions

Name
Usage
Description
Data Type
Example
Required
access-token Message body The user's current (and unexpired) access token string 

lowercaseandnumbers

Yes
sku Message body Product identifier for the product for which we are granting access. string  BOOKSHELF-TUTORIAL Yes
term Message body  The desired license length to grant the user for downloadable access (two options: # of days, like "180," or "Perpetual" for access that never expires) string  180 No
online-term Message body  The desired license length to grant the user for online access. If this field is not specified, term will be used in place of online-term. (Two options: # of days, like "180," or "Perpetual" for access that never expires) string 180 No
tag Message body Your string which will be attached to any redemption code that is created (for reporting purposes) string  XYX_ID_123 No
ensure-years Message body  Refers to the minimum number of years you wish for this user to have the product before giving a new license (defaults to 3 years). If the account holder does not already have this number of years available, a new redemption code will be created and redeemed which grants the user access for the requested term length. To force the redemption to happen regardless of the current state of the user's content, pass an ensure-years value of -1. integer  2 No
ensure-days   Refers to the minimum number of days you wish for this user to have the product before giving a new license. If the account holder does not already have this number of days available, a new redemption code will be created and redeemed which grants the user access for the requested term length. ensure-days is checked before the ensure-years default. In other words, if you omit ensure-years and include ensure-online-days, that could take precedence on the skip logic. If you include ensure-years and need it to be ignored, pass a value of 0. number 180 No 
callback   While not required this element is the ONLY way to receive status regarding your bulk POST request. This endpoint will respond with "processing" for all correctly formed XML. Issues with the body of your request. I.e bad sku's or access tokens will generate "processing." If this attribute is present, status of this bulk request will be posted back to you at this URL. URL  https://yourdomain.com  No 
code-type   comp, add-drop, and p-plus-e are valid values. If code-type is missing or blank, the code type will be "code-api." string comp, add-drop, and p-plus-e  No 
price    Set the price on each request within a bulk redemption request  number  10.00  No

 

Request Headers

X-VitalSource-API-Key: ALLCAPSANDNUMBERS

Request Body

Request

<?xml version="1.0" encoding="UTF-8"?>
<redemptions callback="https://yourserver.com/yourpath/alldone">
	<redemption access-token="abcdefghijklmnopqrstuvwxyz123456" sku="0390222801" term="Perpetual" online-term="1825" tag="4018045" ensure-years="3" /> 
	<redemption access-token="abcdefghijklmnopqrstuvwxyz654321" sku="0077376323" term="1825" ensure-years="3" />
	<redemption access-token="abcdefghijklmnopqrstuvwxyz654321" sku="0074231723" term="55" code-type="add-drop" />
</redemptions>

Response

Response body - default

HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<redemptions>
	<redemptions status="processing">
</redemptions>

Response body - default (if callback URL provided)

HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?> 
<redemptions> 
	<redemption access-token="abcdefghijklmnopqrstuvwxyz123456" sku="0390222801" status="redeemed" code="XYZABCDEFBUZGHIKKABD" tag="4018045"/>
<redemption access-token="abcdefghijklmnopqrstuvwxyz654321" sku="0077376323" status="skipped" msg="/> </redemptions>

Response descriptions

Name
Description
access-token The user's current (and unexpired) access token
sku Product identifier for the product for which we are granting access
status (in bulk) processing
status (individual) skipped, redeemed, or error
code Code that was automatically created and redeemed
msg Explanatory message about the particular redemption request
tag Your string which will be attached to any redemption code that is created (for reporting purposes)

 

Error Codes

HTTP & Error messages 
Message
Notes
200

 

Success. Errors provided simultaneously
468

Redemption code is invalid

 
469

Code has been redeemed

Access token mismatch/error
470

Redemption failed

 
474

User could not be found

Access token issue
483

Malformed redemption request

 
1001

Code is not available for redemption 

Already redeemed 
1004

Redemption code is expired

 
1006

Error creating eResource

 
1007

Timeout when attempting call to eResource provider

 

 

Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.