About the Read-Only Variants V3 API

Overview

The Read-Only Variants V3 API allows you to query product variants as primary entities with enhanced pagination, filtering, and sorting capabilities. Unlike the Product API where variants are nested within products, this service focuses exclusively on variants, making it easier to implement variant-focused features. Use the Read-Only Variants API when you need to search and filter variants across multiple products efficiently.

Key Features

• 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.
• Flexible filtering: Use WQL (Wix Query Language) for complex filtering operations.
• Free-text search: Search variants by product name.
• Aggregation support: Get faceted search results for building advanced filtering UIs.

API Methods

QueryVariants vs SearchVariants

Choose the right method for your use case:

• queryVariants: Use for simple, structured filtering operations. Ideal when you know specific criteria like product ID and/or variant ID.
• searchVariants: 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 Model

Variant structure

Each variant includes:

• Variant-specific data: ID, SKU, barcode, pricing, inventory status, and option choices.
• Product context: Product name, visibility, categories, and other product details.
• Type-specific properties: Physical properties (weight) for physical products, digital files for digital products.
• Conditional data: Revenue details, subscription pricing, and currency information when requested.

Option choices

Variants are defined by their option choices (like "Size: Large" or "Color: Red"). Each option choice includes:

• IDs: For programmatic use and relationships.
• Names: Human-readable labels for display.
• Render type: UI guidance for how to display the option (text, color swatches, images).

Data consistency

This API operates on an eventually consistent model. Changes made through the Products V3 API (creating, updating, or deleting variants) will synchronize 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 V3 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.

Integration Considerations

Performance

• Each request can return up to 1,000 variants with full context.
• Consider caching frequently accessed variant data.

Error handling

• Variants for non-visible products and/or variants are filtered based on your permissions.
• Invalid queries return clear validation messages.