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.



Data Definitions

Data Type
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 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)




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. 



promotional (legacy: comp), 


standard (default code)

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


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 body - all types example

HTTP Code: 200
<?xml version="1.0" encoding="UTF-8"?>
<codes> <code>ALLCAPSANDNUMBERS</code> </codes>

Error Codes

HTTP & Error messages 

Invalid license type

code-type may not be allowed on this API key

Invalid expiration date


Number of days cannot be zero



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  

Malformed XML request



Product sku could not be found SKU is not in the catalog associated with your API key

Invalid code request


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



Article is closed for comments.