# 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()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/stores/catalog-versioning/get-catalog-version) 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. <br>
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.<br>
Eventually all sites will move off this version, but some stores will stay in this version for a while yet. Read more [here](fallback::https://github.com/wix-private/sdk-manual-docs/blob/master/public-sdk/stores/catalog/introduction*original::../catalog/introduction)
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](fallback::https://github.com/wix-private/sdk-manual-docs/blob/master/public-sdk/stores/catalog-v3/products-v3/introduction*original::../catalog-v3/products-v3/introduction)

---
## Notes
- The [`getCatalogVersion()`](fallback::https://dev.wix.com/docs/sdk/backend-modules/stores/catalog-versioning/get-catalog-version) 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.

@package_metadata:@wix/stores

To use the CatalogVersioning API, install the `@wix/stores` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/stores` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/stores` or `yarn add @wix/stores`. |
| Headless sites and apps | Run `npm install @wix/stores` or `yarn add @wix/stores`. |

#### Import the package

To import the package in your code:

```js
import { catalogVersioning } from '@wix/stores'
```

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)

CatalogVersioning

Catalog Versioning 1 0 0

Retrieves the version of Stores Catalog installed on a site.

import { catalogVersioning } from '@wix/stores';

async function getCatalogVersion() {
  const response = await catalogVersioning.getCatalogVersion();
};

getCatalogVersion

import { createClient } from '@wix/sdk';
import { catalogVersioning } from '@wix/stores';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { catalogVersioning },
  // Include the auth strategy and host as relevant
});


async function getCatalogVersion() {
  const response = await myWixClient.catalogVersioning.getCatalogVersion();
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

getCatalogVersion (self-hosted)

Manage Stores - all permissions

Read Stores - all read permissions

Manage Orders

Manage Products

Read Products

Manage Restaurants - all permissions

Read v3 catalog

Manage v3 catalog

Manage Stores

GetCatalogVersionResponse

# 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()`](https://dev.wix.com/docs/sdk/backend-modules/stores/catalog-versioning/get-catalog-version) 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. <br>
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.<br>
Eventually all sites will move off this version, but some stores will stay in this version for a while yet. Read more [here](../catalog/introduction)
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](../catalog-v3/products-v3/introduction)

---
## Notes
- The [`getCatalogVersion()`](https://dev.wix.com/docs/sdk/backend-modules/stores/catalog-versioning/get-catalog-version) 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.


@package_metadata:@wix/stores

To use the CatalogVersioning API, install the `@wix/stores` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/stores` using the [Wix CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/stores` or `yarn add @wix/stores`. |
| Headless sites and apps | Run `npm install @wix/stores` or `yarn add @wix/stores`. |

#### Import the package

To import the package in your code:

```js
import { catalogVersioning } from '@wix/stores'
```
  

stores_catalog-versioning

The version of Stores Catalog installed on a site.

getCatalogVersion( )