CatalogSearchAPI - Scoped, Global

  • Release version: Australia
  • Updated June 29, 2026
  • 9 minutes to read

    • 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.

    CatalogSearchAPI - CatalogSearch()

    Creates an instance of the CatalogSearchAPI class.

    Table 1. Parameters
    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.
    Table 2. Parameters
    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
    Table 3. Returns
    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'

{
   "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.

    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
}