GET v4/products - Read All

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

GET https://api.vitalsource.com/v4/products

Data 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.

GET https://api.vitalsource.com/v4/products

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.

GET https://api.vitalsource.com/v4/products/?from=2023-02-01T00:00:00Z

Response Header - from & until example

This request would return all catalog items between 1-Jul-2021 and the end of 2022

GET https://api.vitalsource.com/v4/products?from=2021-07-01T00:00:00Z&until=2022-12-31T00:00:00Z

Response Header - include_details example

GET https://api.vitalsource.com/v4/products?include_details=subjects

Response Header - currency example

GET https://api.vitalsource.com/v4/products?currency=USD,WON,JPY,NZD

Response

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
  • 1 denotes unrestricted copying or printing
  • 0 denotes no copying or printing. Only some integrations are allowed to use this value. See your Customer Success Manager for details.
  • A value of 1 is not allowed.
  • Otherwise, values should be 2 or greater.
copy_restrictions
  • 1 denotes unrestricted copying or printing
  • 0 denotes no copying or printing. Only some integrations are allowed to use this value. See your Customer Success Manager for details.
  • A value of 1 is not allowed.
  • Otherwise, values should be 2 or greater.
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
This is a fixed price to consumer set by the publishers. Your company must transact at this price. No markup or discount on this price is allowed.
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

 

 

Was this article helpful?
2 out of 3 found this helpful

Comments

0 comments

Article is closed for comments.