Catalog V1 to V3 Velo Events Migration Guide

If your site uses Wix Stores V1 catalog events, add the corresponding V3 handlers before your site moves to Catalog V3. Keep your V1 handlers so that your site continues to respond to catalog changes before and after migration.

In each V3 handler, update your code to use the V3 event data. If the handler makes catalog API calls, use Catalog V3 SDK methods, such as Get Product.

How events work during migration

While your site uses Catalog V1, it receives V1 catalog events. After it moves to Catalog V3, it receives V3 catalog events and stops receiving V1 events. A catalog change does not generate both V1 and V3 events, so keeping both sets of handlers does not create duplicate events across versions.

Use Velo backend handlers to receive events in backend/events.js. Use Catalog V3 SDK methods for catalog API calls within those handlers.

Update your site code

1. Find your V1 catalog handlers in backend/events.js. Check the helper functions they call for catalog API calls.
2. Use the event conversion table to find the corresponding V3 events. Follow Define Backend Event Handlers to add the handlers. Keep the V1 handlers.
3. Adapt each V3 handler to use the V3 event data and Catalog V3 SDK methods. Read the Catalog V1 to V3 Migration Guide for changes to entity structures and fields.
4. Publish and test on a test site. Trigger catalog changes for the version the test site uses. Backend events do not run automatically in site preview.

Changes to event data and catalog entities

In V3 update events, event.entity contains the updated entity. Some V3 events use a different structure. For example, the V3 Inventory Item Stock Status Updated event provides its stock-status data in event.data. Use each linked V3 event reference for its full payload.

Products, variants, collections, and inventory have different structures in V3. Use the entity conversion tables to map the fields your handler reads or updates.

Event conversion table

This table covers catalog events. It excludes cart and order events.

Catalog V1 event	Event to use with Catalog V3	Migration notes
Product Created	Product Created
Product Updated	Product Updated
Product Deleted	Product Deleted
Variants Updated	Product Updated	Variant changes trigger Product Updated. Read current variants from event.entity.variantsInfo.
Collection Created	Category Created	Collections become categories.
Collection Updated	Category Updated	Collections become categories.
Collection Deleted	Category Deleted	Collections become categories.
Inventory Item Updated	Inventory Item Updated	See Inventory item terminology.
Inventory Variant Updated	Inventory Item Updated	Use Inventory Item Updated for quantity changes. Use Inventory Item Stock Status Updated only for changes between in stock and out of stock.

Category events are documented in the wix-categories.v2 Velo package, separately from wix-stores.v3.

Inventory item terminology

The term inventory item has a different meaning in each version:

• In V1, an inventory item belongs to a product. Its inventory variants hold stock data for the product's variants.
• In V3, an inventory item holds stock data for one product variant at one location.

A product with two variants at two locations can have four V3 inventory items. Do not reuse V1 inventory item IDs. Find the V3 item by product, variant, and location. See the Inventory Items API.