Item Search API Output Response

This topic applies to

Applies to

SuiteCommerce | SuiteCommerce Advanced | SuiteCommerce InStore


The response data includes the following properties:

  • total – This is the number of items that match the search query, but without taking into account the stock level variance since the last search index update. Consequently, the actual number of items displayed on the page might be less than the total displayed.

    For example, if your search query matches only nine items out of the 1000 items in your catalogue, the value of total displayed is nine. If three out of these nine matching items go out of stock since the last search index update, only six items are displayed even though the value of total displayed is nine.


    If you use the url parameter to request an item by specifying the url component value, total is not displayed in the Item Search API output response.

  • items – This is an array of items that includes the fields specified using the fields or fieldset parameter. Note that the following output for the items property shows fields that are included in the search field set, which was specified in the sample query:

    items: [ { ispurchasable: false, custitem_ns_pr_attributes_rating: "", showoutofstockmessage: true, custitem38: false, custitem33: "&nbsp;", itemid: "OL5299", onspecial: false, onlinecustomerprice: 19.99, pricelevel5: 19.99, outofstockbehavior: "Disallow back orders but display out-of-stock message", storedescription2: "Features<BR>-Cool.Q™ ZERO provides an immediate and ongoing cooling sensation<BR>-Mesh sides for ventilation<BR>-Lightweight foam brim folds up and packs down small for shoving in a pack<BR>- Drawcord attachment under the chin", storedisplayname2: "Chiller Wide Brim Hat", custitem_onsale: false, internalid: 6548 } ],
  • facets – This shows the facets associated with items returned in the response data. Use the include parameter to show all of facets you defined in on the Web Site Setup page. Note the following sample from the output response shows IDs for two facets, Ideal For and Collection. Each facet has two facet values.

    facets: [ { id: "Ideal For", values: [ { url: "Men", label: "Men" }, { url: "Women", label: "Women" } ] }, { { id: "Collection", values: [ { url: "Spring", label: "Spring" }, { url: "Fall", label: "Fall" } ] }, {

    For more information on defining facets in NetSuite, see Select and Configure Facet Fields.

  • links – These links support pagination and are automatically returned in response data. You can also build the URL for the next set of results using the limit and offset parameters returned by the API. You can click next href in the query results to increment the offset parameter by the value of limit and view the next set of results. You can also click prev href in the query results to decrease the value of the offset parameter by the value of limit. Note that the value of limit remains unchanged.

    links: [ { rel: "next", href: "" }, ],
  • corrections – This property displays the past and present values for facet URL components in the Item Search API request. If you have not entered any aliases in NetSuite for facets or facet values you used in the past, then the corrections property does not return any data.

    For example, in the past you may have used custitem_category as a facet. At that time, the facet value was Hockey Player. Today, you are using Equipment Category as the facet, and the current facet value is Player. When you modify the facet URL values, you can add the original values to the Alias list in NetSuite. If you query the Item Search API using the original facet names and values, then corrections are returned in the response data. For more information about entering URL component aliases, see the help topic URL Components for Facets.

    Since the following API request includes the original facet and facet value, the output response to the following query string includes corrections:

    Note that both past and current facet URL components are included in the response data:

    corrections: [ { type:"facet", id:"custitem_category", usedAlias:"custitem_category", url:"EquipmentCategory" }, { type:"facet-value", facet:"custitem_category", usedAlias:"HockeyPlayer", url:"Player" } ],
  • locale – This is an object that represents the locale with respect to internationalization. You can troubleshoot errors related to currency mismatch by verifying the details in the locale section. When you are using the Multiple Currencies feature, you should always select the correct default locale on the currency record. For example, select New Zealand (English) as the default locale for New Zealand Dollar.

    locale: { country: "US", language: "en", currency: "USD", region: 17 },

    For more information, see the help topic Localization.

  • volatility – This refers to the CDN cache settings for your Commerce implementation. CDN caching can be set for a shorter period of time or a longer period of time. The length of time that a certain type of content is cached on CDN depends on the value of TTL (Time To Live) in CDN, which could be one of the following:

    • Unique — This asset is not cached.

    • Short — This asset may change frequently, so cache it for five minutes.

    • Medium — This asset may or may not change frequently, so cache it for two hours.

    • Long — This asset is not expected to change frequently, so cache it for seven days.

    By default, the Item Search API response data has a volatility of Short. CDN caching can be set for a shorter period of time or a longer period of time as described in Configure CDN Caching. However, changing the CDN cache setting in your application can have a significant performance impact.


    If you exclude the pricelevel parameter from the Item Search API URL, the volatility is automatically set to Unique.

    In pre-Elbrus releases of SuiteCommerce Advanced, the Item Search API response data is not cached in the CDN by default. To enable caching of the Item Search API response, you must customize your implementation to include the pricelevel input parameter as described in Item Search API Response Data not Cached.

  • code – This is the HTTP status code. All responses should have a status code or a message that allows the client to continue processing the results or handle the error if necessary. If the request is successful, a 200 status code indicates that the request was received, understood, and has been processed.

  • warnings – If you have specified a parameter in the query that the API does not recognize, the parameter is ignored and a warning message is displayed in the API response. In the following Item Search API response, a warning message is displayed indicating that the non-existent parameter foo has been ignored.

    "warnings": { "processeduri":"" , "ignoredparams": [ "foo" ] }