> 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

# QueryVariants

# Package: catalogV3

# Namespace: ProductVariantsReader

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/query-variants.md

## Permission Scopes:
Read products in v3 catalog: SCOPE.STORES.PRODUCT_READ
Product v3 read admin: SCOPE.STORES.PRODUCT_READ_ADMIN

## Introduction

Retrieve product variants using structured queries with cursor-based pagination.

Use this endpoint for simple filtering operations on `id` and `productId`.
For complex queries with free-text search and aggregations, use Search Variants instead.

Up to 1,000 variants can be returned per request.

To learn about working with _Query_ endpoints, see
[API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md),
and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md).

Learn more about the differences between [_Query_ and _Search_](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md) methods.

---

## REST API

### Schema

```
 Method: queryVariants
 Description: Retrieve product variants using structured queries with cursor-based pagination.  Use this endpoint for simple filtering operations on `id` and `productId`. For complex queries with free-text search and aggregations, use Search Variants instead.  Up to 1,000 variants can be returned per request.  To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md).  Learn more about the differences between [_Query_ and _Search_](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md) methods.
 URL: https://www.wixapis.com/stores/v3/products/query-variants
 Method: POST
 Method parameters:
   param name: fields | type: array<fields> | description: List of additional fields to include in the response. See VariantOps.RequestedFields for available options. 
                 - enum:
                 -     CURRENCY: Include currency information in product data.  Returns the currency code (ISO-4217 format) used for pricing this variant. Defaults to the site's currency unless specified in request headers.
                 -     MERCHANT_DATA: Include merchant-specific data such as cost and profit information.  Returns revenue details including cost, profit, and profit margin. Requires `SCOPE.STORES.PRODUCT_READ_ADMIN` permission scope.
                 -     SUBSCRIPTION_PRICES_INFO: Include subscription pricing information.  Returns calculated prices for different subscription plans with applied discounts. Only relevant for variants that are part of subscription offerings.
                 -     WEIGHT_MEASUREMENT_UNIT_INFO: Include weight measurement unit information.  Returns the weight measurement unit (kg, lb, etc.) used for the variant. Useful for shipping calculations and product comparisons.
   param name: query | type: CursorQuery   
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. 
        - name: limit | type: integer | description: Maximum number of items to return in the results. 
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. 
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` 
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` 
           - name: fieldName | type: string | description: Name of the field to sort by. 
           - name: order | type: SortOrder | description: Sort order. 
                 - enum: ASC, DESC
 Return type: QueryVariantsResponse
  - name: variants | type: array<ReadOnlyVariant> | description: Variants matching the query criteria. 
     - ONE-OF: 
        - name: physicalProperties | type: VariantPhysicalProperties | description: Physical properties such as weight and dimensions.  Required when the product type is `PHYSICAL`. 
           - name: weight | type: number | description: Weight of the variant for shipping calculations.  Used for shipping cost calculations and fulfillment planning. Returned only when you pass `"WEIGHT_MEASUREMENT_UNIT_INFO"` to the `fields` parameter. 
           - name: pricePerUnit | type: PricePerUnit | description: Price per unit measurement information.  Allows customers to compare prices based on a standard unit (like price per kilogram or per liter). Useful for bulk products or items sold by weight or volume. 
              - name: settings | type: PricePerUnitSettings | description: Price per unit measurement settings.  Defines the unit of measurement for price comparison (e.g., per kilogram, per liter). The measurement unit must correspond to the unit set on the parent product. 
                 - name: quantity | type: number | description: Quantity. For example, to define price per per 100 grams, set this field to `100`. 
                 - name: measurementUnit | type: MeasurementUnit | description: Measurement unit. For example, to define price per 100 grams, set this field to "G". 
                         - enum: UNSPECIFIED, ML, CL, L, CBM, MG, G, KG, MM, CM, M, SQM, OZ, LB, FLOZ, PT, QT, GAL, IN, FT, YD, SQFT
              - name: value | type: string | description: Calculated price per unit value.  Shows the variant's price normalized to the standard unit of measurement. For example, if a 500g variant costs $2 and the standard unit is 1kg, this value would be $4. 
              - name: description | type: string | description: Human-readable description of the price per unit.  For example, "per kg" or "per liter". 
        - name: digitalProperties | type: VariantDigitalProperties | description: Digital properties such as downloadable files.  Required when the product type is `DIGITAL`. 
           - name: digitalFile | type: SecuredMedia | description: Digital file available for download after purchase.  The file that customers receive when they purchase this digital variant. 
              - name: id | type: string | description: Media GUID in media manager. 
              - name: fileName | type: string | description: Original file name. 
              - name: fileSize | type: string | description: Original file size. 
              - name: fileType | type: FileType | description: File type. 
                     - enum:
                     -     UNSPECIFIED: Unspecified file type.
                     -     SECURE_PICTURE: Secure picture file.
                     -     SECURE_VIDEO: Secure video file.
                     -     SECURE_DOCUMENT: Secure document file.
                     -     SECURE_MUSIC: Secure music file.
                     -     SECURE_ARCHIVE: Secure archive file.
                     -     SECURE_RAW: Secure raw file.
     - name: id | type: string | description: Variant GUID. 
     - name: visible | type: boolean | description: Whether the variant is visible to site visitors.  Default: `true` 
     - name: sku | type: string | description: Stock keeping unit (SKU) for inventory tracking and identification.  The SKU is typically used for inventory management, order fulfillment, and product identification across different systems. 
     - name: barcode | type: string | description: Barcode for the variant, typically used for point-of-sale systems and inventory management.  Common barcode formats include UPC, EAN, and Code 128. The barcode helps with quick product identification and checkout processes. 
     - name: optionChoices | type: array<OptionChoice> | description: Product option choices that define this variant.  Each option choice represents a specific selection for a product option (like "Size: Large" or "Color: Red"). An empty list indicates this is the default variant of a product with no managed options. 
        - name: optionChoiceIds | type: OptionChoiceIds | description: Option and choice identifiers. 
           - name: optionId | type: string | description: Product option GUID. 
           - name: choiceId | type: string | description: Specific choice GUID within the option. 
        - name: optionChoiceNames | type: OptionChoiceNames | description: Human-readable option and choice names. 
           - name: optionName | type: string | description: Display name of the product option.  For example, "Size", "Color", or "Material". 
           - name: choiceName | type: string | description: Display name of the chosen option value.  For example, "Large", "Red", or "Cotton". 
           - name: renderType | type: string | description: Visual representation style for the option choice.  Determines how the option is displayed in the product selector UI. Common values include "TEXT_CHOICES", "COLOR_CHOICES", or "IMAGE_CHOICES". 
     - name: price | type: PriceInfo | description: Pricing information for the variant. 
        - name: actualPrice | type: FixedMonetaryAmount | description: Current selling price of the variant. 
           - name: amount | type: string | description: Monetary amount. For example, `"3.99"`, or `"-4.99"` for a negative amount. 
           - name: formattedAmount | type: string | description: Formatted monetary amount. For example, `"$3.99"`. > **Note:** Returned only when you pass `"CURRENCY"` to the `fields` array in Read-Only Variants API requests. 
        - name: compareAtPrice | type: FixedMonetaryAmount | description: Original price before any discounts.  Used to show customers the savings when the variant is on sale. If not set, no original price is displayed. 
     - name: revenueDetails | type: RevenueDetails | description: Revenue and cost details for business analytics.  Includes cost, profit, and profit margin calculations. Returned only when you pass `"MERCHANT_DATA"` to the `fields` parameter. 
        - name: cost | type: FixedMonetaryAmount | description: Cost of the variant for profit calculations.  The amount you pay to produce or acquire this variant. 
        - name: profit | type: FixedMonetaryAmount | description: Profit amount calculated by subtracting cost from the discounted price. 
        - name: profitMargin | type: number | description: Profit margin as a percentage of the selling price.  Calculated by dividing profit by the discounted price. The result is rounded to 4 decimal places. A value of 0.25 represents a 25% profit margin. 
     - name: media | type: ProductMedia | description: Media associated with the variant.  Typically includes images, videos, or other media files specific to this variant. 
        - name: altText | type: string | description: Image alt text. 
        - name: displayName | type: string | description: Media display name. Allows to override the default media name. Can be passed only when `setBy: url`. 
        - name: mediaType | type: MediaType | description: Media type. 
             - enum:
             -     IMAGE: Image media type.
             -     VIDEO: Video media type.
        - name: thumbnail | type: Thumbnail | description: Media thumbnail. 
           - name: url | type: string | description: Thumbnail URL. 
           - name: height | type: integer | description: Thumbnail height. 
           - name: width | type: integer | description: Thumbnail width. 
           - name: altText | type: string | description: Thumbnail alt text. 
        - name: uploadId | type: string | description: GUID used to upload media to Wix Media Manager. 
     - name: subscriptionPricesInfo | type: SubscriptionPricesInfo | description: Subscription pricing information when the variant is part of subscription plans.  Shows calculated prices after applying subscription discounts to the variant's price. Returned only when you pass `"SUBSCRIPTION_PRICES_INFO"` to the `fields` parameter. 
        - name: subscriptionPrices | type: array<SubscriptionPrice> | description: Pricing for different subscription plans.  Shows how the variant's price changes with different subscription intervals or discounts. 
           - name: subscriptionId | type: string | description: Subscription plan GUID. 
           - name: price | type: FixedMonetaryAmount | description: Variant price with subscription discount applied. 
           - name: pricePerUnit | type: SubscriptionPricePerUnit | description: Price per unit for subscription pricing. 
              - name: value | type: string | description: Calculated price per unit for the subscription.  Takes into account the subscription discount and the variant's price per unit settings. 
              - name: description | type: string | description: Description of the subscription price per unit. 
     - name: inventoryStatus | type: InventoryStatus | description: Current inventory and availability status. 
        - name: inStock | type: boolean | description: Whether the variant is currently in stock and available for purchase. 
        - name: preorderEnabled | type: boolean | description: Whether customers can place preorders for this variant when it's out of stock. 
     - name: productData | type: ProductFields | description: Product information for context and convenience.  Includes essential product details like name, visibility, and categories to avoid requiring separate product API calls when working with variants. 
        - ONE-OF: 
           - name: physicalProperties | type: PhysicalProperties | description: Physical product properties such as weight and dimensions.  Required when `productType` is `PHYSICAL`. 
              - name: weightMeasurementUnitInfo | type: WeightMeasurementUnitInfo | description: Weight measurement unit information for the product.  Defines the unit of measurement (kg, lb, etc.) used for product weight calculations. Returned only when you pass `"WEIGHT_MEASUREMENT_UNIT_INFO"` to the `fields` parameter. 
                 - name: weightMeasurementUnit | type: WeightUnit | description: Unit of measurement for weight.  Standard units include kilograms (KG), pounds (LB), ounces (OZ), and grams (G). 
                         - enum:
                         -     UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error.
                         -     KG: Kilograms.
                         -     LB: Pounds.
        - name: productId | type: string | description: Product GUID. 
        - name: name | type: string | description: Product name displayed to customers. 
        - name: productType | type: ProductType | description: Type of product determining available properties and behavior. 
             - enum:
             -     PHYSICAL: Physical product.
             -     DIGITAL: Digital product.
        - name: slug | type: string | description: URL-friendly identifier for the product.  Used in product page URLs and for SEO optimization. 
        - name: visible | type: boolean | description: Whether the product is visible to site visitors.  Default: `true` 
        - name: visibleInPos | type: boolean | description: Whether the product appears in point-of-sale systems.  Default: `true` Always `false` for digital products. 
        - name: mainCategoryId | type: string | description: Primary category assignment for the product.  Determines the main category used for navigation and organization. 
        - name: currency | type: string | description: Currency used for pricing this product.  Three-letter currency code in ISO-4217 alphabetic format. Defaults to the site's currency setting unless specified in request headers. Returned only when you pass `"CURRENCY"` to the `fields` parameter. 
        - name: revision | type: string | description: Revision number, which increments by 1 each time the product is updated. To prevent conflicting changes, the current revision must be passed when updating the product. 
        - name: handle | type: string | description: A unique human-friendly identifier for the product.  The handle can be set by the user to ensure consistency across multiple platforms. 
  - name: pagingMetadata | type: CursorPagingMetadata | description: Pagination information with cursors for next pages. 
     - name: count | type: integer | description: Number of items returned in the response. 
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. 
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results. 
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. 
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page. 


```

### Examples

### Query Variants
Retrieve product variants filtered by variant IDs.

```curl
curl -X POST 'https://www.wixapis.com/stores/v3/products/query-variants' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
      "fields": [],
      "query": {
        "filter": {
          "id": {
            "$in": [
              "acb1b5ef-ca5a-4a13-97fc-4a378f558be1",
              "d0906ff4-06ab-4fa3-9c34-b167dcd96403"
            ]
          }
        }
      }
    }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.catalogV3.ProductVariantsReader.queryVariants(query, options)
 Description: Retrieve product variants using structured queries with cursor-based pagination.  Use this endpoint for simple filtering operations on `id` and `productId`. For complex queries with free-text search and aggregations, use Search Variants instead.  Up to 1,000 variants can be returned per request.  To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), and [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md).  Learn more about the differences between [_Query_ and _Search_](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md) methods.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  query
 Method parameters: 
   param name: options | type: QueryVariantsOptions  none 
        - name: fields | type: array<RequestedFields> | description: List of additional fields to include in the response. See VariantOps.RequestedFields for available options. 
             - enum:
             -     CURRENCY: Include currency information in product data.  Returns the currency code (ISO-4217 format) used for pricing this variant. Defaults to the site's currency unless specified in request headers.
             -     MERCHANT_DATA: Include merchant-specific data such as cost and profit information.  Returns revenue details including cost, profit, and profit margin. Requires `SCOPE.STORES.PRODUCT_READ_ADMIN` permission scope.
             -     SUBSCRIPTION_PRICES_INFO: Include subscription pricing information.  Returns calculated prices for different subscription plans with applied discounts. Only relevant for variants that are part of subscription offerings.
             -     WEIGHT_MEASUREMENT_UNIT_INFO: Include weight measurement unit information.  Returns the weight measurement unit (kg, lb, etc.) used for the variant. Useful for shipping calculations and product comparisons.
   param name: query | type: ReadOnlyVariantQuery   | required: true
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. 
        - name: limit | type: integer | description: Maximum number of items to return in the results. 
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. 
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` 
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` 
           - name: fieldName | type: string | description: Name of the field to sort by. 
           - name: order | type: SortOrder | description: Sort order. 
                 - enum: ASC, DESC
 Return type: PROMISE<QueryVariantsResponse>
  - name: variants | type: array<ReadOnlyVariant> | description: Variants matching the query criteria. 
     - ONE-OF: 
        - name: physicalProperties | type: VariantPhysicalProperties | description: Physical properties such as weight and dimensions.  Required when the product type is `PHYSICAL`. 
           - name: weight | type: number | description: Weight of the variant for shipping calculations.  Used for shipping cost calculations and fulfillment planning. Returned only when you pass `"WEIGHT_MEASUREMENT_UNIT_INFO"` to the `fields` parameter. 
           - name: pricePerUnit | type: PricePerUnit | description: Price per unit measurement information.  Allows customers to compare prices based on a standard unit (like price per kilogram or per liter). Useful for bulk products or items sold by weight or volume. 
              - name: settings | type: PricePerUnitSettings | description: Price per unit measurement settings.  Defines the unit of measurement for price comparison (e.g., per kilogram, per liter). The measurement unit must correspond to the unit set on the parent product. 
                 - name: quantity | type: number | description: Quantity. For example, to define price per per 100 grams, set this field to `100`. 
                 - name: measurementUnit | type: MeasurementUnit | description: Measurement unit. For example, to define price per 100 grams, set this field to "G". 
                         - enum: UNSPECIFIED, ML, CL, L, CBM, MG, G, KG, MM, CM, M, SQM, OZ, LB, FLOZ, PT, QT, GAL, IN, FT, YD, SQFT
              - name: value | type: string | description: Calculated price per unit value.  Shows the variant's price normalized to the standard unit of measurement. For example, if a 500g variant costs $2 and the standard unit is 1kg, this value would be $4. 
              - name: description | type: string | description: Human-readable description of the price per unit.  For example, "per kg" or "per liter". 
        - name: digitalProperties | type: VariantDigitalProperties | description: Digital properties such as downloadable files.  Required when the product type is `DIGITAL`. 
           - name: digitalFile | type: SecuredMedia | description: Digital file available for download after purchase.  The file that customers receive when they purchase this digital variant. 
              - name: _id | type: string | description: Media GUID in media manager. 
              - name: fileName | type: string | description: Original file name. 
              - name: fileSize | type: string | description: Original file size. 
              - name: fileType | type: FileType | description: File type. 
                     - enum:
                     -     UNSPECIFIED: Unspecified file type.
                     -     SECURE_PICTURE: Secure picture file.
                     -     SECURE_VIDEO: Secure video file.
                     -     SECURE_DOCUMENT: Secure document file.
                     -     SECURE_MUSIC: Secure music file.
                     -     SECURE_ARCHIVE: Secure archive file.
                     -     SECURE_RAW: Secure raw file.
     - name: _id | type: string | description: Variant GUID. 
     - name: visible | type: boolean | description: Whether the variant is visible to site visitors.  Default: `true` 
     - name: sku | type: string | description: Stock keeping unit (SKU) for inventory tracking and identification.  The SKU is typically used for inventory management, order fulfillment, and product identification across different systems. 
     - name: barcode | type: string | description: Barcode for the variant, typically used for point-of-sale systems and inventory management.  Common barcode formats include UPC, EAN, and Code 128. The barcode helps with quick product identification and checkout processes. 
     - name: optionChoices | type: array<OptionChoice> | description: Product option choices that define this variant.  Each option choice represents a specific selection for a product option (like "Size: Large" or "Color: Red"). An empty list indicates this is the default variant of a product with no managed options. 
        - name: optionChoiceIds | type: OptionChoiceIds | description: Option and choice identifiers. 
           - name: optionId | type: string | description: Product option GUID. 
           - name: choiceId | type: string | description: Specific choice GUID within the option. 
        - name: optionChoiceNames | type: OptionChoiceNames | description: Human-readable option and choice names. 
           - name: optionName | type: string | description: Display name of the product option.  For example, "Size", "Color", or "Material". 
           - name: choiceName | type: string | description: Display name of the chosen option value.  For example, "Large", "Red", or "Cotton". 
           - name: renderType | type: string | description: Visual representation style for the option choice.  Determines how the option is displayed in the product selector UI. Common values include "TEXT_CHOICES", "COLOR_CHOICES", or "IMAGE_CHOICES". 
     - name: price | type: PriceInfo | description: Pricing information for the variant. 
        - name: actualPrice | type: FixedMonetaryAmount | description: Current selling price of the variant. 
           - name: amount | type: string | description: Monetary amount. For example, `"3.99"`, or `"-4.99"` for a negative amount. 
           - name: formattedAmount | type: string | description: Formatted monetary amount. For example, `"$3.99"`. > **Note:** Returned only when you pass `"CURRENCY"` to the `fields` array in Read-Only Variants API requests. 
        - name: compareAtPrice | type: FixedMonetaryAmount | description: Original price before any discounts.  Used to show customers the savings when the variant is on sale. If not set, no original price is displayed. 
     - name: revenueDetails | type: RevenueDetails | description: Revenue and cost details for business analytics.  Includes cost, profit, and profit margin calculations. Returned only when you pass `"MERCHANT_DATA"` to the `fields` parameter. 
        - name: cost | type: FixedMonetaryAmount | description: Cost of the variant for profit calculations.  The amount you pay to produce or acquire this variant. 
        - name: profit | type: FixedMonetaryAmount | description: Profit amount calculated by subtracting cost from the discounted price. 
        - name: profitMargin | type: number | description: Profit margin as a percentage of the selling price.  Calculated by dividing profit by the discounted price. The result is rounded to 4 decimal places. A value of 0.25 represents a 25% profit margin. 
     - name: media | type: ProductMedia | description: Media associated with the variant.  Typically includes images, videos, or other media files specific to this variant. 
        - name: altText | type: string | description: Image alt text. 
        - name: displayName | type: string | description: Media display name. Allows to override the default media name. Can be passed only when `setBy: url`. 
        - name: mediaType | type: MediaType | description: Media type. 
             - enum:
             -     IMAGE: Image media type.
             -     VIDEO: Video media type.
        - name: thumbnail | type: Thumbnail | description: Media thumbnail. 
           - name: url | type: string | description: Thumbnail URL. 
           - name: height | type: integer | description: Thumbnail height. 
           - name: width | type: integer | description: Thumbnail width. 
           - name: altText | type: string | description: Thumbnail alt text. 
        - name: uploadId | type: string | description: GUID used to upload media to Wix Media Manager. 
     - name: subscriptionPricesInfo | type: SubscriptionPricesInfo | description: Subscription pricing information when the variant is part of subscription plans.  Shows calculated prices after applying subscription discounts to the variant's price. Returned only when you pass `"SUBSCRIPTION_PRICES_INFO"` to the `fields` parameter. 
        - name: subscriptionPrices | type: array<SubscriptionPrice> | description: Pricing for different subscription plans.  Shows how the variant's price changes with different subscription intervals or discounts. 
           - name: subscriptionId | type: string | description: Subscription plan GUID. 
           - name: price | type: FixedMonetaryAmount | description: Variant price with subscription discount applied. 
           - name: pricePerUnit | type: SubscriptionPricePerUnit | description: Price per unit for subscription pricing. 
              - name: value | type: string | description: Calculated price per unit for the subscription.  Takes into account the subscription discount and the variant's price per unit settings. 
              - name: description | type: string | description: Description of the subscription price per unit. 
     - name: inventoryStatus | type: InventoryStatus | description: Current inventory and availability status. 
        - name: inStock | type: boolean | description: Whether the variant is currently in stock and available for purchase. 
        - name: preorderEnabled | type: boolean | description: Whether customers can place preorders for this variant when it's out of stock. 
     - name: productData | type: ProductFields | description: Product information for context and convenience.  Includes essential product details like name, visibility, and categories to avoid requiring separate product API calls when working with variants. 
        - ONE-OF: 
           - name: physicalProperties | type: PhysicalProperties | description: Physical product properties such as weight and dimensions.  Required when `productType` is `PHYSICAL`. 
              - name: weightMeasurementUnitInfo | type: WeightMeasurementUnitInfo | description: Weight measurement unit information for the product.  Defines the unit of measurement (kg, lb, etc.) used for product weight calculations. Returned only when you pass `"WEIGHT_MEASUREMENT_UNIT_INFO"` to the `fields` parameter. 
                 - name: weightMeasurementUnit | type: WeightUnit | description: Unit of measurement for weight.  Standard units include kilograms (KG), pounds (LB), ounces (OZ), and grams (G). 
                         - enum:
                         -     UNSPECIFIED_WEIGHT_UNIT: Weight unit can't be classified due to an error.
                         -     KG: Kilograms.
                         -     LB: Pounds.
        - name: productId | type: string | description: Product GUID. 
        - name: name | type: string | description: Product name displayed to customers. 
        - name: productType | type: ProductType | description: Type of product determining available properties and behavior. 
             - enum:
             -     PHYSICAL: Physical product.
             -     DIGITAL: Digital product.
        - name: slug | type: string | description: URL-friendly identifier for the product.  Used in product page URLs and for SEO optimization. 
        - name: visible | type: boolean | description: Whether the product is visible to site visitors.  Default: `true` 
        - name: visibleInPos | type: boolean | description: Whether the product appears in point-of-sale systems.  Default: `true` Always `false` for digital products. 
        - name: mainCategoryId | type: string | description: Primary category assignment for the product.  Determines the main category used for navigation and organization. 
        - name: currency | type: string | description: Currency used for pricing this product.  Three-letter currency code in ISO-4217 alphabetic format. Defaults to the site's currency setting unless specified in request headers. Returned only when you pass `"CURRENCY"` to the `fields` parameter. 
        - name: revision | type: string | description: Revision number, which increments by 1 each time the product is updated. To prevent conflicting changes, the current revision must be passed when updating the product. 
        - name: handle | type: string | description: A unique human-friendly identifier for the product.  The handle can be set by the user to ensure consistency across multiple platforms. 
  - name: pagingMetadata | type: CursorPagingMetadata | description: Pagination information with cursors for next pages. 
     - name: count | type: integer | description: Number of items returned in the response. 
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. 
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results. 
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. 
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page. 


```

### Examples

### Query variants
Query variants filtered by variant IDs

```javascript
import { readOnlyVariantsV3 } from "@wix/stores";

const options = {
  fields: [],
  query: {
    filter: {
      id: {
        $in: [
          "acb1b5ef-ca5a-4a13-97fc-4a378f558be1",
          "d0906ff4-06ab-4fa3-9c34-b167dcd96403"
        ]
      }
    }
  }
};

async function queryVariants() {
  const response = await readOnlyVariantsV3.queryVariants(options);
}

/* Promise resolves to:
 * {
 *   "variants": [
 *     {
 *       "_id": "acb1b5ef-ca5a-4a13-97fc-4a378f558be1",
 *       "visible": true,
 *       "price": { "actualPrice": { "amount": "10.00" } },
 *       "productData": { "productId": "product-1", "name": "Coffee", "productType": "PHYSICAL" },
 *       "inventoryStatus": { "inStock": true }
 *     },
 *     {
 *       "_id": "d0906ff4-06ab-4fa3-9c34-b167dcd96403",
 *       "visible": true,
 *       "price": { "actualPrice": { "amount": "15.00" } },
 *       "productData": { "productId": "product-2", "name": "Tea", "productType": "PHYSICAL" },
 *       "inventoryStatus": { "inStock": false }
 *     }
 *   ],
 *   "pagingMetadata": { "count": 2, "cursors": {}, "hasNext": false }
 * }
 */


```

### queryVariants (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { readOnlyVariantsV3 } from '@wix/stores';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { readOnlyVariantsV3 },
  // Include the auth strategy and host as relevant
});


async function queryVariants(query,options) {
  const response = await myWixClient.readOnlyVariantsV3.queryVariants(query,options);
};
```

---