About the Catalog Versioning API

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

With the Catalog Versioning API, you can retrieve the catalog version installed on a site.

V1 vs V3 catalogs

Wix Stores has two catalog versions:

• Catalog V1: The original Wix Stores API. Some stores remain on this version, though all sites will eventually migrate to V3. Learn more about Catalog V1.
• Catalog V3: The newer API offering finer-grained control and better performance. Learn more about Catalog V3.

The two versions are not backwards compatible. To ensure your integration works correctly, call GetCatalogVersion at the beginning of each flow to determine which API to use.

Domain events and webhooks

Each catalog version has its own set of domain events. Changes in the V1 catalog trigger V1 webhooks, and changes in the V3 catalog trigger V3 webhooks.

To handle events from all sites until V1 is fully deprecated, subscribe to both V1 and V3 domain events:

• V1 domain events for notifications from sites still on V1 catalog.
• V3 domain events for notifications from sites migrated to V3 catalog.

Important notes

• The GetCatalogVersion endpoint takes no parameters. All necessary information is contained within your authorization header.
• Once a store has been upgraded to V3, it will not be downgraded to V1.
• Catalog version is permanent for a given site. A single call to this endpoint is sufficient for most flows.

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.

Use cases

• Create a product while supporting both V1 and V3 catalogs

Terminology

• Catalog V1: Original Wix Stores API.
• Catalog V3: Newer Wix Stores API with improved performance and capabilities.