---
title: "List variants"
method: GET
path: "/v1/variants"
tags: ["variants"]
---

# List variants

`GET /v1/variants`

Get multiple variants by specifying variant IDs.

__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`.

***

__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,lowestPriorPrice`.

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),lowestPriorPrice`.

## Query parameters

- `shopId` string, required
- `ids` integer[], required
- `campaignKey` string
- `pricePromotionKey` string
- `with` string[]

## Response `200`

successful operation

- object
  - `entities` Variant[]
    - `id` integer, required
    - `advancedAttributes` object
    - `appliedPricePromotionKey` string
    - `attributes` object
    - `lowestPriorPrice` LowestPriorPrice — Information about the lowest price in the past 30 days.
      - `withTax` integer, nullable, required — The lowest price including tax.
      - `relativeDifferenceToPrice` number, float, nullable, required — The relative difference from the lowest prior price to the current price. If the value is positive, it means that the current price is higher than the lowest prior price. If the value is negative, it means that the current price is lower than the lowest prior price.
    - `price` Price, required
      - `appliedReductions` AppliedReduction[], required
        - `amount` AppliedReductionAmount, required
          - `absoluteWithTax` integer
          - `relative` number
        - `category` 'sale' | 'campaign' | 'promotion', required
        - `type` string, required
      - `currencyCode` string, required — 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` Tax, required
        - `vat` Vat
          - `amount` number
          - `rate` number
      - `withoutTax` integer, required
      - `withTax` integer, required
      - `recommendedRetailPrice` integer, required
    - `productId` integer, required
    - `referenceKey` string, required
    - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
    - `stock` Stock, required
      - `supplierId` integer, required
      - `warehouseId` integer, nullable, required
      - `quantity` integer, required
      - `isSellableWithoutStock` boolean, required
      - `expectedAvailabilityAt` string, nullable, required
    - `customData` object, required
    - `merchant` Merchant
      - `id` integer, required
      - `key` string, required
      - `name` string, required
      - `legal` object
        - `legaName` string
        - `parentCompanyLegalName` string
        - `streetWithNumber` string
        - `zip` string
        - `city` string
        - `country` string
        - `telephone` string
        - `email` string
        - `registryCourtCity` string
        - `registerNumber` string
        - `parentCompanyRegistryCourtCity` string
        - `parentCompanyRegisterNumber` string
        - `managingDirectors` string
        - `representative` string
        - `shippingMerchantName` string
        - `registryCourtType` string
        - `parentCompanyRegistryCourtType` string
        - `vatId` string
    - `createdAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
    - `updatedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
  - `pagination` Pagination
    - `current` integer, required
    - `first` integer, required
    - `last` integer, required
    - `next` integer, required
    - `page` integer, required
    - `perPage` integer, required
    - `prev` integer, required
    - `total` integer, required

## Other responses

- `400` — Required query parameter missing / invalid
- `401` — Authentication information is missing or invalid

## Changes

> 3 revisions in range; 1 could not be searched.

- **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/8cfa924ae703/schema)