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 products requested, or you will receive errors. Please note below we have documented the five ways you can define the license type. License MUST be specified for both the installed and online versions of Bookshelf. 

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 installed apps in all major ecosystems (Windows, MacOS, Android & iOS). This element will set license terms for all installed apps accessed by this code. Choosing default will automatically use the product level defaults. (Note: Branded versions do not always have all 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  No
tag Message body Mark a batch of codes with a particular code for tracking purposes. We strongly encourage using this element on all calls.  string, with no spaces id_456_xyz No
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 codes 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.