> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/introduction.md

## Article Content:

# 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/introduction.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/introduction.md).

For more information about how options and variants work together, see [About Product Options and Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-product-options-and-variants.md).

## Query vs Search

Choose the right method for your use case:

- **[Query Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/query-variants.md)**: Use for simple, structured filtering operations. Ideal when you know specific criteria like product ID or variant ID.
- **[Search Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/search-variants.md)**: 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/introduction.md) (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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/introduction.md) 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](https://www.wix.com/app-market/wix-stores).
- Variants for non-visible products require the `SCOPE.STORES.PRODUCT_READ_ADMIN` permission.

## Use cases
- [Manage inventory across multiple products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/sample-flows.md#manage-inventory-across-multiple-products)
- [Build a variant search interface](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/sample-flows.md#build-a-variant-search-interface)
- [Sync variant pricing with external systems](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/sample-flows.md#sync-variant-pricing-with-external-systems)
- [Create variant analytics dashboard](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/sample-flows.md#create-variant-analytics-dashboard)

## Terminology

For a comprehensive glossary of Catalog V3 terms, see [Terminology](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/terminology.md).

@sdk_package_setup