--- title: Product Catalog Search API description: The Product Catalog Search API searches the product catalog and retrieves the eligible catalog-category hierarchy for a given context. Search supports multiple catalog types, with paginated and sortable results.Searches the product catalog and returns a paginated list of products that match the supplied search parameters. locale: en-US canonical_url: https://www.servicenow.com/docs/r/api-reference/rest-apis/product-catalog-search-api.html release: brazil product: REST APIs classification: rest-apis topic_type: concept last_updated: "2026-09-10" reading_time_minutes: 15 breadcrumb: [REST API reference, API reference, API implementation and reference] --- # Product Catalog Search API The Product Catalog Search API searches the product catalog and retrieves the eligible catalog-category hierarchy for a given context. Search supports multiple catalog types, with paginated and sortable results. The Product Catalog Search API provides the ability to: - Search products by search term across one or all catalogs and across one or all categories within a catalog. - Retrieve the eligible catalog-category hierarchy for a context, with ineligible catalogs and categories filtered out. - Filter results by catalog, category, and catalog type \(defaults to Product Offering\). - Supply a header context object to apply account-specific pricing, price lists, currency, channel, shipping/billing address, and sales agreement to search results. - Page through result sets using a zero-based page index and page limit. - Control sort order and sort field \(for example, by relevance score\). - Optionally pass an AI Search suggestion ID to support AI-assisted search flows. This API delegates all data retrieval to the existing script include, ensuring consistent behavior between the UI and the REST interface. Endpoints are independent and can be called individually. There is no required call order and no dependency on other APIs. The [CatalogSearchAPI - Scoped, Global](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/CatalogSearchAPI-scoped_global.md) wraps this REST API. ## Requirements This API is included in the Product Catalog Management Core application, which is available on the ServiceNow Store. This API is provided within the `sn_prd_pm` namespace and requires the Product Catalog Management Core plugin \(sn\_prd\_pm\) to access it. The calling user must have the sn\_prd\_pm.product\_catalog\_viewer or sn\_prd\_pm.external\_product\_viewer roles. **Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/rest-apis/api-rest.md) ## Product Catalog Search - POST /api/sn\_prd\_pm/catalog/search Searches the product catalog and returns a paginated list of products that match the supplied search parameters. Use this endpoint whenever an external application or agent needs to retrieve products from the catalog. For example, to populate a shopping interface, drive an AI recommendation flow, or validate catalog availability. The endpoint delegates to the existing script include entry point and supports the same context-aware pricing and eligibility logic available in the Product Catalog UI. ### Additional usage notes - If **headerContext** is provided only with `account` but other context values such as **pricelist**, **currency** aren't provided, they are automatically fetched based on the given account to evaluate eligibility rules. - If user has their own context variables for eligibility, those can be passed in **headerContext**. - If **headerContext** isn't provided, the currency will default to the system currency and standard price list. - Pass **sortOrder**, **sortBy** and **aiSearchSuggestionId** request parameters only if AI Search + RAG setup for product catalog search is done on the instance. ### URL format Base URL: `/api/sn_prd_pm/{api_version}/catalog/search` ### Supported request parameters
| Name | Description |
|---|---|
| api\_version | Required. Version of the endpoint to access. Valid value: `v1`. Requests made without the version fails with a "Requested URI doesn't represent any resource" error. Data type: String |
| Name | Description |
|---|---|
| aiSearchSuggestionId | Sys\_id of an AI Search suggestion record to associate with this search request. Used to support AI-assisted search flows.Data type: String Default: empty string |
| catalogType | Type of catalog items to search. Case-sensitive.Valid values: - `PRODUCT_OFFERING`: Fetch product offerings. - `SERVICE_SPECIFICATION`: Fetch service specifications. Data type: String |
| headerContext | Context object that controls pricing, eligibility, and localization applied to search results. When omitted, the API derives context from the account if one is provided.Data type: Object ``` "headerContext": { "account": "String", "currency": "String", "billing_city": "String", "billing_country": "String", "billing_location": "String", "billing_state": "String", "billing_street": "String", "billing_zip": "String", "pricelist": "String", "sales_agreement": "String", "shipping_city": "String", "shipping_country": "String", "shipping_location": "String", "shipping_state": "String", "shipping_street": "String", "shipping_zip": "String", "suppressPricing": String, "transaction_date": "String" } ``` |
| headerContext.account | Sys\_id of the account to use for context resolution. When provided and other context fields are omitted, pricing and eligibility are resolved from the account.Data type: String |
| headerContext.billing\_city | City for the billing address. Data type: String |
| headerContext.billing\_country | Country for the billing address. Example: `USA`Data type: String |
| headerContext.billing\_location | Sys\_id of the billing location record.Table: Location \[location\] Data type: String |
| headerContext.billing\_state | State or province for the billing address. Example: `TX`Data type: String |
| headerContext.billing\_street | Street address for billing.Data type: String |
| headerContext.billing\_zip | Postal code for the billing address. Example: `75254-7536`Data type: String |
| headerContext.currency | Currency code to use for pricing. Example: `USD`.Data type: String Default: Derived from account if not supplied. If account not provided, resolves to system currency. |
| headerContext.pricelist | Sys\_id of the price list to apply.Table: Pricing List \[sn\_csm\_pricing\_price\_list\] Default: Derived from account if not supplied. Data type: String |
| headerContext.sales\_agreement | Sys\_id of the sales agreement to apply.Table: Sales Agreement \[sn\_sales\_agmt\_core\_sales\_agreement\] Data type: String |
| headerContext.shipping\_city | City for the shipping address. Data type: String |
| headerContext.shipping\_country | Country for the shipping address. Example: `USA`Data type: String |
| headerContext.shipping\_location | Sys\_id of the shipping location record.Table: Location \[location\] Data type: String |
| headerContext.shipping\_state | State or province for the shipping address. Example: `TX`Data type: String |
| headerContext.shipping\_street | Street address for shipping. Data type: String |
| headerContext.shipping\_zip | Postal code for the shipping address. Example: `75254-7536`Data type: String |
| headerContext.suppressPricing | Optional. Flag that indicates whether to suppress pricing information in the response. Valid values: - `true`: Pricing is suppressed. - `false`: Pricing is included. Data type: Boolean Default: false |
| headerContext.transaction\_date | Date and time of the transaction.Format: `yyyy-MM-dd HH:mm:ss` \(Example: 2026-03-30 20:20:08\) Data type: String |
| pageIndex | Zero-based index of the page of results to return. Data type: Number \(integer\) Minimum value: 0 Default: 0 |
| pageLimit | Number of search results per page.Data type: Number Default: 10 |
| searchTerm | Keyword or phrase to search for in the product catalog. When null or empty, returns all products in the specified catalog.Data type: String Default: null |
| selectedCatalog | Sys\_id of the catalog to search. Table: Product Offering Catalog \[sn\_prd\_pm\_product\_offering\_catalog\] Data type: String Default: “allCatalog” \(searches across all catalogs\) |
| selectedCategory | Sys\_id of the category to filter results by. If providing this value, you must pass the **selectedCatalog** to which that particular category belongs to.Table: Product Offering Category \[sn\_prd\_pm\_product\_offering\_category\] Data type: String Default: “showAll” \(returns results from all categories within the catalog\) |
| sortBy | Field to sort results by. Accepted values are dependent on the value of **catalogType**.Valid values: - PRODUCT\_OFFERING: - `code` - `description` - `display_name` - `name` - `score` - For SERVICE\_SPECIFICATION: - `description` - `display_name` - `name` - `score` - `specification_code` Data type: String |
| sortOrder | Sort direction for results.Valid values: - `ascending` - `descending` Data type: String Default: descending |
| Name | Description |
|---|---|
| count | Number of product offerings in the `response` array.Data type: Number |
| leafCategoryList | A comma-separated string of eligible leaf category sys\_ids used to filter product offerings, derived from the selected catalog and category hierarchy. Only included in the output when not already provided in the input filter. Data type: String |
| response | An array matching the current filter criteria, including search terms, selected category, and eligibility rules.Data type: Array of Objects ``` "response": [ { "code": {Object}, "description": {Object}, "listPrice": "String", "name": {Object}, "offerType": {Object}, "offerTypeVariation": "String", "priceList": "String", "pricingMethod": "String", "productOfferingFamily": {Object}, "productOfferingSysId": {Object}, "uom": {Object} } ] ``` |
| response.code | Product offering code.Data type: Object ``` "code": { "value": "String", "displayValue": "String" } ``` |
| response.code.displayValue | Display value of the field.Data type: String |
| response.code.value | Stored \(raw\) value of the field.Data type: String |
| response.derivedPrice | Flag that indicates whether the product's price is calculated dynamically based on related products, product characteristics, or predefined pricing rules rather than having a fixed catalog list price.Valid values: - true: Product's price is calculated dynamically. - false: Product's price is calculated using a fixed catalog list price. Data type: Boolean |
| response.description | Details about the product offering.Data type: Object ``` "description": { "value": "String", "displayValue": "String" } ``` |
| response.description.displayValue | Display value of the field.Data type: String |
| response.description.value | Stored \(raw\) value of the field.Data type: String |
| response.items.semanticSimilarity | Relevance or semantic score assigned to this result by the AI search engine. Field is absent from non-AI Search responses.Data type: Number |
| response.listPrice | Formatted list price of the product offering \(for example, `"$50.00"`\). May be absent if no price is configured.Data type: String |
| response.name | Display name of the product offering.Data type: Object ``` "name": { "value": "String", "displayValue": "String" } ``` |
| response.name.displayValue | Display value of the field.Data type: String |
| response.name.value | Stored \(raw\) value of the field.Data type: String |
| response.offerType | Type of the product offering \(for example, `simple`, `config`, or `simple_with_spec`\).Data type: Object ``` "offerType": { "value": "String", "displayValue": "String" } ``` |
| response.offerType.displayValue | Display value of the field.Data type: String |
| response.offerType.value | Stored \(raw\) value of the field.Data type: String |
| response.offerTypeVariation | Variation type of the offering, typically matching offerType.Data type: String |
| response.priceList | Sys\_id of the associated price list record. May be absent if no price list is assigned.Data type: String |
| response.pricingMethod | Pricing method for the offering.Possible values: - `one_time` - `recurring` Data type: String |
| response.productOfferingFamily | Product offering family to which the offering belongs to.Data type: Object ``` "productOfferingFamily": { "value": "String", "displayValue": "String" } ``` |
| response.productOfferingFamily.displayValue | Display value of the field.Data type: String |
| response.productOfferingFamily.value | Stored \(raw\) value of the field.Data type: String |
| response.productOfferingSysId | List containing the sys\_id\(s\) of the product offering record\(s\).Data type: Object ``` "productOfferingSysId": { "value": "String", "displayValue": "String" } ``` |
| response.productOfferingSysId.displayValue | Display value of the field.Data type: String |
| response.productOfferingSysId.value | Stored \(raw\) value of the field.Data type: String |
| response.uom | Unit of measure for the offering.Data type: Object ``` "uom": { "sysId": "String", "name": "String" } ``` |
| response.uom.name | Display name of the unit of measure \(for example, `Each`\).Data type: String |
| response.uom.sys\_id | Sys\_id of the unit-of-measure record.Data type: String |
| response.visual | URL to the product offering's image/thumbnail, if configured and if sn\_prd\_pm.show\_product\_visuals system property is enabled.Data type: String |
| selectedCatalogHierarchy | List of all eligible catalog objects when no default catalog is configured and "All Catalogs" is the selected view.Data type: Array of Objects ``` "selectedCatalogHierarchy": [ { "id": "String", "label": "String", "children": [] } ] ``` |
| selectedCatalogHierarchy.children | Child category nodes. Dependent on the value set for **selectedCategory** in the request: - Value is empty or `showAll` \(default\): Returns an empty array \(`[]`\) when there are no children; the `showAll` node returns an empty object \(`{}`\). - Value is a sys\_id: Returns the child sys ID, display value, and any nested children associated with the given category sys\_id. Data type: Object or Array ``` //'selectedCategory' is 'showAll' { "id": "showAll", "label": "Show all", "children": {} } ``` ``` //'selectedCategory' is sys_id { "id": "String", "label": "String", "children": [ { "id": "String", "label": "String", "children": [Array] } ] } ``` |
| selectedCatalogHierarchy.id | Category identifier. A sys\_id for catalog categories, or the literal `showAll` for the "Show all" option.Data type: String |
| selectedCatalogHierarchy.label | Display name of the category.Data type: String |
| spellCorrectedTerm | Spell-corrected version of the search term, returned when AI Search + RAG is enabled and a correction is available. Field is absent from non-AI Search responses.Data type: String |
| suggestedRecordDisplayName | Display name of a suggested record, returned when AI Search + RAG is enabled and a direct match suggestion exists.Data type: String |