The v4/packages APIs require a special API Key permission. Please contact your Customer Success Manager if you wish to use them.
This API creates a Package that is a collection of Assets/SKUs. Use this API if you wish to group multiple titles into a single SKU to allow single item redemptions of a package of titles/resources.
Verb/URI
https://api.vitalsource.com/v4/packagesData Definitions
Name
|
Usage
|
Description
|
Data Type
|
Example
|
Required
|
---|---|---|---|---|---|
sku | Message body |
Populate to create a custom SKU for the package. If this is not included a SKU will be automatically created and returned in the response. It is important to know that the system appends the first 3 characters of the owning company name to name space the package sku. It also converts to all caps. This sku will be used for creating/redeeming codes to provide access to packages and content to users. |
string | TEST-1234 | No, highly recommended |
name | Message body | Package name that will display in VitalSource Manage | string | Name of your package | Yes |
library_id | Message body | The specific library set up within VitalSource Manage to specify where the package will live. This must be a LibraryID that was created by the requesting companies API key. | integer | 1500. Ask your CSM for assistance here | Yes |
products | Message body | A list of assets or SKU identifiers that are needed to create the package. This can be left blank but will create an empty package that must be updated later | single or array | "products": ["{{variable_vbid}}","{{variable_vbid2}}"] | No, highly recommended |
download_license, online_license | Message body | Specific elements to specify the license length and type for downloadable and online clients. Must set a specific value | array | "download_license": { "type":"numdays", "num_days":"180"} |
Yes |
type | Message body | Set value for type of license. Options are numdays, absdate, perpetual | key: value | "type":"numdays", | Yes |
num_days | Message body | Number of days from redemption that access is granted | key: value | "num_days":"180" Max = 3,650 days; else choose perpetual | Only if type=numdays |
expiration_date | Message body | The date in YYYY-MM-DD for the package expiration | ISO-8601 date | 2020-12-31 | Only if type=absdate |
description | Message body | Optional package description to display to end users | string | License free content | No, but recommended |
list_price | Message body | The price for the package, if necessary | number | 19.99 | No |
tags |
Message body | String field to allow reporting data to move through VST systems | string | no_spaces_allowed | recommended |
Request Headers
X-VitalSource-API-Key: ALLCAPSANDNUMBERS Content-Type: application/json
Request Body
Request body - default example
{
"name":"Name of your package",
"sku": "TEST-1234",
"description":"License free content",
"products": ["{{variable_vbid}}","{{variable_vbid2}}"],
"library_id":"{{devNetworkLibraryID}}",
"download_license": {
"type":"absdate",
"expiration_date":"2021-12-31"
},
"online_license": {
"type": "numdays",
"num_days":"180"
},
"list_price": 19.99,
"tags": ["TAG1","TAG2"]
}
Response
Response body - default example
{
"sku": "TEST-1234",
"name": "Name of your package",
"description": "License free content",
"publisher": "YOUR_COMPANY_NAME_HERE",
"list_price": "19.99",
"download_license": {
"details": "Expires on December 31, 2020",
"duration": null
},
"online_license": {
"details": "Expires 180 days after registration",
"duration": "180 days"
},
"tags": [],
"created_on": "2019-07-30T12:00:00Z",
"updated_on": "2019-07-30T12:00:00Z",
"products": [
{
"isbn": "L-999-70103",
"vbid": "L-999-70103",
"fpid": null,
"isbn13": null,
"description": "Jane Austen's most famous novel, Pride and Prejudice focuses on Elizabeth Bennet and how she deals with her sisters' romantic entanglements while trying to manage her own.",
"publication_date": "1813",
"author": "Jane Austen",
"title": "Pride and Prejudice",
"sort_title": "Pride and Prejudice",
"icon_url": "https://covers.vitalbook.com/vbid/L-999-70103/width/120",
"sampleable": false
},
{
"isbn": "L-999-71968",
"vbid": "L-999-71968",
"fpid": null,
"isbn13": null,
"description": "After beautiful socialite Dorian Gray sits for a portrait, he casually remarks that he would like to forever appear as the young, pure man looking out from the canvas. In the years that follow, Dorian's is lured into a life of vain depravity, yet Dorian remains physically attractive. Instead, the portrait acquires the ugliness of his sin and perversion. Oscar Wilde's only novel, The Picture of Dorian Gray darkly addresses the sadistic and egotistical aspects of human nature.",
"publication_date": "1890",
"author": "Oscar Wilde",
"title": "The Picture of Dorian Gray",
"sort_title": "Picture of Dorian Gray",
"icon_url": "https://covers.vitalbook.com/vbid/L-999-71968/width/120",
"sampleable": false
}
]
}
Response descriptions
Name
|
Description
|
---|---|
sku | The auto-generated SKU for the new package, or name you passed |
name | The name of the package |
description | Package description to display to end users |
Publisher | Name of the company who created the package (in VitalSource Manage) |
list_price | The price for the package if necessary |
download_license, online_license | Specific elements to specific the license length and type for downloadable and online clients. Must set a specific value |
tags | String field passed at Create/Update |
details | Text describing license rules set |
duration | Number of days of num_days was used, otherwise null |
product(s) [{sku},{sku2}] | Array of SKU's in package. Metadata currently available for each asset in VitalSource Manage is shown for each asset as vbid response body |
Error Codes
HTTP & Error messages
|
Message
|
Notes
|
---|---|---|
201 |
Created |
The build process was successful and the package is ready. |
422 |
Name can't be blank |
Required field |
422 | SKU can't be blank | Do not pass as null |
422 | Company can't be blank | API key issue |
422 | License rule can't be blank | See code create to learn more |
422 | Online license rule can't be blank | See code create to learn more |
422 | Library is not acceptable | Ask your CSM for assistance here |
Comments
Please sign in to leave a comment.