CatalogSearchAPI- Scoped, Global

CatalogSearchAPI is a script include used to fetch product catalog data from all application scopes.

The CatalogSearchAPI API is available by default with the Product Catalog Management application and is offered as the script include sn_prd_pm.CatalogSearchAPI under the namespace sn_prd_pm. No special roles are required to access this API.

Find the REST version of this API at Product Catalog Search API.

Note: There are distinct differences between this API and CatalogSearch - Scoped though they're almost identically named. CatalogSearch API is a native ServiceNow platform API documented in the public API reference under com.glideapp.servicecatalog.CatalogSearch. It provides basic catalog item search functionality available in scoped scripts via the standard platform.

This API, CatalogSearchAPI (sn_prd_pm.CatalogSearchAPI), is the script include wrapper API specific to the Product Catalog Management application. It extends beyond the native API to support product offerings and service specifications, with richer filtering, account-based pricing and eligibility via headerContext, and AI Search integration.

Parent Topic:Server API reference

CatalogSearchAPI - CatalogSearch()

Creates an instance of the CatalogSearchAPI class.

Name	Type	Description
None

The following example is a constructor for the CatalogSearchAPI class:

var catalogSearch = new sn_prd_pm.CatalogSearchAPI();

CatalogSearchAPI – getCatalogData(Object input)

Searches the product catalog and returns matching catalog items with optional pricing information. Supports searching across multiple catalog types.

Capabilities provided:

Search products by search term across one or all catalogs and across one or all categories within a catalog.
Filter results by catalog, category, and catalog type (defaults to Product Offering).
Page through result sets using a zero-based page index and page limit.
Supply a header context object to apply account-specific pricing, price lists, currency, channel, shipping/billing address, and sales agreement to search results.
Control sort order and sort field (for example, by relevance score).
Optionally pass an AI Search suggestion ID to support AI-assisted search flows.

Name	Type	Description
aiSearchSuggestionId	String	Sys\_id of an AI Search suggestion record to associate with this search request. Used to support AI-assisted search flows.Default: empty string
catalogType	String	Type of catalog items to search. Case-sensitive.Valid values: - `PRODUCT_OFFERING`: Fetch product offerings. - `SERVICE_SPECIFICATION`: Fetch service specifications.
headerContext	Object	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. "headerContext": { "account": "String", "pricelist": "String", "currency": "String", "suppressPricing": String, "transaction_date": "String", "shipping_city": "String", "shipping_country": "String", "shipping_location": "String", "shipping_state": "String", "shipping_street": "String", "shipping_zip": "String", "billing_city": "String", "billing_country": "String", "billing_location": "String", "billing_state": "String", "billing_street": "String", "billing_zip": "String", "sales_agreement": "String" }
headerContext.account	String	Optional. 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.
headerContext. billing\_city	String	Optional. City for the billing address.
headerContext. billing\_country	String	Optional. Country for the billing address.
headerContext. billing\_location	String	Optional. Sys\_id of the billing location record.Table: Location \[location\]
headerContext. billing\_state	String	Optional. State or province code of the billing address.
headerContext. billing\_street	String	Optional. Street address for billing.
headerContext. billing\_zip	String	Postal code for the billing address. Example: `75254-7536`Data type: String
headerContext.currency	String	Currency code to use for pricing. Example: `USD`.Default: Derived from account if not supplied. If account not provided, resolves to system currency.
headerContext.pricelist	String	Optional. Sys\_id of the price list to apply.Table: Pricing List \[sn\_csm\_pricing\_price\_list\] Default: Derived from account if not supplied.
headerContext. sales\_agreement	String	Optional. Sys\_id of the sales agreement to apply.Table: Sales Agreement \[sn\_sales\_agmt\_core\_sales\_agreement\]
headerContext. shipping\_city	String	Optional. City for the shipping address.
headerContext. shipping\_country	String	Optional. Country for the shipping address. Example: `USA`
headerContext. shipping\_location	String	Sys\_id of the shipping location record.Table: Location \[location\]
headerContext. shipping\_state	String	State or province for the shipping address. Example: `TX`
headerContext. shipping\_street	String	Optional. Street address for shipping.
headerContext. shipping\_zip	String	Optional. Postal code for the shipping address. Example: `75254-7536`
headerContext. suppressPricing	Boolean	Optional. Flag that indicates whether to suppress pricing information in the response. Valid values: - `true`: Pricing is suppressed. - `false`: Pricing is included. Default: false
headerContext. transaction\_date	String	Date and time of the transaction.Format: `yyyy-MM-dd HH:mm:ss` $Example: 2026-03-30 20:20:08$
pageIndex	Number	Optional. Zero-based index of the page of results to return. Minimum value: 0 Default: 0
pageLimit	Number	Optional. Number of search results per page.Default: 10
searchTerm	String	Optional. Keyword or phrase to search for in the product catalog. When null or empty, returns all products in the specified catalog. Default: null
selectedCatalog	String	Sys\_id of the catalog to search. Table: Product Offering Catalog \[sn\_prd\_pm\_product\_offering\_catalog\] Default: “allCatalog” $searches across all catalogs$
selectedCategory	String	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] Default: “showAll” (returns results from all categories within the catalog)
sortBy	String	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` `specificaton_code` Data type: String
sortOrder	String	Optional. Sort direction for results.Valid values: - `ascending` - `descending` Default: descending

Type	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": [ { "productOfferingSysId": {Object}, "code": {Object}, "name": {Object}, "description": {Object}, "offerType": {Object}, "pricingMethod": "String", "uom": {Object}, "offerTypeVariation": "String", "listPrice": "String", "priceList": "String" } ]`
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.items.description	Details about the product offering.Data type: Object `"description": { "value": "String", "displayValue": "String" }`
response.items.description.displayValue	Display value of the description.Data type: String
response.items.description.value	Stored $raw$ value of the description.Data type: String
response.items. listPrice	Formatted list price of the product offering $for example, `"$50.00"`$. May be absent if no price is configured.Data type: String
response.items.offerType	Type of the product offering $for example, `simple`, `config`, or `simple_with_spec`$.Data type: Object `"offerType": { "value": "String", "displayValue": "String" }`
response.items.offerType.displayValue	Display value of the field.Data type: String
response.items.offerType.value	Stored $raw$ value of the field.Data type: String
response.items. offerTypeVariation	Variation type of the offering, typically matching offerType.Data type: String
response.items. priceList	Sys\_id of the associated price list record. May be absent if no price list is assigned.Data type: String
response.items.pricingMethod	Pricing method for the offering.Possible values: - `one_time` - `recurring` Data type: String
response.items. productOfferingSysId	List containing the sys\_id$s$ of the product offering record$s$.Data type: Object `"productOfferingSysId": { "value": "String", "displayValue": "String" }`
response.items. semanticSimilarity	Relevance or semantic score assigned to this result by the AI search engine.Data type: Number
response.items.uom	Unit of measure for the offering.Data type: Object `"uom": { "sysId": "String", "name": "String" }`
response.items.uom.name	Display name of the unit of measure $for example, `Each`$.Data type: String
response.items.uom.sysId	Sys\_id of the unit-of-measure record.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. productOfferingSysId.displayValue	Display value of the field.Data type: String
response. productOfferingSysId.value	Stored $raw$ value of the field.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'</p> <p>{ "id": "showAll", "label": "Show all", "children": {} }</p> <div class="highlight"><pre><span></span><code>` //'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.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

Search by keyword within a catalog and category

The following example searches for offerings matching the term router within a specific catalog and category, with an account context for pricing and eligibility.

var req = {
    "searchTerm": "router",
    "selectedCatalog": "<catalog_sys_id>",
    "selectedCategory": "<category_sys_id>",
    "headerContext": {
        "account": "<account_sys_id>"
    }
};

var res = new sn_prd_pm.CatalogSearchAPI().getCatalogData(req);
gs.info(JSON.stringify(res));

Output:

{
  "selectedCatalogHierarchy": [
    {
      "id": "showAll",
      "label": "Show all",
      "children": {}
    },
    {
      "id": "<catalog_sys_id_1>",
      "label": "Networking",
      "children": []
    },
    {
      "id": "<catalog_sys_id_2>",
      "label": "Internet",
      "children": []
    }
  ],
  "leafCategoryList": "<category_sys_id>",
  "response": [
    {
      "productOfferingSysId": {
        "value": "<product_offering_sys_id_1>",
        "displayValue": "<product_offering_sys_id_1>"
      },
      "code": {
        "value": "ROUTERPRO1",
        "displayValue": "ROUTERPRO1"
      },
      "name": {
        "value": "Pro Router X100",
        "displayValue": "Pro Router X100"
      },
      "description": {
        "value": "High-performance dual-band router for home and business use.",
        "displayValue": "High-performance dual-band router for home and business use."
      },
      "offerType": {
        "value": "simple",
        "displayValue": "simple"
      },
      "pricingMethod": "one_time",
      "uom": {
        "sysId": "<uom_sys_id>",
        "name": "Each"
      },
      "offerTypeVariation": "simple",
      "listPrice": "$150.00",
      "priceList": "<pricelist_sys_id>",
      "derivedPrice": false
    }
  ],
  "count": 1
}

Search using the full parameter set with a complete header context

The following example performs a search request using all available parameters and a complete header context, including explicit pricing, currency, and shipping and billing addresses.

var req = {
    "searchTerm": "laptop",
    "selectedCatalog": "<catalog_sys_id>",
    "selectedCategory": "<category_sys_id>",
    "pageIndex": 0,
    "pageLimit": 10,
    "catalogType": "PRODUCT_OFFERING",
    "sortOrder": "descending",
    "sortBy": "score",
    "aiSearchSuggestionId": "",
    "headerContext": {
        "account": "<account_sys_id>",
        "pricelist": "<pricelist_sys_id>",
        "currency": "USD",
        "suppressPricing": false,
        "transaction_date": "2026-01-15 09:00:00",
        "shipping_city": "Chicago",
        "shipping_country": "USA",
        "shipping_location": "<shipping_location_sys_id>",
        "shipping_state": "IL",
        "shipping_street": "123 Main Street, Chicago",
        "shipping_zip": "60601",
        "billing_city": "Chicago",
        "billing_country": "USA",
        "billing_location": "<billing_location_sys_id>",
        "billing_state": "IL",
        "billing_street": "123 Main Street, Chicago",
        "billing_zip": "60601"
    }
};

var res = new sn_prd_pm.CatalogSearchAPI().getCatalogData(req);
gs.info(JSON.stringify(res));

Output:

{
  "selectedCatalogHierarchy": [
    {
      "id": "showAll",
      "label": "Show all",
      "children": {}
    },
    {
      "id": "<catalog_sys_id_1>",
      "label": "Computers",
      "children": []
    },
    {
      "id": "<catalog_sys_id_2>",
      "label": "Mobile Devices",
      "children": []
    }
  ],
  "leafCategoryList": "<category_sys_id>",
  "response": [
    {
      "productOfferingSysId": {
        "value": "<product_offering_sys_id_1>",
        "displayValue": "<product_offering_sys_id_1>"
      },
      "code": {
        "value": "LAPTOPBIZ15",
        "displayValue": "LAPTOPBIZ15"
      },
      "name": {
        "value": "Business Laptop 15\"",
        "displayValue": "Business Laptop 15\""
      },
      "description": {
        "value": "15-inch business laptop with 16GB RAM and 512GB SSD.",
        "displayValue": "15-inch business laptop with 16GB RAM and 512GB SSD."
      },
      "offerType": {
        "value": "simple",
        "displayValue": "simple"
      },
      "pricingMethod": "one_time",
      "uom": {
        "sysId": "<uom_sys_id>",
        "name": "Each"
      },
      "offerTypeVariation": "simple",
      "listPrice": "$1,200.00",
      "priceList": "<pricelist_sys_id>",
      "derivedPrice": false
    }
  ],
  "count": 1
}

Search for service specifications by keyword

The following example searches for service specifications matching the term vpn service.

var req = {
    "searchTerm": "vpn service",
    "catalogType": "SERVICE_SPECIFICATION"
};

var res = new sn_prd_pm.CatalogSearchAPI().getCatalogData(req);
gs.info(JSON.stringify(res));

Output:

{
  "response": [
    {
      "productOfferingSysId": {
        "value": "<product_offering_sys_id_1>",
        "displayValue": "<product_offering_sys_id_1>"
      },
      "code": {
        "value": "MANAGEDVPNSERVICE",
        "displayValue": "MANAGEDVPNSERVICE"
      },
      "name": {
        "value": "Managed VPN Service",
        "displayValue": "Managed VPN Service"
      },
      "description": {
        "value": "Managed VPN Service",
        "displayValue": "Managed VPN Service"
      },
      "offerType": {
        "value": "config",
        "displayValue": "config"
      }
    },
    {
      "productOfferingSysId": {
        "value": "<product_offering_sys_id_2>",
        "displayValue": "<product_offering_sys_id_2>"
      },
      "code": {
        "value": "MANAGEDVPNSERVICEV2",
        "displayValue": "MANAGEDVPNSERVICEV2"
      },
      "name": {
        "value": "Managed VPN Service v2",
        "displayValue": "Managed VPN Service v2"
      },
      "description": {
        "value": "Managed VPN Service",
        "displayValue": "Managed VPN Service"
      },
      "offerType": {
        "value": "config",
        "displayValue": "config"
      }
    }
  ],
  "count": 2
}