---
title: "Product Listing Endpoint V2"
method: POST
path: "/v2/product-listing"
tags: ["Product Listing", "V2"]
---

# Product Listing Endpoint V2

`POST /v2/product-listing`

## Request body

- ProductListingRequestV2
  - `cursor` string, nullable — Used for cursor-based pagination. Set it to the cursor from the last response. If not set, will return the first results.
  - `limit` integer, nullable — Used for cursor-based pagination. Maximum number of results per response.
  - `page` integer, nullable — Page-based pagination. We recommend using cursor-based pagination instead.
  - `hits_per_page` integer, nullable — Page-based pagination. We recommend using cursor-based pagination instead.
  - `market` string, required
  - `filters` SearchFilter[], nullable — List of filters to apply to the results.
    - `field` string, required
    - `op` 'eq' | 'neq' | 'in' | 'nin' | 'leq' | 'geq' | 'inrange', required
    - `data` union
      - 'true' | 'false'
      - number
      - integer
      - string
      - union[]
        - union
          - 'true' | 'false'
          - number
          - integer
          - string
      - array[]
        - string[]
    - `meta` union
      - RangeFilterMeta
        - `group_title` string, nullable
        - `group_expanded` boolean, nullable
        - `type` 'range'
        - `min` number, required
        - `max` number, required
        - `unit` string, nullable
        - `currency` string, nullable
      - ValuesFilterMeta
        - `group_title` string, nullable
        - `group_expanded` boolean, nullable
        - `type` 'radio' | 'checkbox' | 'checkbox-grid' | 'checkbox-color', required
        - `values` union[], required
          - union
            - 'true' | 'false'
            - number
            - integer
            - string
        - `counts` integer[], required
        - `names` string[], nullable, required
        - `swatches` string[], nullable
      - HierarchicalValuesFilterMeta
        - `group_title` string, nullable
        - `group_expanded` boolean, nullable
        - `type` 'checkbox-hierarchical'
        - `values` array[], required
          - string[]
        - `counts` integer[], required
        - `names` string[], nullable
    - `id` string, nullable
  - `sort` SortModelInput
    - `field` string, required
    - `order` 'asc' | 'desc', required
    - `meta` SortMeta
      - `title` string, required
      - `values` SortingOrder[]
      - `names` string[], nullable
  - `session_id` string, nullable — Session identifier
  - `metadata` object, nullable — Metadata that can be used to modify the behaviour of the search.
  - `tenant` string, required
  - `locale` string, nullable — The locale to use for the search. If not set, the default locale will be used.
  - `user_id` string, nullable — User identifier
  - `dsid` string, nullable — Populated for integrations performed by Depict.ai only. Depict.ai Session Id
  - `query_id` string, required — ID of the page to get products for. This is typically the slug, for example `hoodies-and-sweaters`.
  - `show_hidden_products` boolean — Disables rules to hide products.
  - `return_grouping_ids` boolean — Whether to return grouping IDs or not.
  - `type` 'category' | 'collection' | 'scollection'

## Response `200`

Successful Response

- ProductListingResponseV2
  - `displays` object[], required — The products to be shown on the product listing page.
  - `n_hits` integer, required — Total number of results for this query. Not necessarily exact.
  - `sorts` SortModelOutput[], nullable — Available methods for sorting the response. Any element from this list can be sent as `sort` in subsequent requests.
    - `field` string, required
    - `order` 'asc' | 'desc', required
    - `meta` SortMeta
      - `title` string, required
      - `values` SortingOrder[]
      - `names` string[], nullable
  - `filters` SearchFilter[], nullable — Available filters that can be used for filtering in the subsequent request.
    - `field` string, required
    - `op` 'eq' | 'neq' | 'in' | 'nin' | 'leq' | 'geq' | 'inrange', required
    - `data` union
      - 'true' | 'false'
      - number
      - integer
      - string
      - union[]
        - union
          - 'true' | 'false'
          - number
          - integer
          - string
      - array[]
        - string[]
    - `meta` union
      - RangeFilterMeta
        - `group_title` string, nullable
        - `group_expanded` boolean, nullable
        - `type` 'range'
        - `min` number, required
        - `max` number, required
        - `unit` string, nullable
        - `currency` string, nullable
      - ValuesFilterMeta
        - `group_title` string, nullable
        - `group_expanded` boolean, nullable
        - `type` 'radio' | 'checkbox' | 'checkbox-grid' | 'checkbox-color', required
        - `values` union[], required
          - union
            - 'true' | 'false'
            - number
            - integer
            - string
        - `counts` integer[], required
        - `names` string[], nullable, required
        - `swatches` string[], nullable
      - HierarchicalValuesFilterMeta
        - `group_title` string, nullable
        - `group_expanded` boolean, nullable
        - `type` 'checkbox-hierarchical'
        - `values` array[], required
          - string[]
        - `counts` integer[], required
        - `names` string[], nullable
    - `id` string, nullable
  - `product_listing_request_id` string, required
  - `cursor` string, nullable — Cursor that can be used in the next request to get subsequent results when using cursor based pagination. If this is not set, there are no more results.
  - `page` integer, nullable — Deprecated, do not use.
  - `grouping_ids` object, nullable — Maps product ID to grouping ID. Only returned if `return_grouping_ids` is True.
  - `breadcrumb` BaseCategoryDisplay[], nullable — Breadcrumb for the current page. Ordered from less to more specific, where the last element is the current page.
    - `category_id` string, required — Unique identifier of the category.
    - `title` string, required — The title of the category
    - `page_url` string, nullable — The full URL to the category page
    - `query_id` string, nullable — Optionally a unique query ID for the category
    - `uri` string, nullable — Optionally a unique URI for the category, for example men/shoes
    - `category_type` 'TAG' | 'CATEGORY' | 'TENANT_CATEGORY' | 'TENANT_SECONDARY_CATEGORY' | 'CAMPAIGN' | 'BRAND'
  - `quick_links` BaseCategoryDisplay[], nullable — List of pages that can be used as quick links. Will return child pages if they exist, otherwise sibling pages.
    - `category_id` string, required — Unique identifier of the category.
    - `title` string, required — The title of the category
    - `page_url` string, nullable — The full URL to the category page
    - `query_id` string, nullable — Optionally a unique query ID for the category
    - `uri` string, nullable — Optionally a unique URI for the category, for example men/shoes
    - `category_type` 'TAG' | 'CATEGORY' | 'TENANT_CATEGORY' | 'TENANT_SECONDARY_CATEGORY' | 'CAMPAIGN' | 'BRAND'
  - `metadata` PLPMetadata
    - `title` string, required
    - `description` string, nullable
    - `replace_meta_tags` boolean — Whether to replace the page meta tags, e.g., title and description, with the ones from the collection.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/depict/apis/depict-api.md) · [All operations](https://skmtc.net/depict/apis/depict-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/depict/depict-api/revisions/aad86b1030c7/schema)