---
title: Product Listing API endpoint
description: Product Listing API endpoint reference.
slug: product-listing/api/v1
docKind: endpoint
hub: product-listing
tableOfContents: true
---

# Product listing API

Use the [Search API](/search/api/) to integrate product listing, but avoid
setting the query parameter (`q`). See the Search API documentation for complete usage details.

<div class="row mt-4 mb-4">
  <div class="col-md-4">
    <div class="card border-dark h-100 text-bg-light">
      <div class="card-header">Product listing API integration tutorial</div>
      <div class="card-body">
        <h5 class="card-title"><i class="bi bi-wrench-adjustable"></i> See the full guide to integrating Luigi's Box Product listing using the API</h5>
        <a href="/tutorials/plp.html" class="card-link">See the tutorial</a>
      </div>
    </div>
  </div>
</div>

# Product listing
<span class="badge text-bg-success">GET</span> `https://live.luigisbox.com/search`

## Required parameters

&nbsp; | &nbsp;
--------- | -----------
`f[] or f_must[]` | Filters to apply to fetch the listing products. This will typically be the category or, preferably, the special `category_path` attribute described below.
`tracker_id` | Identifier of your site within Luigi's Box. You can see this identifier in every URL in [the Luigi's Box app](https://app.luigisbox.com) once you are logged-in.
`plp` | E.g. `plp=category`. Name of the filter (from the `f[]` supplied filters) that serves as the unique identifier of the category. This is used to retrieve and apply any customizations (facets, pins) made for that category.

Note: Both `plp` and `f[]` (or `f_must[]`) are required but also must use the same key. See the example below with `plp=category&f[]=category:Kalimbas`.

<span class="badge text-bg-success">GET</span> `https://live.luigisbox.com/search?tracker_id=179075-204259&plp=category&f[]=category:Kalimbas&f[]=type:product&hit_fields=all_categories`

 <a href="https://live.luigisbox.com/search?tracker_id=179075-204259&plp=category&f[]=category:Kalimbas&f[]=type:product&hit_fields=all_categories" target="_blank">Try it live →</a>

# Best practices

## Filtering within full category hierarchy

When dealing with hierarchical categories, filtering by standalone category names might not be sufficient, and filtering by whole paths in the hierarchy may be necessary.

### Special filters

There are two special filters for product listing: `category_path` and `all_categories_path`.

You can use the special filter `category_path`, designed for filtering within a category hierarchy. Individual steps (categories within the hierarchy) should be separated by a double pipe `||`, e.g.: `f[]=category_path:Women||Footwear||Sandals`.
As with other filters, you can use multiple `category_path` filters together to create `OR` (by repeating the `f[]=...`) or `AND` (using `f_must[]`) combinations.

Alternatively the `all_categories_path` filter can be used, e.g.: `f[]=all_categories_path:Women||Footwear||Sandals`. It allows for filtering within full category hierarchy, while the `category_path` filter is applied only to primary category.

Special filter | Usage
--------- | -----------
`category_path` | filtering products with a matching <strong>primary</strong> category hierarchy within product's category hierarchies
`all_categories_path` | filtering products with a matching <strong>any</strong> category hierarchy within product's category hierarchies

To learn more about product category hierarchies visit docs on [product feeds](/indexing/feeds/).

For special filters to work, Luigi's Box needs to [pair](/plp/pairing/) one of them.

## Matching filter value with product data
Important: As with all other filters, we require the product value to perfectly match the filter value, including letter case.

This example presents a correct plp request, where the category attribute `title` is mapped to the product attribute `category` and the title `Musicians` matches the category name in the product data. 

<span class="badge text-bg-success">GET</span> `https://live.luigisbox.com/search?tracker_id=179075-204259&f[]=type:product&f[]=category:Musicians&plp=category`

<a href="https://live.luigisbox.com/search?tracker_id=179075-204259&f[]=type:product&f[]=category:Musicians&plp=category" target="_blank">Try it live →</a>

This example presents an invalid plp request for the same mapping as above because the letter case does not match (`musicians` instead of `Musicians`).

<span class="badge text-bg-success">GET</span> `https://live.luigisbox.com/search?tracker_id=179075-204259&f[]=type:product&f[]=category:musicians&plp=category`

<a href="https://live.luigisbox.com/search?tracker_id=179075-204259&f[]=type:product&f[]=category:musicians&plp=category" target="_blank">Try it live →</a>