V3/catalog to V4/products - migration guide

This article will better explain the differences of the V3 Catalog API compared to the V4 Products API, and help partners successfully migrate to the V4 Products API.

One of the main differences between the V3 Catalogs API and the V4 Products API is the general structure of the response. The V4 Products API was designed to look like, feel like and drive a true commerce experience. In the legacy V3 Catalog API, many of the data points were duplicated among product variants of the same asset. This resulted in larger responses and more data being returned in the API which meant it took a lot longer for a consumer of the API to build a full catalog. The below breakdown of the API response will help to understand how to use the API.

API Response Breakdown

The first part of the API response describes some top level details about the catalog and pagination information. "num_items" describes the total number of "items" or assets and not the total number of product variants or SKUs. Pagination starts at page 1.

"num_items": 16742,
"page": 1,
"per_page": 1000,
"total_pages": 17,

In the V4 Products API, the top level item object is an "item" or asset (identified by VBID or VitalBook Identifier).  The API response includes some metadata about the "item" or asset. The item metadata (title, edition, language, etc...) is shared among all the product variants (the duplicated data in V3 Catalogs API mentioned above).

"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",

The nested objects under the the item are called "variants" or products (identified by SKU). These SKUs are what will be used in subsequent API calls to create and redeem access codes for products. The product variants are the same asset (book), but they have different licensing terms as indicated by the "online_duration" and "duration" fields (ex. one product variant might be for 180 days and the other product variant might be for 365 days). Each product variant also contains its own pricing information at the variant (SKU) level.

"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

v3 to v4 field mapping

v3 Element/field v4 JSON Equivalent v4 XML Equivalent
items num_items num-items
total-pages  total_pages total-pages
page page page
per-page per_page per-page
item  item item
sku sku sku
created created created
updated updated updated
off-sale-date off_sale_date off-sale-date
type type type
downloadable-duration duration duration
online-duration online_duration online-duration
book-format format format
kind kind kind
discount code discount_code discount-code
url store_url store-url
description description description
publication-date publication_date publication-date
author name name
title title title
sort-title sort_title sort-title
edition edition edition
icon-url cover_image cover-image
sampleable *deprecated* *deprecated*
page-count page_count page-count
copyright-date copyright_date copyright-date
copyright-year *deprecated* *deprecated*
print-drm-text print_restrictions print-restrictions
copy-drm-text copy_restrictions copy-restrictions
subjects subjects subjects
parent-isbn parent_isbn parent-isbn
subject schema=biscac schema schema
subject schema=coursesmart schema schema
pricelist prices prices
publisher-name publisher publisher
imprint-name imprint_name imprint-name
distributable distributable distributable
aliases identifiers identifiers
eisbn-canonical eisbn_canonical eisbn-canonical
isbn-canonical isbn_canonical isbn-canonical
print-isbn-canonical print_isbn_canonical print-isbn-canonical
additional-isbns identifiers identifiers
fpid fpid fpid
fpid-equivalent *deprecated* *deprecated*
vpid-equivalent *deprecated* *deprecated*
isbn13 isbn_13 isbn-13
isbn10 isbn_10 isbn-10
owner *deprecated* *deprecated*
company *deprecated* *deprecated* 
id *deprecated* *deprecated* 
name *deprecated* *deprecated* 
distributor *deprecated* *deprecated* 
build-status *deprecated* *deprecated*
company *deprecated* *deprecated* 
id *deprecated* *deprecated* 
name *deprecated* *deprecated* 


The V4 Products API returns more pricing types than the V3 Catalogs API.  This allows the consumer of the API to be more flexible in how they use or display the prices returned in the API response. Below are the pricing types and their descriptions.  If you have questions about these pricing types and when to use them, contact your VitalSource Integration Manager.

Pricing Types Description
digital-list-price Digital list price for the product variant
recommended-retail Recommended retail price for the product variant
publisher-list-price Generally the publisher's list price for the print version of the book
distributor-price Custom price for the distributor



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



Article is closed for comments.