> 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

# QueryProductVariants

# Package: catalogV1

# Namespace: CatalogReadApi

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

## Permission Scopes:
Read Products: SCOPE.DC-STORES.READ-PRODUCTS

## Introduction

Retrieves product variants, based on either choices (option-choice key-value pairs) or variant IDs.
See [Stores Pagination](https://dev.wix.com/api/rest/wix-stores/pagination) for more information.

---

## REST API

### Schema

```
 Method: queryProductVariants
 Description: Retrieves product variants, based on either choices (option-choice key-value pairs) or variant GUIDs. See [Stores Pagination](https://dev.wix.com/api/rest/wix-stores/pagination) for more information.
 URL: https://www.wixapis.com/stores-reader/v1/products/{id}/variants/query
 Method: POST
 Method parameters:
   param name: choices | type: choices | description: The specific choices available or chosen from within a selection (e.g., choosing the red Selection triggers the red Choice). You may specify all the relevant choices for a specific variant, or only some of the options, which will return all corresponding variants (not relevant when passing variant GUIDs). 
        - name: key | type: string | description: none 
        - name: value | type: string | description: none 
   param name: includeMerchantSpecificData | type: includeMerchantSpecificData | description: Whether merchant specific data should be included in the response. Requires permissions to manage products. 
   param name: paging | type: Paging   
        - name: limit | type: integer | description: Amount of items to load per page 
        - name: offset | type: integer | description: Number of items to skip in the display (relevant for all pages after the first) 
   param name: variantIds | type: array<variantIds> | description: List of variant GUIDs (not relevant when passing choices). 
 Return type: QueryProductVariantsResponse
  - name: variants | type: array<Variant> | description: List of variants based on the specified filters and sorting. 
     - name: id | type: string | description: Requested Variant GUID 
     - name: choices | type: object | description: Specific choices within a selection, as option-choice key-value pairs 
     - name: variant | type: VariantDataWithNoStock | description:  
        - name: priceData | type: PriceData | description: Variant price. 
           - name: currency | type: string | description: Product price currency 
           - name: price | type: number | description: Product price 
           - name: discountedPrice | type: number | description: Discounted product price (if no discounted price is set, the product price is returned) 
           - name: formatted | type: FormattedPrice | description: The product price and discounted price, formatted with the currency 
              - name: price | type: string | description: Product price formatted with the currency 
              - name: discountedPrice | type: string | description: Discounted product price formatted with the currency (if no discounted price is set, the product formatted price is returned) 
              - name: pricePerUnit | type: string | description: Price per unit 
           - name: pricePerUnit | type: number | description: Price per unit 
        - name: convertedPriceData | type: PriceData | description: Variant price data, converted to currency requested in header. 
        - name: costAndProfitData | type: CostAndProfitData | description: Cost and profit data. 
           - name: itemCost | type: number | description: Item cost. 
           - name: formattedItemCost | type: string | description: Item cost formatted with currency symbol. 
           - name: profit | type: number | description: Profit. Calculated by reducing `cost` from `discounted_price`. 
           - name: formattedProfit | type: string | description: Profit formatted with currency symbol. 
           - name: profitMargin | type: number | description: Profit Margin. Calculated by dividing `profit` by `discounted_price`. The result is rounded to 4 decimal places. 
        - name: weight | type: number | description: Variant weight. 
        - name: sku | type: string | description: Variant SKU (stock keeping unit). 
        - name: visible | type: boolean | description: Whether the variant is visible to customers. 
        - name: productDimensions | type: Dimensions | description: Product dimensions (length, width, height of the physical product). 
           - name: length | type: string | description: Length. Measurement unit is handled at the system level (metric/imperial). 
           - name: width | type: string | description: Width. Measurement unit is handled at the system level (metric/imperial). 
           - name: height | type: string | description: Height. Measurement unit is handled at the system level (metric/imperial). 
           - name: unit | type: DimensionsUnit | description: Unit of measurement for dimensions (length, width, height). 
                 - enum:
                 -     UNKNOWN_DIMENSIONS_UNIT: 
                 -     MM: Millimeters.
                 -     CM: Centimeters.
                 -     M: Meters.
                 -     IN: Inches.
                 -     FT: Feet.
                 -     YD: Yards.
        - name: packageDimensions | type: Dimensions | description: Package dimensions (length, width, height of the shipping package). 
     - name: stock | type: VariantStock | description: Variant inventory status. 
        - name: trackQuantity | type: boolean | description: Whether inventory is being tracked. 
        - name: quantity | type: integer | description: Quantity currently left in inventory. 
        - name: inStock | type: boolean | description: Whether the product is currently in stock (relevant only when tracking manually). 
  - name: metadata | type: PagingMetadata | description:  
     - name: items | type: integer | description: Amount of items to load per page 
     - name: offset | type: integer | description: Number of items to skip in the display (relevant for all pages after the first) 
  - name: totalResults | type: integer | description:  


```

### Examples

### QueryProductVariants
```curl
~~~cURL
curl -X POST \
   'https://www.wixapis.com/stores/v1/products/0614129c-8777-9f3b-4dfe-b80a54df10d5/variants/query' \
    --data-binary '{
                      "choices": {
                        "Weight": "250g"
                      },
                      "includeMerchantSpecificData": true
                    }' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: <AUTH>'
~~~
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.catalogV1.CatalogReadApi.queryProductVariants(_id, options)
 Description: Retrieves product variants, based on either choices (option-choice key-value pairs) or variant GUIDs. See [Stores Pagination](https://dev.wix.com/api/rest/wix-stores/pagination) for more information.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  _id
 Method parameters: 
   param name: _id | type: string | description: Requested product GUID. | required: true
   param name: options | type: QueryProductVariantsOptions  none 
        - name: choices | type: object | description: The specific choices available or chosen from within a selection (e.g., choosing the red Selection triggers the red Choice). You may specify all the relevant choices for a specific variant, or only some of the options, which will return all corresponding variants (not relevant when passing variant GUIDs). 
        - name: variantIds | type: array | description: List of variant GUIDs (not relevant when passing choices). 
        - name: paging | type: Paging | description:  
           - name: limit | type: integer | description: Amount of items to load per page 
           - name: offset | type: integer | description: Number of items to skip in the display (relevant for all pages after the first) 
        - name: includeMerchantSpecificData | type: boolean | description: Whether merchant specific data should be included in the response. Requires permissions to manage products. 
 Return type: PROMISE<QueryProductVariantsResponse>
  - name: variants | type: array<Variant> | description: List of variants based on the specified filters and sorting. 
     - name: _id | type: string | description: Requested Variant GUID 
     - name: choices | type: object | description: Specific choices within a selection, as option-choice key-value pairs 
     - name: variant | type: VariantDataWithNoStock | description:  
        - name: priceData | type: PriceData | description: Variant price. 
           - name: currency | type: string | description: Product price currency 
           - name: price | type: number | description: Product price 
           - name: discountedPrice | type: number | description: Discounted product price (if no discounted price is set, the product price is returned) 
           - name: formatted | type: FormattedPrice | description: The product price and discounted price, formatted with the currency 
              - name: price | type: string | description: Product price formatted with the currency 
              - name: discountedPrice | type: string | description: Discounted product price formatted with the currency (if no discounted price is set, the product formatted price is returned) 
              - name: pricePerUnit | type: string | description: Price per unit 
           - name: pricePerUnit | type: number | description: Price per unit 
        - name: convertedPriceData | type: PriceData | description: Variant price data, converted to currency requested in header. 
        - name: costAndProfitData | type: CostAndProfitData | description: Cost and profit data. 
           - name: itemCost | type: number | description: Item cost. 
           - name: formattedItemCost | type: string | description: Item cost formatted with currency symbol. 
           - name: profit | type: number | description: Profit. Calculated by reducing `cost` from `discounted_price`. 
           - name: formattedProfit | type: string | description: Profit formatted with currency symbol. 
           - name: profitMargin | type: number | description: Profit Margin. Calculated by dividing `profit` by `discounted_price`. The result is rounded to 4 decimal places. 
        - name: weight | type: number | description: Variant weight. 
        - name: sku | type: string | description: Variant SKU (stock keeping unit). 
        - name: visible | type: boolean | description: Whether the variant is visible to customers. 
        - name: productDimensions | type: Dimensions | description: Product dimensions (length, width, height of the physical product). 
           - name: length | type: string | description: Length. Measurement unit is handled at the system level (metric/imperial). 
           - name: width | type: string | description: Width. Measurement unit is handled at the system level (metric/imperial). 
           - name: height | type: string | description: Height. Measurement unit is handled at the system level (metric/imperial). 
           - name: unit | type: DimensionsUnit | description: Unit of measurement for dimensions (length, width, height). 
                 - enum:
                 -     UNKNOWN_DIMENSIONS_UNIT: 
                 -     MM: Millimeters.
                 -     CM: Centimeters.
                 -     M: Meters.
                 -     IN: Inches.
                 -     FT: Feet.
                 -     YD: Yards.
        - name: packageDimensions | type: Dimensions | description: Package dimensions (length, width, height of the shipping package). 
     - name: stock | type: VariantStock | description: Variant inventory status. 
        - name: trackQuantity | type: boolean | description: Whether inventory is being tracked. 
        - name: quantity | type: integer | description: Quantity currently left in inventory. 
        - name: inStock | type: boolean | description: Whether the product is currently in stock (relevant only when tracking manually). 
  - name: metadata | type: PagingMetadata | description:  
     - name: items | type: integer | description: Amount of items to load per page 
     - name: offset | type: integer | description: Number of items to skip in the display (relevant for all pages after the first) 
  - name: totalResults | type: integer | description:  


```

### Examples

### Query product variants with choices filter and merchant data
```javascript
import { products } from "@wix/stores";

const productId = "0614129c-8777-9f3b-4dfe-b80a54df10d5";

const options = {
  choices: {
    Weight: "250g"
  },
  includeMerchantSpecificData: true
};

async function queryProductVariants() {
  const response = await products.queryProductVariants(productId, options);
}

/* Promise resolves to:
 * {
 *   "variants": [
 *     {
 *       "_id": "00000000-0000-0020-0005-a316e6ba5b37",
 *       "choices": {
 *         "Weight": "250g",
 *         "Ground for": "Filter"
 *       },
 *       "variant": {
 *         "priceData": {
 *           "currency": "USD",
 *           "price": 35,
 *           "discountedPrice": 26.25,
 *           "formatted": {
 *             "price": "$35.00",
 *             "discountedPrice": "$26.25"
 *           }
 *         },
 *         "costAndProfitData": {
 *           "itemCost": 20,
 *           "profit": 6.25,
 *           "profitMargin": 0.25
 *         },
 *         "weight": 0.25,
 *         "sku": "BRA-250-FIL",
 *         "visible": true
 *       }
 *     }
 *   ],
 *   "pagingMetadata": {
 *     "count": 100,
 *     "offset": 0
 *   },
 *   "totalCount": 2
 * }
 */

```

### Get product variants by variant IDs
```javascript
/**************************************
 * Backend code - products.web.js/ts *
 **************************************/

import { Permissions, webMethod } from '@wix/web-methods';
import { products } from '@wix/stores';

export const getProductVariants = webMethod(Permissions.Anyone, (_id, options) => {
  return products.queryProductVariants(_id, options);
});

/********************
 * Client-side code *
 ********************/
import { getProductVariants } from 'backend/products.web';

let _id = "3fb6a3c8-988b-7895-04bd-5c59ae0b18ea"; // get product ID
let options = {
  variantIds: [
    "00000000-0000-03e1-0005-957f699d0688",
    "00000000-0000-03e2-0005-957f699d0688"
  ]
};

getProductVariants(_id, options)
  .then((response) => {
    let firstVariant = response.variants[0];
    let firstPrice = firstVariant.variant.priceData.price;
    let numberOfReturnedVariants = response.variants.length;
  })
  .catch((error) => {
    console.error(error);
  })

/* Example of returned variants array:
 *
 * [
 *   {
 *     "_id": "00000000-0000-03e1-0005-957f699d0688",
 *     "choices": {
 *       "Size": "Large",
 *       "Color": "Red",
 *       "Pattern": "Paisley"
 *     },
 *     "variant": {
 *       "costAndProfitData": {
 *         "itemCost": 10
 *       },
 *       "priceData": {
 *         "price": 25
 *       },
 *       "weight": 5,
 *       "sku": "217537123517253",
 *       "visible": true
 *     }
 *   },
 *   {
 *     "_id": "00000000-0000-03e2-0005-957f699d0688",
 *     "choices": {
 *       "Size": "Large",
 *       "Color": "Red",
 *       "Pattern": "Houndstooth"
 *     },
 *     "variant": {
 *       "costAndProfitData": {
 *         "itemCost": 10
 *       },
 *       "priceData": {
 *         "price": 25
 *       },
 *       "weight": 5,
 *       "sku": "217537123517253",
 *       "visible": true
 *     }
 *   }
 * ]
 *
 */
```

### Get product variants by specified choices
```javascript
/**************************************
 * Backend code - products.web.js/ts *
 **************************************/

import { Permissions, webMethod } from '@wix/web-methods';
import { products } from '@wix/stores';

export const getProductVariants = webMethod(Permissions.Anyone, (_id, options) => {
  return products.queryProductVariants(_id, options);
});

/*************
 * Page code *
 *************/

import { getProductVariants } from 'backend/products.web';

let _id = "3fb6a3c8-988b-7895-04bd-5c59ae0b18ea"; // get product ID
let options = {
  choices: {
    "Size": "Large",
    "Color": "Red"
  }
};

getProductVariants(_id, options)
  .then((response) => {
    let firstVariant = response.variants[0];
    let firstPrice = firstVariant.variant.priceData.price;
    let numberOfReturnedVariants = response.variants.length;
  })
  .catch((error) => {
    console.error(error);
  });

/* Example of returned variants array:
 *
 * [
 *   {
 *     "_id": "00000000-0000-03e1-0005-957f699d0688",
 *     "choices": {
 *       "Size": "Large",
 *       "Color": "Red",
 *       "Pattern": "Paisley"
 *     },
 *     "variant": {
 *       "costAndProfitData": {
 *         "itemCost": 10
 *       },
 *       "priceData": {
 *         "price": 25
 *       },
 *       "sku": "217537123517253",
 *       "visible": true,
 *       "weight": 5
 *     }
 *   },
 *   {
 *     "_id": "00000000-0000-03e2-0005-957f699d0688",
 *     "choices": {
 *       "Size": "Large",
 *       "Color": "Red",
 *       "Pattern": "Houndstooth"
 *     },
 *     "variant": {
 *       "costAndProfitData": {
 *         "itemCost": 10
 *       },
 *       "priceData": {
 *         "price": 25
 *       },
 *       "sku": "217537123517253",
 *       "visible": true,
 *       "weight": 5
 *     }
 *   }
 * ]
 *
 */

```

### queryProductVariants (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 { products } from '@wix/stores';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

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


async function queryProductVariants(_id,options) {
  const response = await myWixClient.products.queryProductVariants(_id,options);
};
```

---