---
updatedAt: 2026-06-09T11:33:45.000Z
agentTools:
  projectIndex: https://docs.tweakwise.com/llms.txt
---

# Use request parameters

In Tweakwise, you’re able to pass parameters, sometimes refered to as "hidden filters", to almost every request that returns products (see [Navigation request](https://docs.tweakwise.com/reference/navigation-3)). These parameters are used to pre-filter the result set without the need to configure a facet in your filter template.

This functionality is useful for pages where you want to show a default subset of products:

* **Include**: brand pages, specific categories.
* **Exclude**: show regular catalog except specificly marked products

# Prerequisite

If you want to use a parameter as a request parameter, you’ll need to enable this in the attribute settings in the Tweakwise App. Don’t forget to publish your instance after changing this setting.

<Image src="https://files.readme.io/2ad576c3775332caf4272b69b7128967fd1046128b23d65d9a1ac59c6edb90d8-image.png" align="center" />

# Include

Use `tn_parameters` to only include products that match with the given attribute value(s).

**Example**: use this if you can't exclude items in your Tweakwise feed, e.g. only items that are *in-stock*:

## Search

Use `tn_parameters` in `/navigation-search` to include products matching selection criteria.

**Example**: select only items that are in-stock:

<Terminal>
  {`/navigation-search/\{instancekey}/?tn_parameters=in-stock%3Dtrue`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/navigation-search/{instancekey}?tn_cid=1000&tn_parameters=in-stock%3Dtrue' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

**Example**: filter by brand 'Coca Cola' or 'Pepsi':

<Terminal>
  {`/navigation-search/\{instancekey}/?tn_parameters=brand%3DCoca%20Cola%26brand%3DPepsi`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/navigation-search/{instancekey}?tn_cid=1000&tn_parameters=brand%3DCoca%20Cola%26brand%3DPepsi' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

## Merchandising

Use `tn_parameters` in `/navigation` to include products matching selection criteria.

**Example**: select only items that are in-stock:

<Terminal>
  {`/navigation/{instancekey}/?tn_parameters=in-stock%3Dtrue`}
</Terminal>

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

**Example**: filter by brand 'Coca Cola' or 'Pepsi':

<Terminal>
  {`/navigation/{instancekey}/?tn_parameters=brand%3DCoca%20Cola%26brand%3DPepsi`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/navigation/{instancekey}?tn_cid=1000&tn_parameters=brand%3DCoca%20Cola%26brand%3DPepsi' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

## Suggestions

Use `tn_parameters` in `/suggestions` and `/suggestions/products` to include products matching selection criteria.

**Example**: select only items that are in-stock:

<Terminal>
  {`/suggestions/\{instancekey}/?tn_parameters=in-stock%3Dtrue`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/suggestions/{instancekey}?tn_q=hoodie&tn_cid=1000&tn_parameters=in-stock%3Dtrue' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

<br />

# Exclude

Use `tn_parameters_except` to exclude items with the given attribute value(s).

**Example**: use this if you can't exclude items in your Tweakwise feed, e.g. for displaying a specific catalog for a user group.

## Search

Use `tn_parameters_except` in `/navigation-search` to exclude products matching selection criteria.

**Example**: select all items that are not in segment 'basic':

<Terminal>
  {`/navigation-search/\{instancekey}/?tn_parameters_except=segment%3Dbasic`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/navigation-search/{instancekey}?tn_cid=1000&tn_parameters_except=segment%3Dbasic' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

## Merchandising

Use `tn_parameters_except` in `/navigation` to exclude products matching selection criteria.

**Example**: select all items that are not in segment 'basic':

<Terminal>
  {`/navigation/\{instancekey}/?tn_parameters_except=segment%3Dbasic`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/navigation/{instancekey}?tn_cid=1000&tn_parameters_except=segment%3Dbasic' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

## Suggestions

Use `tn_parameters_except` in `/suggestions` and `/suggestions/products` to exclude products matching selection criteria.

**Example**: select all items that are not in segment 'basic':

<Terminal>
  {`/suggestions/\{instancekey}/?tn_parameters_except=segment%3Dbasic`}
</Terminal>

```curl Example
curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/suggestions/{instancekey}?tn_q=hoodie&tn_cid=1000&tn_parameters_except=segment%3Dbasic' \
     --header 'TWN-Source: Tweakwise API docs' \
     --header 'accept: application/json'
```

<br />

# Encoding

Building the tn\_parameters value should be done in this way:

* **URL-encode individual values:** A++ becomes A%2B%2B
* **Construct the inner filter string:** Combine the key and encoded value: energy\_label=A%2B%2B
* **URL-encode that entire string:** Because this string is being passed as a value for the tn\_filters parameter, the whole thing from step 2 must be encoded again: energy\_label%3DA%252B%252B
* **Append to the main URL:** \&tn\_filters=energy\_label%3DA%252B%252B

<br />

# Good to know

* Use the attribute URL name as the parameter names.
* Reach out to our support team, and we'll help mark the attributes you'd like to use as hidden filters in your instance.
* When using multiple attributes, format it like a regular URL querystring and URL encode the entire value:
  ```javascript Example
  'in-stock%3Dtrue%26vip%3Dtrue';
  ```

<br />