About the Wix Stores Catalog V3

The Catalog V3 APIs allow you to manage Wix Stores product catalogs. This includes creating and updating products, managing inventory across multiple locations, organizing products with categories and brands, and configuring product options and customizations.

Before you begin

It's important to note the following before starting to code:

  • Each site supports either Catalog V1 or Catalog V3, but not both at the same time. Use the Catalog Versioning API to determine which version a site uses.
  • When you create a new dev site to test your app on, the dev site supports Catalog V3.
  • If your app currently uses the Catalog V1 API, there are several important considerations:
    • Catalog V3 will initially be rolled out to new users only.
    • To continue supporting both new and existing users, your app must support both Catalog V1 and Catalog V3. In your app's dashboard, you will need to confirm compatibility with Catalog V3 to allow Wix users to install your app.
    • Over time, Catalog V3 will fully replace Catalog V1.
    • Learn more about migrating from Catalog V1 to Catalog V3.

Catalog V3 services

Catalog V3 provides a comprehensive set of services, each designed to handle specific aspects of product catalog management:

Products V3

The core service for managing product information and variants. Used for product catalog management, inventory synchronization, storefront display, and more.

Key capabilities include:

  • Product management - Create, update, delete, and query products.
  • Universal variants - Every product has at least one variant. Products without options have a single "default variant" with an empty choices array.
  • Advanced variant handling - Manage complex product variations with options, choices, pricing, and inventory at the variant level.
  • Media management - Associate images, videos, and other media with products and option choices.
  • Bulk operations - Efficiently manage large catalogs with bulk create, update, and delete operations.

Note: When creating products with inline options or modifiers (without referencing existing customization IDs), new standalone Customization entities are automatically created. These can be reused across other products.

Read-Only Variants V3

A read-only service for querying product variants directly. Used for variant-focused inventory management, building variant search interfaces, and syncing variant data with external systems.

Key capabilities include:

  • Variant-centric queries - Query variants directly rather than as nested objects within products.
  • Advanced pagination - Cursor-based pagination supporting up to 1,000 variants per request.
  • Free-text search - Search variants by product name.

Note: This API operates on an eventually consistent model. Changes made through the Products API sync to this service over time.

Inventory Items V3

Dedicated service for inventory tracking and stock management. Used for warehouse management, dropshipping workflows, multi-location retail, and inventory forecasting.

Key capabilities include:

  • Per-variant, per-location tracking - Each inventory item represents a specific variant at a specific location, enabling granular inventory control.
  • Real-time stock tracking - Monitor inventory levels with automatic updates and availability calculations.
  • Preorder management - Configure preorder settings per inventory item, allowing different preorder rules for each variant-location combination.
  • Bulk inventory operations - Efficiently update inventory across large product catalogs.

Note: The Create Product method doesn't automatically create inventory items. Use Create Product With Inventory to create both in a single call, or create inventory items separately using this API.

Customizations V3

Enables product personalization and customization. Customizations can be options (which create variants and affect inventory) or modifiers (which collect additional information without creating variants). Used for print-on-demand products, personalized gifts, custom apparel, and product size/color variations.

Key capabilities include:

  • Options - Create product variations with different SKUs, prices, and inventory tracking. Each combination of option choices creates a variant.
  • Modifiers - Allow customers to customize products with text and selection choices without affecting variants or inventory.
  • Flexible input types - Support text choices, color swatches, and free-text inputs.
  • Reusable customizations - Create customizations that can be assigned to multiple products.

Note: Options can't be deleted while assigned to any product because they affect variants. Modifiers can be deleted freely and are automatically removed from assigned products.

Info Sections V3

Manages reusable product information sections. Used for technical specifications, size charts, care instructions, warranty information, and detailed product descriptions.

Key capabilities include:

  • Rich content sections - Create detailed product information with titles and descriptions.
  • Reusable content blocks - Share common information across multiple products using unique names.

Note: When an info section is deleted, it's automatically removed from all products that reference it.

Brands V3

Brand management system for organizing products by manufacturer or brand identity. Used for multi-brand retail, brand catalog organization, and brand-based marketing campaigns.

Key capabilities include:

  • Brand profiles - Create and manage brand information.
  • Brand associations - Link products to brands for organization and filtering.

Note: When a brand is deleted, it's automatically removed from all products that reference it.

Ribbons V3

Flexible system for product badges, labels, and promotional highlighting. Used for promotional campaigns, seasonal sales, new product launches, and product highlighting.

Key capabilities include:

  • Promotional badges - Create "Sale", "New", "Featured", and custom promotional labels.
  • Visual customization - Control ribbon appearance with text and colors.

Note: When a ribbon is deleted, it's automatically removed from all products that reference it.

Stores Locations V3

A read-only API that provides access to inventory locations for Wix Stores. Used for multi-location retail, regional inventory management, local delivery services, and pickup locations.

Key capabilities include:

  • Location data access - Query store locations, warehouses, and fulfillment centers.
  • Location-based inventory - Use location IDs to track inventory levels via the Inventory Items API.
  • Default location handling - Every store has a default location that's automatically created.

Note: This is a read-only API. To create or update locations, use the Wix Locations API and include "INVENTORY" in the locationTypes array.

Categories

External service for category management that integrates with Catalog V3. Used for product organization, storefront navigation, catalog browsing, and taxonomic product classification.

Key capabilities include:

  • Hierarchical categories - Create nested category structures with unlimited depth.
  • Category relationships - Manage parent-child relationships and category associations.
  • Category metadata - Add descriptions, images, and SEO data to categories.
  • Multi-category assignment - Assign products to multiple categories simultaneously.

Terminology

For a comprehensive glossary of Catalog V3 terms, see Terminology.

Questions?

Reach out to us via our Discord channel, or open a ticket with WixBot.

Did this help?