Product Listing API

Product listing API

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

Product listing API integration tutorial

See the full guide to integrating Luigi's Box Product listing using the API

See the tutorial

Product listing

GET https://live.luigisbox.com/search

Required parameters

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.
f[]=type:...	The content type filter, e.g. f[]=type:product. Always required — see The type filter is required 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 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.

GET https://live.luigisbox.com/search?tracker_id=179075-204259&plp=category&f[]=category:Kalimbas&f[]=type:product&hit_fields=all_categories

Try it live →

The type filter is required

Every product listing request must include a content type filter, passed through f[]:

GET https://live.luigisbox.com/search?tracker_id=179075-204259&plp=category&f[]=category:Kalimbas&f[]=type:product

Your catalog holds more than products — categories and brands live in the same index — so a request without a type filter is not a product listing and its results are not reliable.

Use the type name from your own catalog: product, item, or whatever your indexing uses. If you are unsure which types your catalog contains, request the type facet and read the values back.

Limiting the response with hit_fields

The attribute names you list control each hit’s own attributes. If your tiles also show a product’s other variants, list nested too:

GET https://live.luigisbox.com/search?tracker_id=179075-204259&plp=category&f[]=category:Kalimbas&f[]=type:product&hit_fields=title,image_link,price_amount,nested

Listing attribute names alone returns "nested": []. See Implementing variant search.

Promoted pins in the response

Pinned products have pinned: true at the top level of the hit. When a pin is marked as promoted in the customization, the hit also contains promoted: true. If a pin_note was configured, display its value with the promoted product; it can provide a required explanation such as a sponsorship disclosure.

Configure the promoted flag and pin note in the Luigi’s Box App under Search → Search Results Customization when creating or editing a pin.

See the Search API response fields for the complete hit structure.

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 primary category hierarchy within product’s category hierarchies
all_categories_path	filtering products with a matching any category hierarchy within product’s category hierarchies

To learn more about product category hierarchies visit docs on product feeds.

For special filters to work, Luigi’s Box needs to pair 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.

GET https://live.luigisbox.com/search?tracker_id=179075-204259&f[]=type:product&f[]=category:Musicians&plp=category

Try it live →

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

GET https://live.luigisbox.com/search?tracker_id=179075-204259&f[]=type:product&f[]=category:musicians&plp=category

Try it live →