Wix Catalog V1 to V3: Critical Changes That Could Break Your Store

Key Points

Wix Catalog V3, rolling out in Q2 2025, introduces major updates to product and inventory management.
Changes like variant-level pricing and new APIs may break existing site functionalities.
Sites must support either V1 or V3, not both, requiring careful migration planning.
Early preparation, including code updates and testing, is essential to avoid disruptions.

Why This Matters

Wix Catalog is the backbone of Wix Stores, managing your product listings and inventory. The shift from Catalog V1 to V3, launched in Q2 2025, brings powerful new features but also significant changes that could disrupt your online store if not addressed. These updates affect how products, pricing, and inventory are handled, potentially breaking custom code or integrations.

Major Risks

Key changes include moving pricing fields to variants, removing fields like manageVariants, and introducing new APIs for inventory and customizations. If your site relies on V1 structures, these updates could cause errors in product displays, pricing, or inventory tracking. Since sites can only use one catalog version at a time, upgrading to V3 without preparation may lead to downtime or lost sales.

How to Prepare

To avoid issues, review the Catalog V1 to V3 Conversion Guide, request early access to V3, and update your site’s code and integrations. Use the Catalog Versioning API to check your site’s version and test thoroughly before going live with V3.

Comprehensive Warning: Wix Catalog V1 to V3 Transition Risks and Preparation

Introduction

Wix Catalog is the core system for managing product listings, inventory, and related functionalities in Wix Stores. With the rollout of Wix Catalog V3 in Q2 2025, Wix is introducing significant enhancements to improve store management, including better variant handling and advanced inventory tools. However, these updates come with substantial changes from Catalog V1 that could break existing Wix store sites if not properly managed. This article outlines the major changes, their implications, and essential steps for Wix store users to ensure a smooth transition and avoid disruptions.

Major Changes from Catalog V1 to V3

The transition from Wix Catalog V1 to V3 involves critical structural and functional changes that may impact existing sites. Below is a detailed list of these changes, based on the Catalog V1 to V3 Conversion Guide:

Change	Description	Potential Impact
Product to Variant Field Relocation	Fields like `actualPrice` and `compareAtPrice` have moved from the product level to the variant level for more granular control.	Sites expecting these fields at the product level may display incorrect pricing or encounter errors.
Universal Variants	Every product now has at least one variant, with products without options treated as "single variant products."	Sites assuming products can exist without variants may fail to process products correctly.
Variant Management	The `manageVariants` field has been removed; all products now inherently have variants.	Sites using `manageVariants` for logic will break and require updates to the new variant structure.
Discount Replacement	The `discount` field is replaced by `actualPrice` at the variant level.	Pricing logic or displays relying on the `discount` field will fail, requiring updates to use `actualPrice`.
Price Data Changes	`priceData` and `convertedPriceData` fields are no longer available; pricing is now variant-level.	Sites using these fields for pricing calculations will need to adapt to variant-level fields.
Options and Customizations	The Customizations V3 API replaces the V1 options system for managing product options and modifiers.	Sites using V1 options must migrate to the new API, or customizations may not function.
Custom Text Fields	Custom text fields are now part of the Customizations modifier type.	Sites accessing custom text fields at the product level must use the Customizations API.
Inventory and Stock	Inventory and stock data have moved to the Inventory Items API, with each variant having its own inventory.	Sites accessing stock at the product level will break; updates to use the new API with `productId`/`variantId` filtering are needed.
Media and Other Fields	Fields like media, ribbons, and brands have moved to new APIs (e.g., Ribbons API, Brands API).	Sites using old field locations will encounter errors and must update to new APIs.
Webhook Changes	Webhook structures have changed, e.g., `productId` is now `entityId`, and `changedFields` is now `modifiedFields`.	Sites relying on webhooks for notifications must update to the new payload structure (see Product Created, Product Updated).

Implications for Wix Store Users

The shift to Catalog V3 introduces several risks for existing Wix store users:

Backward Incompatibility: Wix sites can only support either Catalog V1 or V3 at a time, as noted in the Catalog Versioning API documentation. Once a site upgrades to V3, V1 features and integrations will no longer work, potentially causing significant disruptions.
Mandatory Migration: Catalog V3 is initially rolling out to new users in Q2 2025, but existing V1 users will eventually be migrated, as V3 will fully replace V1 over time. Delaying preparation could lead to unexpected issues during the mandatory upgrade.
Potential Disruptions: Without updates, sites may experience broken product displays, incorrect pricing, inventory mismatches, or failed integrations, leading to lost sales or customer dissatisfaction.
Third-Party App Impact: Apps or custom code not updated for V3 compatibility may fail, especially if they rely on deprecated fields or APIs.

These implications highlight the urgency for store owners and developers to act proactively to maintain site functionality.

Preparing for the Transition

To mitigate risks and ensure a seamless transition to Catalog V3, Wix store users should follow these steps:

Review the Conversion Guide
- Study the Catalog V1 to V3 Conversion Guide to understand each change and its impact on your site’s functionality.
Check Your Catalog Version
- Use the Catalog Versioning API to determine whether your site is currently using V1 or V3. This is critical for ensuring your integrations target the correct version.
Request Early Access
- Apply for early access to Catalog V3 via this form to test and adapt your site before the full rollout, minimizing surprises.
Update Code and Integrations
- Modify custom code and third-party integrations to align with V3’s structure:
  - Update pricing logic to use variant-level fields like actualPrice.
  - Migrate to the Customizations V3 API for options and custom text fields.
  - Use the Inventory Items API for stock management.
  - Adjust webhook handling to match new structures (e.g., Product Created).
Test Extensively
- After updating, thoroughly test your site to ensure product listings, pricing, inventory, and customizations function correctly with V3. Test edge cases, such as single variant products or complex customizations.
Stay Informed
- Join the Wix Developer Discord channel to stay updated on V3 changes, bug fixes, and new features during the preview period.

Additional Considerations

Developer Support: If your site relies heavily on custom code or third-party apps, consider consulting a developer familiar with Wix APIs to assist with the migration.
Backup Your Data: Before upgrading to V3, back up your product catalog and site data to prevent potential loss during the transition.
Monitor Performance: After migrating, monitor your site’s performance and customer feedback to quickly address any issues that arise.

Conclusion

The transition from Wix Catalog V1 to V3, launched in Q2 2025, offers powerful new tools for managing online stores but introduces significant changes that could disrupt unprepared sites. By understanding the key changes—such as variant-level pricing, new APIs, and webhook updates—and taking proactive steps to update your site, you can avoid potential issues and leverage V3’s enhanced capabilities. Act now to review the conversion guide, request early access, and test your updates to ensure your Wix store remains functional and competitive.

Critical Alert: Q2-2025 Wix Catalog V3 Migration - What Wix Product Store Owners Need to Know