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

  • If a user already has a Perpetual license to a product, requests to auto-redeem for that product will be ignored.

Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols API Key
Valid for Roles System to System

API Request

HTTP Verbs and URLs

POST /v3/redemptions/bulk.xml

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP

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>

Element Descriptions

Fields Description Required
access-token The user's current (and unexpired) access token  Yes
sku Product identifier for the product for which we are granting access.  Yes
term The desired license length to grant the user for downloadable access (two options: # of days, like "1825," or "Perpetual" for access that never expires)  Yes
online-term 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 "1825," or "Perpetual" for access that never expires)  No
tag Arbitrary tag which will be attached to any redemption code that is created (for reporting purposes)  No
ensure-years 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.  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.  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.  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."  No
price Set the price on each request within a bulk redemption request  

Request Response

Success (initial request)

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

Success (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>

Element Descriptions

Fields 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 redemption response) processing 
status (individual redemption in callback response) skipped, redeemed, or error
code Code that was automatically created and redeemed
msg Explanatory message about the particular redemption request
tag Arbitrary tag which will be attached to any redemption code that is created (for reporting purposes)

Failure

See full list of error codes and messages.

HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<error-response>
  	<error-code>901</error-code>
  	<error-text>Malformed XML request</error-text>
</error-response>

 

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

Comments

0 comments

Please sign in to leave a comment.