Skip to main content

Using Search Overrides

A search override changes how search, filters, and boosts apply to one product, without publishing a release. It sets the field values those rules match, such as a name, a shopper attribute, or tags. The Product Experience Manager (PXM) product is unchanged. Hit attributes stay that product. Public values are returned in meta.search_overrides so a shopper site can see which fields differ from the PXM product and apply them.

Search catches up after the write

The write returns when the override is saved. Search uses it shortly afterward, so a read can show a value search does not use yet.

Sample use cases​

A catalog release is published from your Product Experience Manager (PXM) products. A PIM import updates those products, and the next publish replaces a name, attribute, or stock flag that was on the previous release. A search override is an opt-in capability that preserves search-specific values: one set of fields per product, for the organization or the store. Search keeps those values through later publishes and re-indexes until you clear them. The catalog must allow search overrides first. The default is off.

Reorder a product by updating a field a boost already uses​

Search order comes from filters and boosts on the search profile. The override has no ranking control of its own. Set the field the rule already matches.

A boost on extensions.products(Details).is_featured:=true moves this product up when the override sets that field to true. A boost on extensions.products(Details).stock_status:=out_of_stock with a negative weight moves it down when the override sets out_of_stock.

For a promotion that should fade, lower or clear that field as the promotion winds down. To stop the override on later releases, set applies_to_releases_created_until. A release requested after that time uses the PXM product value.

Leave the field public when the shopper site should see the difference in meta.search_overrides and apply it. Set private to true when search should use the value and the shopper site should not be told.

Remember in-stock and out-of-stock between publishes​

An integration that resolves stock at publish time asks inventory for every product in the release. At 10,000 or 100,000 products, that read dominates the publish. When a stock level changes, set the stock field on the search override instead, and point the search profile boost at that field.

Leave persist_across_releases omitted, or send true. The stock value is still in search after the next publish, so publish does not read inventory again to restore it.

Send persist_across_releases: false when the PXM product is the stock source of truth. A release created after the write uses the PXM product value for that field.

Clear the stock field to remove it. The next indexing of the release uses the PXM product value.

Allow search overrides​

Search uses an override only on a release that allows search overrides.

  1. Turn on Allow search overrides for the catalog. In Commerce Manager the switch is on the catalog while search is enabled. See Enabling Catalog Search for a Catalog. With the Catalogs API, set allow_search_overrides to true on the catalog. It defaults to false.
  2. Publish a release after the setting is on. The release stores allow_search_overrides under meta when the release is created. A release that omits it does not allow search overrides. Changing the catalog later does not change a release that already exists. Two releases of the same catalog can disagree.
  3. A search index built before this value was stored does not use overrides. Re-index that release. After the search index has the value, later overrides apply without another publish.

A release that does not allow search overrides keeps the PXM product values in search. The override is still saved, and releases that do allow them use it.

Where each value lives​

PlaceWhat it shows
Saved search overrideThe values you set, including private fields, and the override field owner of each field
Search, filter, and sortThe override value, once search has caught up
Hit attributesThe PXM product
Hit meta.search_overridesPublic values that differ from the PXM product, for the shopper site to apply. Private values are left out. An empty map is omitted

Autocomplete leaves meta.search_overrides out. In one multi-search response, a search sub-search can include the map while an autocomplete sub-search does not.

Quick Reference​

Search overrides use the same authentication and store or organization as other Catalog Search admin calls. Paths are relative to your API base URL (for example https://useast.api.elasticpath.com/v2).

OperationMethod and path
Get the search override for one productGET /pcm/catalogs/search/overrides/{product_id}
List search overridesGET /pcm/catalogs/search/overrides
Create or update one productPUT /pcm/catalogs/search/overrides/{product_id}
Create or update up to 100 productsPOST /pcm/catalogs/search/overrides/bulk
Delete the search overrideDELETE /pcm/catalogs/search/overrides/{product_id}

There is one search override per product for the calling store or organization. The first successful PUT creates it. A later PUT changes the fields you send. Fields you leave out of fields stay as saved. PATCH is not supported.

Set a search override​

curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides/9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"type": "catalog_search_override",
"attributes": {
"fields": {
"name": {
"value": "Waterproof Hiking Boot"
}
}
}
}
}'

Success: 200 with the saved catalog_search_override. Each field in the response includes value, private, and owner (store or organization). private is always present. meta.created_at and meta.updated_at are always present.

A second PUT that sends only description keeps name:

{
"data": {
"type": "catalog_search_override",
"attributes": {
"fields": {
"description": { "value": "Keeps water out on wet trails" }
}
}
}
}

Field rules​

Send fields, cleared, or both. A request with neither is 400 and saves nothing.

RuleDetail
Field shapeEach entry under fields is an object with value. Optional private. A bare string, number, or list at that key is 400.
Removing a fieldvalue cannot be null. Use cleared to remove a field.
Field nameA core field that is not a pattern, or a field on the tenant's indexable fields. A pattern, such as a path with *, is not a name.
Object namesA name that is an object, such as shopper_attributes, is 400. Set one shopper attribute, admin attribute, or flow extension instead, such as shopper_attributes.color.
Value typeThe value must suit the field type. A number or boolean written to a string field is saved as a string. A date is saved and returned as you sent it, whether you send a date such as 2026-03-05 or Unix milliseconds. Filter that field with Unix milliseconds. An empty string is allowed only on a string field.
Admin attributesAn admin attribute is private. It is used in search, filters, and boosts, and it never appears in meta.search_overrides. The request must set "private": true.
JSON root fieldsA JSON root field cannot be overridden. Set a JSON child field, such as extensions.products(Details).attributes.color.
meta.searchPaths under meta.search, such as meta.search.nodes.name, are 400. Nodes on the hit stay as they were indexed.
PricingPricing fields are not a supported use.
ValidationAn invalid name or value is 400. meta.field names the problem. Nothing from that request is saved.

tags and meta.product_types are the only array fields a search override can set. Any other array is 400.

List indexed fields to see the names search already has.

Public and private values​

meta.search_overrides tells the shopper site which fields differ from the PXM product. The site applies those values. A private field is used in search and left out of the map. Admin attributes are private and never appear in that map.

privateSearch, filter, and sortHit meta.search_overrides
false (default)Uses the override valueShows the value
trueUses the override valueOmits the value

private: true removes the value from the hit and leaves it in search. Use cleared to remove the override.

{
"data": {
"type": "catalog_search_override",
"attributes": {
"fields": {
"admin_attributes.cost_band": { "value": "A", "private": true }
}
}
}
}

One shopper attribute among several​

Setting shopper_attributes.color changes that shopper attribute only. Others, such as fabric, stay as indexed and are not added to the override or the hit.

{
"data": {
"type": "catalog_search_override",
"attributes": {
"fields": {
"shopper_attributes.color": { "value": "teal" }
}
}
}
}

The same is true of one flow extension and of one JSON child field: the field you set changes, and the others stay as indexed.

Setting the field back to the PXM product value is a normal override. Search then uses that value.

Tags and product types​

tags and meta.product_types are replaced with the whole array you send, including an empty array. Send the full list you want search to use.

{
"data": {
"type": "catalog_search_override",
"attributes": {
"fields": {
"tags": { "value": ["waterproof", "hiking"] }
}
}
}
}

An empty array means that indexed field is empty. It stays a search override. Use cleared to remove it.

See the search override on a hit​

After search has caught up, a query for the override value returns the product. A query for the PXM product value of that field does not.

curl "https://useast.api.elasticpath.com/v2/pcm/catalog/search?q=Waterproof" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"hits": [
{
"document": {
"id": "9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"attributes": {
"name": "Trail Boot"
},
"meta": {
"search_overrides": {
"name": "Waterproof Hiking Boot"
}
}
}
}
]
}

PXM product data stays under attributes. meta.search_overrides is only the public fields the shopper site should apply. A private field is absent. A hit with no public override omits the map.

Clear one or more fields​

cleared removes those fields from the search override and keeps the search override. You can send fields and cleared in the same request.

curl -X PUT https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides/9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"type": "catalog_search_override",
"attributes": {
"cleared": ["description"]
}
}
}'

A cleared field drops from meta.search_overrides once search updates. The read does not list cleared names. A field absent from fields is not set on this search override, with one exception: a store clear of an organization field still returns that organization value. See Store and organization.

Search can keep the last override until the next indexing

Clearing a field you set, or deleting the search override, removes it from the hit. Search, filter, and sort keep matching the last override value until the release is next indexed. That indexing uses the PXM product value again.

A store clear of a field the organization set is different: shoppers then match the PXM product value, while list and get still return the organization value with cleared_at_store set to true.

When an organization clears a field the store has not set, shoppers in that organization's stores match the PXM product value. A field the store has set stays the store value.

An empty fields object is still 200. The search override still exists.

Delete the search override​

curl -X DELETE https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides/9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
-H "Authorization: Bearer $ACCESS_TOKEN"

Success: 204. A later get is 404. The hit no longer has meta.search_overrides. Search keeps matching the last override values until the release is next indexed. An organization delete follows the same rule as an organization clear.

Read a search override​

curl https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides/9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b \
-H "Authorization: Bearer $ACCESS_TOKEN"
ResultMeaning
200This store or organization has a search override, or a store is reading an organization search override for this product
404A store read when neither the store nor the organization has a search override. An organization read when the organization has none

A store read returns one search override. Each field's owner is store or organization. cleared_at_store is true only when the store cleared an organization field and the response still shows that organization value. An organization read does not include store fields. Another store's search override is not returned.

A get does not show whether search still matches a cleared field. Run a search to check.

List search overrides​

curl --globoff "https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides?page[limit]=25&page[offset]=0" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Results are this store or organization's search overrides, most recently updated first. Use page[limit] and page[offset]. A store list includes products that only the organization has set, with the same owner on each field as a single get.

Filter with the filter query. See Filtering.

OperatorAttributeMatches
eq, inidThose product ids
eqfields.<name>.valueSearch overrides whose saved value for that field equals the operand. <name> must be a field a search override can set
is_nullfields.<name>Search overrides that do not set that field, including a field that was cleared

A colon means both expressions match. A pipe means either expression matches. Any other operator, attribute, or name is 400 with detail Invalid search filter.

curl --globoff --get "https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
--data-urlencode "filter=eq(fields.name.value,Waterproof Hiking Boot)"

List and get are not for one release. When applies_to_releases_created_until is set, they compare that time with the current time to choose the override field owner that is shown and to match a filter on the field value.

Update many products​

POST /pcm/catalogs/search/overrides/bulk writes from 1 to 100 products. Each entry has the product id, type catalog_search_override, and the same attributes as a single update. Each product is saved on its own, with the same rules. Each product id may appear once.

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search/overrides/bulk \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": [
{
"id": "9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"type": "catalog_search_override",
"attributes": {
"fields": {
"name": { "value": "Waterproof Hiking Boot" }
}
}
},
{
"id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"type": "catalog_search_override",
"attributes": {
"cleared": ["name"]
}
}
]
}'

A well-formed request returns 200 even when some products fail. results has one entry per product, in request order.

statusMeaning
successThat product was saved. Use get to read it
failedThat product was not saved. The entry includes the attributes you sent and an error

A failed product does not stop the others.

An empty data array, more than 100 products, or the same product id twice returns 400, and no product is saved.

Store and organization​

A store write changes the store's search override. An organization write changes the organization's search override.

On a store's search index, a field the store set uses the store value. A field the store did not set uses the organization value. An organization's search index uses only the organization search override.

Example: the organization sets name to Summer tee and tags to ["sale"]. The store sets only name to Store tee. Store search uses Store tee and the organization tags. The store read shows name with owner store and tags with owner organization. The shopper hit shows those values and has no owner.

An organization write, clear, or delete of a field the store did not set is used in search for that organization's stores, including a store release that is still being indexed. A field the store has set stays the store value.

A store clear of a field that only the organization set uses the PXM product value in that store's search. The store read still shows the organization value, with owner organization and cleared_at_store true. An organization read does not show that store clear.

Which releases use the search override​

Send these beside fields or cleared. A release uses the search override when all of the following are true:

  1. The release allows search overrides.
  2. applies_to_releases_created_until is omitted, or the release was requested at or before that time.
  3. persist_across_releases is omitted or true, or the release already had a search index when you saved false.

applies_to_releases_created_until​

Optional date-time. It is the latest time a release can have been requested and still use the search override.

WriteWhat search does
Omit the attributeRemoves any saved time. There is no limit, including on a later update of a search override that had one
Send a time, including one already in the pastSaved and returned. A release requested at or before that time keeps the search override, including when that release is re-indexed after the time has passed
Release requested after that timeSearch shows the PXM product value, and the product is not an omitted catalog. A value already in an older search index stays until that release is re-indexed

A search index created before release request times were stored is left unchanged by a search override that sets this attribute, until that release is indexed again. Deleting the search override still removes meta.search_overrides from the hit.

Sending expires_at is a validation error and saves nothing.

persist_across_releases​

WriteWhat search does
Omit, or send trueLater releases that allow search overrides use it. Get returns true when the write omitted it
falseOnly releases that already had a search index when you saved it use the search override, including a release that is still being indexed. A release created later does not. Re-indexing a release that received it keeps it

A sent applies_to_releases_created_until stays saved when you omit persist_across_releases or send true.

{
"data": {
"type": "catalog_search_override",
"attributes": {
"fields": {
"name": { "value": "Waterproof Hiking Boot" }
},
"applies_to_releases_created_until": "2026-12-01T00:00:00Z",
"persist_across_releases": false
}
}
}

omitted_catalog_ids lists catalogs whose search leaves this product out. The product stays in the catalog.

WriteWhat search does
A list of catalog idsThose catalogs' search indexes omit the product. A catalog id with no search index for this store or organization omits nothing. Duplicate ids are saved once
Store ["all"]Omits the product from every catalog of that store. all must be the only entry
Organization ["all"]Omits the product from that organization's catalogs and from every store catalog of that organization, including a store catalog created later. This still applies when persist_across_releases is false. all must be the only entry
all mixed with a catalog idRefused
[]Clears the saved list. A search index that already omitted the product keeps omitting it until that release is indexed again
Omit the attributeKeeps the saved list

An organization catalog id does not omit a store catalog. A store's list does not omit an organization's catalogs.

{
"data": {
"type": "catalog_search_override",
"attributes": {
"omitted_catalog_ids": ["9f8f1b2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b"]
}
}
}

A store write cannot set an organization all. On a store list, get, or update, meta.organisation_omits_all_catalogs is true while the organization has omitted the product from every catalog. It is absent when that organization search override names specific catalogs or is not set. The store's omitted_catalog_ids stays the list the store saved.

A store clear does not return a product the organization omitted from every catalog. A release that does not allow search overrides keeps the product in search. A release requested after applies_to_releases_created_until is not omitted by that write.

Publish and re-index​

Publishing or re-indexing a release keeps a search override that the release should use. Public values are on the new hit.

  • A field that is set, including an empty tags or meta.product_types array, is on the new search index.
  • A field that was cleared uses the PXM product value after that indexing.
  • A change made while a release is being indexed appears in search for that release after indexing finishes. That release can be searched before the change appears. Releases already in search show the change shortly after you save it.

persist_across_releases: false still applies when you re-index a release that received the search override. A release created later does not use that search override. A store search override with persist_across_releases: false leaves organization fields in place: a store release created later still uses the organization values for fields the store did not set, when that release allows search overrides.

Validation and errors​

StatusWhen
400The request has neither fields nor cleared, or a bulk body is empty, has more than 100 products, or repeats a product id
400A field value is a bare string, number, or list, is null, or does not suit the field type. An unknown or object field name, a pattern, a JSON root field, or a meta.search path
400An admin attribute is sent without "private": true
400expires_at is sent, or omitted_catalog_ids is null, mixes all with a catalog id, or contains a value that is not a catalog id
400A list filter uses an unsupported operator, attribute, or field name
404Get when this store or organization has no search override to return
204Delete succeeded
Ask External AI