> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# List Variants

GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/variants

Returns a list of all variants in your catalog. Optional parameters can be passed in.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-variants/variants-batch/get-variants

## Authentication

- `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Products | modify | `store_v2_products` | | Products | read-only | `store_v2_products_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

## Request

### Path parameters

- `store_hash` (string, required) — Permanent ID of the BigCommerce store.

### Query parameters

- `id` (integer, optional) — Filter items by variant ID.
- `sku` (string, optional) — Filter items by variant SKU. To filter by product / base variant SKU, see [Get all products](/developer/api-reference/rest/admin/catalog/products/get-products).
- `upc` (string, optional) — Filter items by UPC.
- `include_fields` (list of string, optional) — Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- `exclude_fields` (list of string, optional) — Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
- `page` (integer, optional) — Specifies the page number in a limited (paginated) list of products.
- `limit` (integer, optional) — Controls the number of items per page in a limited (paginated) list of products.
- `product_id:in` (list of integer, optional) — A comma-separated list of IDs of products you want to request. For example, `?product_id:in=77,80,81`.

### Headers

- `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

## Response

### 200

OK

- `data` (list of CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItems, optional)
- `meta` (metaCollection_Full, optional) — Data about the response, including pagination and collection totals.

## Errors

### 404 Not Found Error

The resource was not found.

- `status` (integer, optional) — 404 HTTP status code.
- `title` (string, optional) — The error title describing the particular error.
- `type` (string, optional)
- `instance` (string, optional)

## Types

### CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItems

Common Variant properties.

- `cost_price` (double, optional) — The cost price of the variant. It is not affected by Price List prices. This value displays as null in the control panel when `cost_price` equals zero.
- `price` (double, optional) — This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.
- `sale_price` (double, optional) — This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.
- `retail_price` (double, optional) — This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.
- `weight` (double, optional) — This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
- `width` (double, optional) — Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default width (set in the Product resourceʼs `width` field) will be used as the base width.
- `height` (double, optional) — Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default height (set in the Product resourceʼs `height` field) will be used as the base height.
- `depth` (double, optional) — Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the productʼs default depth (set in the Product resourceʼs `depth` field) will be used as the base depth.
- `is_free_shipping` (boolean, optional) — Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero.
- `fixed_cost_shipping_price` (double, optional) — A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
- `purchasing_disabled` (boolean, optional) — If `true`, this variant will not be purchasable on the storefront.
- `purchasing_disabled_message` (string, optional) — If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.
- `upc` (string, optional, nullable) — The UPC code used in feeds for shopping comparison sites and external channel integrations.
- `inventory_level` (integer, optional) — Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/developer/docs/admin/catalog-and-inventory/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api).
- `inventory_warning_level` (integer, optional) — When the variant hits this inventory level, it is considered low stock.
- `bin_picking_number` (string, optional) — Identifies where in a warehouse the variant is located.
- `id` (integer, optional)
- `product_id` (integer, optional)
- `sku` (string, optional)
- `sku_id` (integer, optional) — Read-only reference to v2 APIʼs SKU ID. Null if it is a base variant.
- `option_values` (list of CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems, optional) — Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant.
- `calculated_price` (double, optional) — The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant.

### metaCollection_Full

Data about the response, including pagination and collection totals.

- `pagination` (pagination_Full, optional) — Data about the response, including pagination and collection totals.

### CatalogVariantsGetResponsesContentApplicationJsonSchemaDataItemsOptionValuesItems

Common Option Value Product properties.

- `option_display_name` (string, optional) — The name of the option.
- `label` (string, optional) — The label of the option value.
- `id` (integer, optional)
- `option_id` (integer, optional)

### pagination_Full

Data about the response, including pagination and collection totals.

- `total` (integer, optional) — Total number of items in the result set.
- `count` (integer, optional) — Total number of items in the collection response.
- `per_page` (integer, optional) — The amount of items returned in the collection per page, controlled by the limit parameter.
- `current_page` (integer, optional) — The page you are currently on within the collection.
- `total_pages` (integer, optional) — The total number of pages in the collection.
- `links` (PaginationFullLinks, optional) — Pagination links for the previous and next parts of the whole collection.

### PaginationFullLinks

Pagination links for the previous and next parts of the whole collection.

- `previous` (string, optional) — Link to the previous page returned in the response.
- `current` (string, optional) — Link to the current page returned in the response.
- `next` (string, optional) — Link to the next page returned in the response.

## Examples

**Response**

```json
{
  "data": [
    {
      "cost_price": 1.1,
      "price": 1.1,
      "sale_price": 1.1,
      "retail_price": 1.1,
      "weight": 1.1,
      "width": 1.1,
      "height": 1.1,
      "depth": 1.1,
      "is_free_shipping": true,
      "fixed_cost_shipping_price": 1.1,
      "purchasing_disabled": true,
      "purchasing_disabled_message": "string",
      "upc": "string",
      "inventory_level": 1,
      "inventory_warning_level": 1,
      "bin_picking_number": "string",
      "id": 1,
      "product_id": 1,
      "sku": "string",
      "sku_id": 1,
      "option_values": [
        {
          "option_display_name": "Color",
          "label": "Beige",
          "id": 1,
          "option_id": 1
        }
      ],
      "calculated_price": 1.1
    }
  ],
  "meta": {
    "pagination": {
      "total": 36,
      "count": 36,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "previous": "string",
        "current": "?page=1&limit=50",
        "next": "string"
      }
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants"

headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants';
const options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'X-Auth-Token': '<apiKey>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-Auth-Token", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["X-Auth-Token"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants', [
  'headers' => [
    'Accept' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Token": "<apiKey>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/catalog/variants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```