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.
- If a user already has a Perpetual license to a product, requests to auto-redeem for that product will be ignored.
- Verb/URI
- Data Definitions
- Request Headers
- Response
- Error Codes
Verb/URI
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,-1 | No, but ensure-{something} is strongly recommended |
| ensure-days | Message body | 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. Including ensure-days or ensure-online-days will cause ensure-years to be ignored.. | number | 180 | No, but ensure-{something} is strongly recommended |
| ensure-online-days | Message body |
Ensure-online-days is checked before the ensure-years default. Including ensure-days or ensure-online-days will cause ensure-years to be ignored. |
number |
180 |
No, but ensure-{something} is strongly recommended |
| callback | URL |
Omit this at your peril. Without a valid callback you will have no information as to the status of your request(s). 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 VitalSource can only perform naked POST requests on callback. No authentication is possible as we send to you. Should this be determinative please instead use the non-bulk version of this API, where information is available in the response body. |
No, but highly recommended |
| code-type | Message body | 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 | Message body | 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 |
Comments
Please sign in to leave a comment.