---
title: "Display a list of variants"
method: GET
path: "/v1/variants"
tags: ["variants"]
---

# Display a list of variants

`GET /v1/variants`

Get multiple variants, either by specifying search criteria/filters or variant IDs.

There are two basic ways to use this endpoint: You can either search for variants by specifying search/filter parameters or directly fetch known variants by their [variant IDs](../../../en/glossary#variant-id).

***

__Searching for variants__

The various `filter` parameters can be used to restrict the list of variants included in the response (see available parameters below).

You can also use the `/v1/filters` endpoint to determine which filters are available in the current context. This way, you can, for example, enable users to narrow down general variant lists to very specific results by incrementally adding more and more filter parameters.

The `minProductId`, `includeSellableForFree`, and `includeSoldOut` parameters can further restrict or expand the search results (see below).

***

__Fetching variants by variant ID__

To fetch a list of known variants, simply specify them by variant ID using the `ids` parameter, for example, `/v1/variants?ids=1,2,3`.

If you specify the `ids` parameter, all other search/filter parameters will be ignored.

***

__Selecting included variant data__

By default, only basic variant data is included in the response. Use the `with` parameters (see below) to include more variant data.

To see all available variant data, for example, for debugging, you might use unrestricted `with` parameters: `?with=attributes,advancedAttributes`.

Beware of using unrestricted `with` parameters in production applications. It will result in slow performance, as download sizes for full variant data lists can be quite big. Including only exactly what is needed will be best for performance when downloading and parsing the result.

A typical request for a variant list optimized for maximum performance is, for example, `?with=attributes:key(ean|shopSize),advancedAttributes:key(modelHeight)`.

## Query parameters

- `ids` integer[]
- `campaignKey` string
- `includeSellableForFree` boolean
- `includeSoldOut` boolean
- `minProductId` integer
- `sortingKey` string
- `filters[attributeId]` integer
- `filters[attributeKey]` string
- `orFiltersOperator` string
- `filters[category]` integer[]
- `filters[ean]` string[]
- `filters[isnew]` boolean
- `filters[maxPrice]` integer
- `filters[maxReduction]` integer
- `filters[minPrice]` integer
- `filters[minReduction]` integer
- `filters[referenceKey]` string
- `filters[sale]` boolean
- `filters[styleKey]` string[]
- `filters[term]` string[]
- `filters[merchantId]` integer
- `sort` 'new' | 'price' | 'reduction'
- `sortDir` 'asc' | 'desc'
- `hideSoldOutVariants` boolean
- `greaterThan` integer
- `with` string[]
- `page` integer
- `perPage` integer

## Response `200`

successful operation

- object
  - `entities` Variant[]
    - `id` integer
    - `advancedAttributes` object
    - `appliedPricePromotionKey` string
    - `attributes` object
    - `price` Price
      - `appliedReductions` AppliedReduction[]
        - `amount` object
          - `absoluteWithTax` integer
          - `relative` number
        - `category` string
        - `type` string
      - `currencyCode` string — The currency of the price.
      - `reference` object
        - `size` integer — Size of the reference (100m, 100ml), but in this field fill in only the value without the unit of measurement.
        - `unit` string — The size of reference unit (KG, ml, L, etc.) without the value
        - `withoutTax` integer — Reference price excluding the taxes.
        - `withTax` integer — Item price including taxes. The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provided on the request).
      - `tax` object
        - `vat` object
          - `amount` number
          - `rate` number
      - `withoutTax` integer
      - `withTax` integer
      - `recommendedRetailPrice` integer
    - `productId` integer
    - `referenceKey` string
    - `firstLiveAt` string — Identifies the first time the variant went live
    - `stock` Stock
      - `deliveryForecast` object
        - `deliverable` string
        - `subsequentDelivery` string
      - `isSellableWithoutStock` boolean
      - `quantity` integer
      - `warehouseId` integer, nullable
      - `supplierId` integer
    - `customData` object
    - `createdAt` string — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
    - `updatedAt` string — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
  - `pagination` Pagination
    - `current` integer
    - `first` integer
    - `last` integer
    - `next` integer
    - `page` integer
    - `perPage` integer
    - `prev` integer
    - `total` integer

## Other responses

- `401` — authentication failed

## Changes

- **2023-08-06** `302b7c443b51` — 42 breaking, 4 warning, 33 info
  - the response property `entities/items/attributes/additionalProperties/id` became nullable for the status `200`
  - the response property `entities/items/attributes/additionalProperties/type` became nullable for the status `200`
  - the response property `entities/items/attributes/additionalProperties/values/items/id` became nullable for the status `200`
  - the response property `entities/items/attributes/additionalProperties/values/items/label` became nullable for the status `200`
  - …75 more

[Change history](https://skmtc.dev/scayle/apis/storefront-api-documentation/changes/v1/variants/get.md)

---

[API](https://skmtc.dev/scayle/apis/storefront-api-documentation.md) · [All operations](https://skmtc.dev/scayle/apis/storefront-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scayle/storefront-api-documentation/revisions/beabe2149947/schema)