This API creates one or more redemption codes for specific VitalSource books with this call. These codes will be redeemed by user-specific accounts. Your company must have distribution rights to the product requested or you will receive an error.
Below we have documented the five (5) ways you can define the license type. VitalSource offers both installed and online versions of our Bookshelf eReader. In order to successfully create a code you MUST specify license terms for each of these versions, separately. The online version is defined by the "online-license-type" field, while the installed version is defined by the "license-type" field.
It is possible to partially skip these definitions by passing license-type="default" as shown below. This will leave contractual and product defaults in place. Ask your CSM for these numbers.
Verb/URI
https://api.vitalsource.com/v3/codes.xml
Data Definitions
|
Name
|
Usage
|
Description
|
Data Type
|
Example
|
Required
|
|---|---|---|---|---|---|
| sku | Message body |
The VitalBookID (VBID) for the title. To determine your available catalog make the GET v4/products/ request. Payload from that endpoint will contain "vbid", "sku" and "eisbn_canonical". Along with "fpid" from legacy integrations, all these options are acceptable as sku="L-999-70461" |
string | L-999-70461 | Yes |
| license-type | Message body | VitalSource Bookshelf has free apps for all major ecosystems (Windows, MacOS, Android, iOS, Kindle & Chromebook). This element will set license terms for all installed apps accessed by this code. Choosing default will automatically use the product/contract defaults. (Note: Branded versions do not always have installable apps.) | string | perpetual, numdays, absdate, default, noaccess | Yes |
| num-codes | Message body | The number of codes to create for the request | integer | 1 | Yes |
| online-license-type | Message body | VitalSource Bookshelf is accessible at https://bookshelf.vitalsource.com. This optional element sets terms for access to online versions of the bookshelf reader only. If this is not set, the code will inherit the product defaults. (Note: Branded versions of Bookshelf have different URLs.) | string | numdays, absdate, noaccess | Yes, unless license-type = "default" |
| tag | Message body |
Mark a batch of codes with a particular code for tracking purposes. We strongly encourage using this element on all calls. Concatenate multiple fields. This field is available within VitalSource Manage reporting and Caliper feeds. If sending a ":" you have created a key :value pairing within your string. Only one ":" is allowed. If sending more than one ":" will cause all data after that ":" to be ignored. |
string (50) with no spaces (“:” can only be used once) |
order1_region2_cust3 or mcgrawcodes:1234567 |
No, but highly recommended |
| code-type | Message body |
Standard is the default code. Other types must be enabled by Integration Manager prior to use. add-drop is associated with temporary licenses. |
string |
add-drop, promotional (legacy: comp), pub_sample, standard (default code) |
No |
| price | Message body | CAUTION - Do not pass this element without first consulting with your integration and customer success manager as it is an override to publisher agreements. Use if setting a price; must be greater than 0. Omitting this element will default to the appropriate publisher-set price. Passing an incorrect price will cause billing issues and may violate your contract. | num | 50.00 | No |
| num-days | Message body | The number of days for which this downloadable license should be available after redemption | integer | 180. Max = 3,650 days; else choose perpetual | Only if license-type = numdays |
| online-num-days | Message body | The number of days for which the online license should be available after redemption | integer | 90. Max = 3,650 days; else choose perpetual | Only if online-license-type = online-numdays |
| exp-year | Message body | The expiration year of the downloadable book | integer | 2025 | Only if license-type = absdate |
| exp-month | Message body | The expiration month of the downloadable book | integer | 12 | Only if license-type = absdate |
| exp-day | Message body | The expiration day of the downloadable book | integer | 31 | Only if license-type = absdate |
| online-exp-year | Message body | The expiration year of the online book | integer | 2025 | Only if license-type = absdate |
| online-exp-month | Message body | The expiration month of the online book | integer | 12 | Only if license-type = absdate |
| online-exp-day | Message body | The expiration month of the online book | integer | 31 | Only if license-type = absdate |
Request Headers
X-VitalSource-API-Key: ALLCAPSANDNUMBERS
Request Body - examples:
Request body - numdays example
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="{{vst_vbid}}" license-type="numdays" num-days="180" online-license-type="numdays" online-num-days="180" num-codes="1" tag="postman_created_code"/>
Request body - absdate example
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="{{vst_vbid}}" license-type="absdate" exp-year="2020" exp-month="01" exp-day="01" online-license-type="absdate" online-exp-year="2020" online-exp-month="01" online-exp-day="01" num-codes="1" tag="postman_created_code"/>
Request body - perpetual example (your contract must permit this)
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="{{vst_vbid}}" license-type="perpetual" online-license-type="perpetual" num-codes="1" tag="postman_created_code"/>
Request body - default example (your standard contract terms will be applied)
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="{{vst_vbid}}" license-type="default" online-license-type="default" num-codes="1" tag="postman_created_code"/>
Request body - noacccess example (in this example the user cannot access the installed apps, only online)
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<codes sku="{{vst_vbid}}" license-type="noaccess" online-license-type="default" num-codes="1" tag="postman_created_code"/>
Response
Response body - all types example
HTTP Code: 200 <?xml version="1.0" encoding="UTF-8"?>
<codes> <code>ALLCAPSANDNUMBERS</code> </codes>
Error Codes
|
HTTP & Error messages
|
Message
|
Notes
|
|---|---|---|
| 104 |
Invalid license type |
code-type may not be allowed on this API key |
| 105 |
Invalid expiration date |
|
| 106 |
Number of days cannot be zero |
|
| 200 |
|
Success. Errors provided simultaneously |
| 403 | Execute access forbidden | Wrong or invalid API Key |
| 403 | You do not have distribution permission for this product | Your Manage company does not have distribution rights to the SKU passed in the request body |
| 900 | Insufficient permission to perform this action | |
| 901 |
Malformed XML request |
|
|
902 |
Product sku could not be found | SKU is not in the catalog associated with your API key |
| 905 |
Invalid code request |
|
| 908 |
Code price must be positive |
|
| 909 | Sampling not allowed | |
| 997 | Product has unavailable asset | Error with underlying asset |
Comments
Article is closed for comments.