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

Pricing

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.