POST v3/codes - Create

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

POST 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  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. string, with no spaces, 128 chars data1_data2_data3 No, but recommended
code-type Message body These types must be enabled prior to use. Comp is limited by your contract with VitalSource and generates a no-charge (to you) code. add-drop is associated with temporary licenses. p-plus-e (print-plus-electronic) is used when publishers generate VitalSource codes alongside printed ISBNs. string comp, add-drop, p-plus-e 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 You do not have distribution permission for this product  
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

 

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

Comments

0 comments

Please sign in to leave a comment.