The Products API is used to retrieve and query the VitalSource catalog, which has more than a million titles available. Users can choose specific requests to filter results and also configure paging on how many records are returned per page. With this API you get access to data used by VitalSource to distribute, sell and link content including links to additional resources to retrieve other metadata for use within a users own commerce system.
Best Practice: When creating your catalog on your eCommerce site, utilize the kind and format attributes to display the kind of title (ex: Book, Online Resource or Online Resource Bundle) and the format of the content (ex: ePub or Page Fidelity).
Note: When an item is no longer distributable in your catalog, the distributable attribute will return false for 10 days, then will be dropped off the response.
- Verb/URI
- Data Definitions
- Request Headers
- Response
- Error Codes
Verb/URI
https://api.vitalsource.com/v4/productsData Definitions
Name
|
Usage
|
Description
|
Data Type
|
Example
|
Required
|
---|---|---|---|---|---|
URL param | The default request | N/A |
v4/products |
Yes | |
page | URL param | Page number for the catalog request; default pagination is 1000 per page. Depending on the number of records in your distribution set, you will call multiple pages of data. Pages start at page 1. | integer |
v4/products?page=1 |
No |
per_page | URL param | Valid values between 1 and 1,000; recommendation is to pull 1,000 at a time. | integer |
v4/products?per_page=1000 |
No |
from | URL param | ISO-8601 date/time | ISO |
v4/products?from=2019-07-01T00:00:00Z |
No |
until | URL param | ISO-8601 date/time | ISO |
v4/products?until=2020-12-31T00:00:00Z |
No |
include_details | URL param | Valid groups: metadata, subjects, identifiers, accessibility | string |
v4/products?include_details=subjects,metadata |
No |
currency | URL param | Supported ISO-4217 three letter currency code(s) separated by commas | ISO |
v4/products?currency=USD,WON,JPY,NZD |
No |
Request Headers
X-VitalSource-API-Key: ALLNUMBERSANDCAPS
Accept: application/json
Response Header - no parameters (Full call)
This request would return the entire catalog
Best practice: The Full call should be done on a monthly basis.
/v4/productshttps://api.vitalsource.com
Response Header - from example (Delta call)
This request would return all catalog items updated or added since 1-Feb-2023
Best practice: The Delta call should be done on a daily basis. This will allow you to notice any frequent changes to items in the catalog.
/v4/products/?from=2023-02-01T00:00:00Zhttps://api.vitalsource.com
Response Header - from & until example
This request would return all catalog items between 1-Jul-2021 and the end of 2022
https://api.vitalsource.com/v4/products?from=2021-07-01T00:00:00Z&until=2022-12-31T00:00:00Z
Response Header - include_details example
https://api.vitalsource.com/v4/products?include_details=subjectsResponse Header - currency example
https://api.vitalsource.com/v4/products?currency=USD,WON,JPY,NZDResponse
Response Body - default
{
"num_items": 867204,
"page": 123,
"per_page": 1000,
"total_pages": 868,
"items": [
{
"vbid": "L-999-70030",
"kind": "ePub",
"identifiers": {
"print_isbn_canonical": "L99970030",
"eisbn_canonical": null
},
"title": "Fall of the House of Usher",
"format": "Page Fidelity",
"publisher": "Distributor Company",
"edition": 0,
"contributors": [
{
"name": "Edgar Allan Poe",
"type": null
}
],
"language": null,
"created": "2006-03-04T06:20:36Z",
"off_sale_date": null,
"print_restrictions": -1,
"copy_restrictions": -1,
"resource_links": {
"metadata": "https://api.vitalsource.com/v4/products/L99970030",
"cover_image": "https://covers.vitalbook.com/vbid/L-999-70030/width/480",
"table_of_contents": "https://api.vitalsource.com/v4/products/L99970030/toc",
"store_url": "https://vitalsource.com/textbooks?term=L99970030"
},
"related_products": {
"previous_edition": null,
"new_edition": null,
"ancillary": null
},
"sales_rights": [],
"exclude_sales_rights": [],
"variants": [
{
"duration": "perpetual",
"online_duration": "365",
"sku": "L-999-70030",
"type": "Single",
"distributable": true,
"prices": [
{
"type": "digital-list-price",
"value": "0.99",
"currency": "USD",
"discount_code": null,
"territory": null
}
],
"updated": "2016-12-08T17:17:35Z",
"channel_ids": [
{
"channel": "inclusive_access",
"identifier": "L-999-70030"
}
],
"pos_tags":[
"1234", "ABCD"
]
}
],
"contents": []
},...
Response Descriptions - default
The standard response body, returned in your requested format.
Name
|
Description
|
---|---|
vbid | The VitalBookID (VBID) for the title |
kind | The type of asset/product including book, chapter, title, online resource, online resource bundle |
print_isbn_canonical | Print ISBN of asset returned |
eisbn_canonical | eISBN of asset returned |
title | Asset title |
format | Format of the book; Page Fidelity and ePub are valid returns. |
publisher | Name of the publisher |
edition | Edition of the book |
contributors - name | Names of the contributors for the asset |
contributors - type | Type of contributor |
language | Language of the asset |
created | Date the asset was created |
off_sale_date | Date the asset will be removed from distribution |
print_restrictions |
|
copy_restrictions |
|
resource_links - metadata | Additional API call to gather additional metadata about the asset |
resource_links - cover_image | URL for the cover image of the asset |
resource_links - table_of_contents | Additional API call to return the Table of Contents for the asset |
resource_links - store_url | VitalSource store URL for the asset |
previous_edition | Previous edition of the asset |
next_edition | Next edition of the asset |
ancillary | |
sales rights | array of country(s) where assets can be sold |
exclude_sales_rights | array of country(s) where assets cannot be sold |
variants | additional products based on the asset |
variants - duration | Duration for the downloadable version of the product variant, all values are returned as number of days or perpetual |
variants - online_duration | Duration for the online version of the product variant, all values are returned as number of days or perpetual |
variants - sku | Unique product SKU for the product variant; this will be used to make additional API calls to create codes |
variants - type | Type of product that is the variant |
variants - distributable | Value determines whether or not the items can be sold. Items will be in the product response with distributable = false due to deltas and identification of products that have been removed from sale. |
variants - prices - type | Pricing details for the specific product variant |
variants - prices - value | Price of the product variant |
variants - prices - currency | Country code of the currency |
variants - prices - discount_codes | The discount code returned from publishers, typically from an ONIX feed |
variants - prices - territory | |
variants - channel_ids | Array containing channel-specific ISBN that points to one product |
variants - channel_ids - channel | The VitalSource Manage name of the channel |
variants - channel_ids - identifier | The chosen identifier string |
variants - updated | Date the product variant was last updated |
variants - pos_tags | If using the /adoptions endpoint, this returns relevant tags for each adoption match |
contents | This will return the SKUs that are included in a package |
Response Descriptions - include_details
Include_details groups allow a user to request additional blocks of metadata. By default due to the amount of metadata provided for products the response will only include a smaller subset of data for ease of ingestion. If users would like additional book metadata, identifiers or subjects they can be requested using the include_details parameter below. You can request one to many of these response groups separated by a comma.
Name
|
Description
|
---|---|
metadata | Returns additional metadata for a title. Descriptions, publication dates and other relevant metadata listed in the data dictionary. |
identifiers | Returns all of the alias identifiers VitalSource has related to a specific title. This can be used to help power your search index to allow lookup. These often will be the hardcover, spiral bound versions of ISBNs associated to the same digital title. |
subjects | Returns BISAC categories for use of grouping titles in a users commerce platform. |
accessibility | Returns the accessibility features for a title. Accessibility features are data like whether a title has audio captions or if images have descriptions for the visually impaired. |
Response Descriptions - metadata
Name
|
Description
|
---|---|
subtitle | Subtitle of the asset |
description | Description of the asset |
sort_title | Sort title of the asset |
publication_date | Date of copyright for the asset |
page_count | Page count of the asset (if provided by the publisher) |
imprint_name | Name of the publisher imprint |
parent_isbn | If the asset is a child to a parent asset (ex. single chapter of a book) this value is the parent asset |
publisher_list_price | The publisher provided list price of the asset |
Response Descriptions - subjects
Name
|
Description
|
---|---|
schema | Subject classification schema |
code | Subject code |
name | Subject name |
Response Descriptions - identifiers
Name
|
Description
|
---|---|
isbn_canonical | Canonical ISBN of the asset |
isbn_10 | ISBN 10 of the asset |
isbn_13 | ISBN 13 of the asset |
e_isbn | eISBN of the asset |
Response Descriptions - accessibility
The data that is returned in the accessibility_options array can be semantically understood by referencing the a11y w3c schemas here:
Response Descriptions - prices
Each product in a client's catalog can have many prices. Each price has the following attributes:
Name
|
Description
|
---|---|
type | Prices have "types," such as digital list price or print list price. When to use which price type as your selling price is dependent on your company's agreements with VitalSource or your direct agreements with publishers. Please work with your assigned customer success manager |
value | Price in decimal format |
currency | Supported ISO-4217 currency code By default, the endpoint returns all prices in all currencies for each of the "basic" price types. Individual API keys can be configured to receive additional price types as determined by business need. If a client has any custom pricing, a price type of distributor-price will be returned as an additional price element.
Note: Not all products and variants have prices in every price type or currency. If you specify a currency the endpoint returns all prices with the specified currencies for the products a client can distribute. If there are no prices in the currency specified you'll receive empty price information. |
discount_codes | The discount code that can be applied to this product, if applicable |
territory | Comma separated country codes based on the ONIX 3.0 standard (which is based on the ISO 3166-1 standard). If present, the given price is only relevant to transactions in the stated territories and can not be transacted at that price outside those regions. If empty, you may assume the price is good worldwide. |
Response Descriptions - price types
Name
|
Description
|
---|---|
digital-list-price | This is the general price from the publisher to a distributor. Your company may or may not add mark-up, depending on your business terms. |
print-list-price | This is the price the publisher has set for the print product, which can be used for comparison purposes. e.g. "Digital price saves 20 percent over the publisher's list price for the print book." |
distributor-price | This is a custom price given to your company by the publisher. If present, it supersedes the digital list price. |
agency-price | |
catalog-price | The catalog price is regenerated weekly from the digital list price. It is designed to reduce intra-week pricing variations and to quantize when those changes happen. This price is designed for brick-and-mortar stores that have to manage physical shelf price tags. Note: Available upon request |
ia-agency-price | This is a fixed price to student when an institution is purchasing for its inclusive-access program. Your company will not transact at this price. Note: visible to publishers only |
inclusive-access-price | This is the price to bookstore for products delivered through Inclusive Access programs and Equitable Access programs (unless an equitable-access-price exists, applicable to EA programs only). Typically, the bookstore marks up this price. Note: Requires signing an IA and/or EA agreement. |
equitable-access-price | This is the price to bookstore for products delivered through Equitable Access programs only. Note: Requires signing an EA agreement. |
print-on-demand-price | This is the price to purchases an on-demand copy of the digital resource. This purchase has to happen within the VitalSource ecosystem, but may be useful for your company to track. Note: Available upon request |
publisher-unique-price | This is a "special" price that can have different meanings to different publishers. Your company will not transact at this price. Note: visible to publishers only |
recommended-retail | This is a to-consumer purchase price good only in VST-powered e-commerce stores. (This is the "store price" in Manage.) Note: visible to publishers only |
Error Codes
HTTP & Error messages
|
Message
|
Notes
|
---|---|---|
200 |
OK |
Success |
400 |
Not Found |
|
403 |
Forbidden |
1. Does the API Key have permission to access this logical instance. 2. Does your GET request contain missing elements? I.e. "v4/products?from=2020-01-15&until" this is an incomplete request. |
404 |
Not Found |
Catalog not found. Ensure end point is correct. Contact VitalSource to confirm catalog is enabled |
500 |
Internal Server Error |
Comments
Article is closed for comments.