By default, requesting products for a category in Tweakwise automatically includes products assigned to all of its subcategories. While this behavior works well for general catalog browsing, you may sometimes want to display only products assigned directly to the selected category.

In this guide, you will learn how to turn off subcategory product inclusion by configuring and passing a direct category request parameter.

Process Overview

To restrict product results to direct category items only, complete the following three steps:

1. Expose [Categorie].CategoryKey as a product attribute.
2. Configure the attribute as a request parameter in Tweakwise Studio.
3. Pass the parameter in your API request string (tn_parameters).

Instruction & Implementation

Step 1: Create an attribute exposing categoryid or categorykey

To target exact category assignments, Tweakwise needs access to the direct category key without evaluating the category tree hierarchy.

Contact your CSM or support to create a new product attribute in Tweakwise that exposes CategoryKey or CategoryId as a product attribute.

Step 2: Configure the attribute as a request parameter

After the attribute is available, register it as a request parameter so it can be used dynamically.

1. Log in to Tweakwise.
2. Go to Catalog > Attributes.
3. Locate the new attribute.
4. Configure it as Request parameter, see Configure attribute as request parameter
5. Name the parameter, for example: direct-categoryid.
6. Save your changes and Publish your instance configuration.

Step 3: Pass the parameter in your frontend API request

To filter products directly by category ID, pass your configured parameter within the tn_parameters parameter in your API calls.

For complete endpoint specifications, see how to Use request parameters​

Example: filter on category 16051:

curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/navigation/{instancekey}?tn_cid=1000&tn_parameters=direct-cid%3D16051' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'

Notes & Important Considerations

• Publish Required: Parameter configuration changes will not apply in API responses until you publish your environment in Tweakwise Studio.
• Facet Totals & Pagination: Using direct-categoryid automatically recalibrates item counts, pagination, and available facet options to match only direct category items.
• Combining Parameters: You can combine direct-categoryid with standard category context (tn_cid) if your page requires category metadata (like banners or breadcrumbs) while suppressing subcategory products.

FAQ

1. Why am I still receiving subcategory products in the API response?
   Ensure you have published your environment in Tweakwise Studio after saving the request parameter. Additionally, verify that your feed populates [Categorie].CategoryKey with strictly the direct category ID and not an array of parent category IDs.
2. Can I use direct-categoryid alongside tn_cid?
   Yes. Passing tn_cid loads the relevant category metadata, rules, and breadcrumb structures, while direct-categoryid strictly controls product filtering in the lister result set.
3. What is the difference between a standard attribute filter and a request parameter
   Standard attribute filters add user-selectable facets to your lister page output. Request parameters perform identical product filtering on the engine side without creating frontend facet selections for visitors.