POST v4/packages - Create

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

POST https://api.vitalsource.com/v4/packages

Data 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

 

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.