The Read-Only Variants 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.
For creating, updating, or deleting variants, use the Products V3 API instead.
- 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.
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.
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.
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).
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.
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.
- Each request can return up to 1,000 variants with full context.
- Consider caching frequently accessed variant data.
- Variants for non-visible products and/or variants are filtered based on your permissions.
- Invalid queries return clear validation messages.