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

# List products

`GET /v1/products`

Requesting this API endpoint is the main way to retrieve your product data to display in any context. A product is basically any individual item in the shop.

 There are basically two ways to use this endpoint:
 * Search for products by specifying search/filter parameters

 * Directly fetch known products by their product IDs

 ***

 __Searching for products__

 The various `filter` parameters can be used to restrict the list of products 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 product 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 products by product ID__

 To fetch a list of known products, simply specify them by product ID using the `ids` parameter, for example, `/v1/products?ids=1,2,3`. This offers a notable performance advantage since it eliminates the need for a search step.

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

 ***

 __Selecting included product data__

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

 To see all available product data, for example, for debugging, you might use unrestricted `with` parameters: `?with=attributes,advancedAttributes,categories,images.attributes,priceRange,reductionRange,siblings,variants.attributes,variants.advancedAttributes`.

 Beware of using these unrestricted `with` parameters in production applications. It will result in slow performance, as download sizes for full product 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 product list optimized for maximum performance is, for example, `?with=attributes:key(brand|color),advancedAttributes:key(description),variants.attributes:key(vendorSize),images,priceRange,reductionRange`.

 ***

 __Sorting__

 You can order the results using different sorting strategies, based on the provided `sort`, `sortingKey`, and `sortDir` parameters.

 * __Default sorting__: If no sorting parameter is specified, the products will be sorted by product ID. To specify the order, use the `sortDir` parameter (default `desc`, highest product ID first).

 * __Price sorting__: `sort=price` will sort the results by price. To specify the order, use the `sortDir` parameter (default `desc`, highest price first).

 * __Reduction sorting__: `sort=reduction` will sort the results by price reduction. This sorting is based on the available `appliedReductions` for each product's variants. When a `campaignKey` is also provided, the sorting will also consider the campaign reduction. To specify the order, use the `sortDir` parameter (default `desc`, highest reduction first).

 * __Date sorting__: `sort=new` will order the products by `firstLiveAt` field. If `firstLiveAt` is not set the products will be ordered by creation date. To specify the order, use the `sortDir` parameter (default `desc`, most recent date first).

 * __Key sorting__: `sortingKey` will order the results based on your custom sorting keys, for example, `sortingKey=wcc-default`. If the `sortingKey` parameter has been provided, the `sort` parameter will be ignored.

## Query parameters

- `ids` integer[]
- `campaignKey` string
- `includeSellableForFree` boolean
- `includeSoldOut` boolean
- `referenceKey` string
- `pricePromotionKey` string
- `sort` 'new' | 'price' | 'reduction'
- `sortDir` 'asc' | 'desc'
- `sortingKey` string
- `filters[attributeKey]` string[]
- `filters:not[attributeKey]` integer[]
- `filters:not[id]` integer[]
- `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[variants.referenceKey]` string[]
- `filters[variants.color]` integer[]
- `filters[sale]` boolean
- `filters[masterKey]` string[]
- `filters[term]` string
- `filters[minFirstLiveAt]` string
- `filters[merchantId]` integer
- `filters[hasCampaignReduction]` boolean
- `with` string[]
- `minProductId` integer
- `disableFuzziness` boolean
- `page` integer
- `perPage` integer
- `limit` integer
- `offset` integer

## Response `200`

successful operation

- object
  - `entities` Product[]
    - `id` integer, required
    - `advancedAttributes` object
    - `attributes` object
    - `baseCategories` BaseCategory[]
      - `categoryId` integer, required — Unique identifier of the category
      - `categoryName` string, required — Name of the category
      - `categoryParentId` integer, required — Parent ID of the category
      - `categoryPath` string, required — Category path as text
    - `categories` array[]
      - ProductCategory[]
        - `categoryId` integer
        - `categoryHidden` boolean
        - `categoryName` string
        - `categoryProperties` object
          - `is_inheritable` integer
          - `name` string
          - `value` string
        - `shopLevelCustomData` object
          - `appCatName` object
          - `appCatLocalizedConfig` object
        - `countryLevelCustomData` object
          - `appCatCountryName` string
          - `appCatCountryScore` number
          - `appCatCountryBubbleUp` boolean
          - `appCatCountrySampleName` string
          - `appCatCountrySampleConfig` object
          - `appCatCountryLocalizedConfig` object
        - `categoryUrl` string
        - `categorySlug` string
    - `definingAttributes` DefiningAttribute
      - `id` integer, required
      - `label` string, required
    - `images` Image[], required
      - `attributes` object
      - `hash` string
    - `customData` ResponseCustomData, required
    - `isActive` boolean, required — Identifies whether a product is active or not
    - `isNew` boolean, required — Identifies whether a product is new or not
    - `isSoldOut` boolean, required — Identifies if a product is still available to sell
    - `masterKey` string, required — Identifies the master product which this product belongs
    - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
    - `priceRange` PriceRange
      - `max` 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
      - `min` 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
    - `reductionRange` ReductionRange
      - `max` Price
        - `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
      - `min` Price
        - `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
    - `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.
    - `referenceKey` string, required
    - `searchCategoryIds` integer[]
    - `siblings` Product[] — list of Products
    - `variants` 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
    - `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
    - `indexedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00
  - `pagination` union
    - 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
    - OffsetPagination
      - `total` integer, required

## Other responses

- `400` — required query parameter missing / invalid
- `401` — authentication failed

## Changes

- **2026-07-17** `8cfa924ae703` — 11 breaking, 37 warning, 109 info
  - for the `query` request parameter `filters:not[attributeKey]`, the type/format was changed from `string`/`` to `array`/``
  - for the `query` request parameter `filters[attributeKey]`, the type/format was changed from `string`/`` to `array`/``
  - for the `query` request parameter `orFiltersOperator`, the type/format was changed from `string`/`` to `array`/``
  - the response property `entities/items/attributes/additionalProperties/values` became nullable for the status `200`
  - …153 more
- **2023-08-06** `302b7c443b51` — 123 breaking, 7 warning, 40 info
  - for the `query` request parameter `filters[minFirstLiveAt]`, the type/format was changed from `string`/`` to `array`/``
  - for the `query` request parameter `filters[term]`, the type/format was changed from `string`/`` to `array`/``
  - 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`
  - …166 more

[Change history](https://skmtc.dev/scayle/apis/storefront-api-documentation/changes/v1/products/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)