About the Read-Only Variants API

The Read-Only Variants API allows you to query product variants as primary entities with enhanced pagination, filtering, and sorting capabilities. Unlike the Products API where variants are nested within products, this service focuses exclusively on variants, making it easier to implement variant-focused features.

With the Read-Only Variants API, you can:

• Query variants directly rather than as nested objects within products.
• Use cursor-based pagination supporting up to 1,000 variants per request.
• Filter variants using WQL (Wix Query Language) for complex filtering operations.
• Search variants by product name with free-text search.

For creating, updating, or deleting variants, use the Products API.

For more information about how options and variants work together, see About Product Options and Variants.

Query vs Search

Choose the right method for your use case:

• Query Variants: Use for simple, structured filtering operations. Ideal when you know specific criteria like product ID or variant ID.
• Search Variants: Use for complex queries involving free-text search, aggregations, or faceted search for all other fields.

Both methods support cursor-based pagination and return the same variant data structure.

Data consistency

This API operates on an eventually consistent model. Changes made through the Products API (creating, updating, or deleting variants) sync to this service over time. This design optimizes read performance while ensuring data integrity.

For real-time accuracy requirements, verify critical data through the Products API before making business decisions.

Field selection

Use the fields parameter to request additional data:

• CURRENCY: Include currency information.
• MERCHANT_DATA: Cost, profit, and margin data (requires admin permissions).
• SUBSCRIPTION_PRICES_INFO: Subscription pricing details.
• WEIGHT_MEASUREMENT_UNIT_INFO: Weight unit information.

Before you begin

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

• The Wix user must install the Wix Stores app.
• Variants for non-visible products require the SCOPE.STORES.PRODUCT_READ_ADMIN permission.

Use cases

• Manage inventory across multiple products
• Build a variant search interface
• Sync variant pricing with external systems
• Create variant analytics dashboard

Terminology

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