Overview

Every site has a baseline set of fields that Search matches queries against, configured under Searchable Fields (searchable.fields). This works well for most queries, but some shoppers search using attributes that only make sense for a subset of products, such as a part number, an interchange code, or a legacy SKU.

Additional Searchable Fields lets you add extra fields to a specific search request using the additional.searchable.fields parameter. Search matches the query against your baseline fields plus the fields you add, without changing what every other query matches against.

Common Use Cases

This applies anywhere a query needs to match against a field that only some requests should check:

• Customer- or account-scoped identifiers: Part numbers, interchange codes, distributor codes, or vendor SKUs that only mean something to one buyer or business account. Common in auto parts and industrial catalogs, but equally applicable to grocery/foodservice distribution (distributor codes), fashion and furniture wholesale (vendor style/collection codes), and any B2B catalog where different accounts reference the same product differently.
• Search-experience-scoped fields: An internal tool, a trade/wholesale portal, or a seller-facing dashboard that needs to match against fields (warehouse SKU, seller SKU, batch/lot number) that shouldn't be searchable from your main storefront.
• Legacy identifiers during a transition: Old SKUs or codes that need to stay searchable temporarily after a catalog migration, rebrand, or renumbering, without living in your default configuration permanently.

Example: A shopper on an auto parts site searches for WT304-19B. The site's baseline fields already cover title, SKU, and enriched text, but this particular value only exists in a custom indexed field, PartNumber_22132301_unx_ts.

Adding the field to the request tells Search to also match against it:

additional.searchable.fields=PartNumber_22132301_unx_ts^1

Search combines this with the baseline fields for that request only. You can confirm exactly what got matched by turning on debug mode (see Verify the merged fields below).

Request Parameter

Adding more than one field

Repeat the parameter, or pass a comma-separated list in one parameter:

additional.searchable.fields=field1^2,field2^3

additional.searchable.fields=field1^2&additional.searchable.fields=field2^3

Sample Request

https://search.unbxd.io/<API-KEY>/<SITE-KEY>/search?q=WT304-19B&version=V2&additional.searchable.fields=PartNumber_22132301_unx_ts^1&promotion=false

Verify the Merged Fields

Add brewer.debug=true to the request and check brewerDebug.params.qf (or brewerDebug.qf) in the response. It shows the complete field list Search matched against for that request, baseline fields plus anything you added.

https://search.unbxd.io/<API-KEY>/<SITE-KEY>/search?q=WT304-19B&version=V2&additional.searchable.fields=PartNumber_22132301_unx_ts^1&promotion=false&brewer.debug=true

FAQ

Can I change my site's default search configuration to use this?
No. Your baseline searchable.fields in Console stay as they are. additional.searchable.fields only affects the request it's passed on.

What happens if I don't include a boost value?
The field is not applied. Boost is a required part of the format (fieldName^boost) and there's no default.

Can I add more than one field in a single request?
Yes. Pass the parameter more than once, or list the fields comma-separated in a single parameter.

What if my request already sends a qf parameter?
The explicit qf wins, and additional.searchable.fields is skipped for that request.

How do I confirm which fields were actually used?
Add brewer.debug=true and check brewerDebug.params.qf in the response.