Using Stopwords

Some words carry almost no meaning for search. When a shopper types the red dress or a pair of running shoes, words like the, a, of, and is add noise without helping find the right product. Stopwords are words you tell the search engine to ignore when it processes a query, so matching and ranking focus on the words that matter.

Stopwords are organized into stopword sets — a list of words for a single language. At search time, the service automatically selects the right stopword set based on the language of the request.

No reindexing required

Stopwords are applied when a search is executed, not when products are indexed, so you never need to reindex your catalog. Changes to a stopword set are synchronized to the search engine in the background and take effect within a few seconds.

How Stopwords Work

When a search runs, every word in the query is checked against the stopword set that applies to the request's language. Matching words are removed before the query is matched against your products. The effect depends on what is left:

• Multi-word query: the stopwords are dropped and the remaining words are searched. A query for the titanium bolt, with the as a stopword, searches for titanium bolt.
• Query made entirely of stopwords: nothing is left to match, so the search returns no results. A search for the (when the is a stopword) returns zero products.

Stopword matching is case-insensitive and works on whole words only.

Stopwords are not applied to autocomplete requests

Autocomplete (search-as-you-type) queries keep every word, because partial input like the dr still needs the leading word to suggest results. Stopwords apply only to full search queries.

Quick Reference

Stopword sets are managed through the following endpoints, relative to your API base URL (for example https://useast.api.elasticpath.com/v2):

Operation	Method & Path
Create a stopword set	POST /pcm/catalogs/search/stopword-sets
List stopword sets	GET /pcm/catalogs/search/stopword-sets
Get a stopword set	GET /pcm/catalogs/search/stopword-sets/{stopword_set_id}
Update a stopword set	PUT /pcm/catalogs/search/stopword-sets/{stopword_set_id}
Delete a stopword set	DELETE /pcm/catalogs/search/stopword-sets/{stopword_set_id}

A stopword set has the following attributes:

Attribute	Type	Required	Description
locale	string	No	The ISO 639-1 language code (for example en, fr, de) the set applies to. Omit or pass null for the default set. At most one set per locale is allowed. Only one default set is allowed.
stopwords	array of string	Yes	The words to ignore at query time. Must contain at least one word.

Creating a Stopword Set

Create a set by listing the words to ignore for a language:

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search/stopword-sets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_stopword_set",
      "attributes": {
        "locale": "en",
        "stopwords": ["the", "a", "an", "is", "of"]
      }
    }
  }'

The response echoes the set with a generated id and a meta block describing its synchronization state:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "catalog_search_stopword_set",
    "attributes": {
      "locale": "en",
      "stopwords": ["the", "a", "an", "is", "of"]
    },
    "meta": {
      "owner": "store",
      "created_at": "2026-03-05T12:00:00Z",
      "updated_at": "2026-03-05T12:00:00Z",
      "sync_status": "pending_sync"
    }
  }
}

A new set starts with sync_status: pending_sync and becomes usable once it has synced. See Synchronization Status.

A new set takes a few minutes to apply

Catalog Search caches which stopword set applies to each language. A newly created set can therefore take up to 5 minutes before it is used in searches, even after it reaches synced. Updates to an existing set are not subject to this delay — see Updating a Stopword Set.

Default and Locale-Specific Sets

Each stopword set applies to one language, identified by its locale. You can also create one set with no locale, used as the default set when no other set matches the request language. It is recommended to always have a default set so that stopwords are removed from the search query no matter the user's preferred language.

• Locale-specific set: set locale to an ISO 639-1 code such as en, fr, or de. It applies only to searches in that language.
• Default set: omit locale (or pass null). It applies to any search whose language has no locale-specific set of its own.

# A French stopword set
curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search/stopword-sets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_stopword_set",
      "attributes": {
        "locale": "fr",
        "stopwords": ["le", "la", "les", "un", "une", "de"]
      }
    }
  }'

Only one set is allowed per locale (and one default). Creating a second set for a locale that already has one returns a 409 Conflict.

How a Stopword Set Is Selected at Search Time

The service picks the set automatically for each search, based on:

1. The language of the request. Catalog Search reads the request's Accept-Language header (or X-Moltin-Language) and looks for a stopword set whose locale matches. The first matching language in the header wins.
2. A fallback to the default set. If no set matches the request language, the default (no-locale) set is used.
3. Nothing, if neither exists. If there is no matching set and no default set, no stopwords are removed.

For example, with an English set (en) and a default set configured:

Request language	Set applied
en-US	The en set
fr-FR (no fr set)	The default set
none / no matching set	The default set (or none, if no default set)

Organization and Store Scope

Stopword sets are scoped to the tenant that creates them:

• Organization-scoped sets apply across all stores in the organization.
• Store-scoped sets apply only to that store and take precedence over an organization set for the same locale.

This lets an organization define shared stopwords while individual stores override them where needed. A store cannot modify or delete an organization-scoped set and vice versa.

Updating a Stopword Set

Update replaces the entire stopwords list, so include every word you want to keep. The locale cannot be changed after creation.

curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search/stopword-sets/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "catalog_search_stopword_set",
      "attributes": {
        "stopwords": ["the", "a", "an", "is", "of", "was"]
      }
    }
  }'

After an update, the set returns to pending_sync state until the change synchronizes. See Synchronization Status. While the update is still pending, searches continue to use the set's previous stopwords, then switch to the new list as soon as the change synchronizes. The set should generally sync within a few seconds after updating.

Deleting a Stopword Set

curl -X DELETE https://useast.api.elasticpath.com/v2/pcm/catalogs/search/stopword-sets/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Deletion is processed in the background: the set is first marked for deletion, then removed from the search engine. Because Catalog Search caches which stopword set apply to each language, a deleted set can continue to be applied to searches for up to 5 minutes after deletion. For the same reason, you cannot immediately create a new set for the same locale — wait a few minutes for the deletion to finish.

Synchronization Status

Changes to stopword sets are propagated to the search engine asynchronously. The meta.sync_status field reflects where a set is in that process:

sync_status	Meaning
pending_sync	Created or updated, not yet propagated to the search engine
synced	Live and applied to matching searches; meta.last_synced_at is set
sync_failed	Synchronization did not complete

A set only affects search once it reaches synced. A newly created set that has never synced is ignored at search time.

Validation and Errors

Status	When
400	The stopwords array is empty, or locale is not a valid ISO 639-1 code
400	The id in an update body does not match the id in the path
403	A store tries to update or delete an organization-scoped set
404	The stopword set does not exist (or is being deleted)
409	A set already exists for the locale

Related Resources

• Setting Up Catalog Search
• Using Synonyms
• Handling Typos
• Catalog Search API Reference