Search Settings

Overview

Search settings are a small set of store-level switches that shape every search on an index:

• Rank an exact SKU match first
• Push out-of-stock products down the results, or leave them to your own filter
• Choose how aggressively low-relevance results are dropped
• Give facet fields customer-friendly display names

Each setting is applied to the index configuration for you, so you do not need to edit searchConfig directly. If you need finer control over the underlying search parameters, see Configure Index.

Both endpoints on this page take your API key as a bearer token:

• Authorization: Bearer {api_key}

Changes reach search traffic within about a minute.

Settings

Setting	Type	Values	What it does
skuField	string	Any document field	The field that holds the product SKU. When a shopper's query is exactly a SKU, the matching product is ranked first. Set to null or "" to turn this off.
outOfStockBehavior	string	filter_by_api, deboost, none	How out-of-stock products are handled. deboost keeps them in the results but ranks them below everything in stock. filter_by_api leaves it to the filter you pass in each search request. none applies no special treatment.
stockAvailabilityField	string	Any boolean document field	The field that says whether a product is in stock. Required when outOfStockBehavior is deboost.
stockAvailabilityFieldMeaning	string	in_stock, out_of_stock	What a true value in stockAvailabilityField means. Required when outOfStockBehavior is deboost.
outOfStockFilter	string	A filter expression	A filter that identifies out-of-stock products, used by the merchandising tools. Set to "" to clear it.
relevanceSearch	string	strict, weak	Whether low-relevance results are dropped from the tail of an unsorted search. strict drops them, so shoppers see fewer but more relevant results. weak keeps them.
relevanceSort	string	strict, weak	The same choice for searches that pass a sortBy. With strict, only relevant results are sorted; with weak, every match is sorted.
fieldDisplayNames	object	Field name to label	Customer-facing labels for facet fields, for example {"productVendor": "Brand"}. Search responses return these as fieldLabels alongside facets, so your storefront can render the label without a lookup table. At most 200 entries; each label must be 1 to 80 characters.

Get Search Settings

Endpoint: GET https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/settings

cURL

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/settings \
  -H "Authorization: Bearer {api_key}"

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/settings", {
  headers: {
    "Authorization": "Bearer {api_key}",
  },
});

Response

The response contains the settings above. A setting that has never been written is omitted, in which case the index uses its default behaviour.

{
  "skuField": "sku",
  "outOfStockBehavior": "deboost",
  "stockAvailabilityField": "inStock",
  "stockAvailabilityFieldMeaning": "in_stock",
  "relevanceSearch": "strict",
  "relevanceSort": "weak",
  "fieldDisplayNames": {
    "productVendor": "Brand",
    "productType": "Category"
  }
}

The response may also include a read-only relevanceTriggerConfig object. It is configured by the Marqo team and cannot be set through this endpoint.

Errors

Status	Body	When
404	{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}	No index with this name exists in your account, it belongs to a different account, or it is still being provisioned.

Update Search Settings

Endpoint: PATCH https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/settings

The body wraps the settings in a searchSettings object. The update is a partial merge: only the keys you include are changed, and every other setting keeps its current value. Send null (or "" for string settings) to clear a setting.

Request Body

Parameter	Type	Default	Description
searchSettings	object	Required	One or more of the settings above. An empty object is accepted and changes nothing.

Example Request

This example ranks exact SKU matches first, pushes out-of-stock products to the bottom, and labels two facet fields.

cURL

curl -X PATCH https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/settings \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
  "searchSettings": {
    "skuField": "sku",
    "outOfStockBehavior": "deboost",
    "stockAvailabilityField": "inStock",
    "stockAvailabilityFieldMeaning": "in_stock",
    "fieldDisplayNames": {
      "productVendor": "Brand",
      "productType": "Category"
    }
  }
}'

JavaScript

fetch("https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/settings", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer {api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    searchSettings: {
      skuField: "sku",
      outOfStockBehavior: "deboost",
      stockAvailabilityField: "inStock",
      stockAvailabilityFieldMeaning: "in_stock",
      fieldDisplayNames: {
        productVendor: "Brand",
        productType: "Category",
      },
    },
  }),
});

Response

204 No Content on success.

Errors

Status	Body	When
400	{"error": "[<index>] ..."}	The settings are inconsistent, for example outOfStockBehavior is deboost but stockAvailabilityField or stockAvailabilityFieldMeaning is missing. Nothing is written.
404	{"error": "Marqo settings not found for shop {system_account_id}-{index_name}"}	No index with this name exists in your account, it belongs to a different account, or it is still being provisioned.
422	{"error": [...]}	The body contains a key that is not a recognised setting, a value outside the allowed set, or fieldDisplayNames breaks the size limits (fieldDisplayNames supports at most 200 entries, fieldDisplayNames values must be 1-80 characters).

How the settings affect search

SKU matching. With skuField set, the SKU field is made available for merchandising and a boost is added so that a query matching a SKU exactly returns that product in first position. Products indexed before the setting was turned on are reprocessed automatically so the boost applies to them too.

Out-of-stock deboost. With outOfStockBehavior set to deboost, products whose stockAvailabilityField marks them as out of stock receive a large penalty on every search and on collection pages, so they appear after every in-stock result. They are not removed, so a shopper searching for a specific out-of-stock item can still find it.

Relevance strictness. Hybrid search returns every product that matches at least one query term, which can leave a long tail of weak matches. strict cuts that tail off; weak keeps it, which suits stores that prefer a fuller result set over precision.

Display names. fieldDisplayNames does not change how documents are indexed or searched. It only adds fieldLabels to search responses for the facet fields that have a label, so it is safe to change at any time.

Next Steps

• AI Search: Send searches and read facets and fieldLabels in the response
• Configure Index: Default search parameters and indexing options
• Boost and Bury: Merchandising rules on top of these settings