About the Catalog Versioning API

The Catalog Versioning API allows you to determine what version of the Wix Stores Catalog a site is using.

The two versions of the catalog are not backwards compatible. Supporting both versions of the catalog is critical, as sites will be spread across both versions.

Motivation

In order to support our customers' needs and to support the best practices in a modern eCommerce platform, WixStores has developed a new API. Designated Catalog V3, this new API will allow more fine-grained control of your store, as well as much better performance.

Unfortunately, not every store will be able to take advantage of this new API right away. Because of this, to use the Catalog API, services will need to first check which version of the Catalog is being used on a specific site. In order to determine which API to use, it is important to call the getCatalogVersion() endpoint at the beginning of each flow.

Catalog Webhooks/Events

V1 Domain events will be sent for all updates to the Catalog, even for sites using the V3 catalog. Each event has a new CatalogVersion field.
This field can take the values V1_CATALOG or V3_CATALOG. This data can be used instead of calling the Versioning API.

Before you begin

It’s important to note the following points before starting to code:

  • The site owner must have the Wix Stores app installed.
  • Your app must have the SCOPE.STORES/CATALOG_READ permission

Terminology

  1. Catalog V1: Original API for Wix-Stores.
    Eventually all sites will move off this version, but some stores will stay in this version for a while yet. Read more here
  2. Catalog V3: New API for Wix-Stores. Once original API is deprecated, this will be the new standard for Wix-Stores. Read more here

Notes

  • The getCatalogVersion() endpoint takes no parameters. All necessary information is contained within your AUTH header.
  • Once a store has been upgraded to CATALOG_V3, it will not be downgraded to CATALOG_V1
  • Changing catalog versions is a once-in-a-lifetime event for a given store (site). One call to this endpoint will suffice for most catalog flows.
Did this help?