Item Search API Input Parameters

This topic applies to

Applies to

SuiteCommerce Web Stores

The Item Search API Input Parameters are used to construct query strings that return item record attributes in a JSON response. To create a query string for the Item Search API, you should use the input parameters with the base URL http://www.mywebstore.com/api/items?{parameters}. You can also use multiple parameters with the base URL by separating them with an ampersand (&).

Note

Some parameters when used with the base URL just return the item IDs of the matching items. However, if you want to retrieve additional item details, you can use the parameters listed under the Retrieve Additional Item Details section with these parameters.


The base URL when used without any parameters retrieves the item IDs of all the items. To retrieve only the desired items and item details, you can specify the following input parameters:

Parameters

Usage

c

n

region

Retrieve Items by NetSuite Account Number, SuiteCommerce Site ID, Subsidiary ID

id

Retrieve Items by Item ID

url

Retrieve Items by Item URL

q

Retrieve Items by Keyword Search

commercecategoryid

commercecategoryurl

commercecategoryname

Retrieve Items by Commerce Categories

fields

fieldset

Retrieve Additional Item Details

matrixchilditems_fieldset

correlateditems_fieldset

relateditems_fieldset

Flexibility in Specifying the Field Sets of Related Items

limit

offset

Pagination of Query Results

<field_name>

<numeric_facet_field_ID>.ranges

<numeric_facet_field_ID>.from

<numeric_facet_field_ID>.to

Facet and Filter Items

include

facet.exclude

Include or Exclude Item Attributes

sort

Sort Items

pricelevel

Specify Price Level

currency

Specify Currency

language

country

Specify Language and Country

callback

Callback Function

ssdebug

Retrieve Debug Information

Retrieve Items by NetSuite Account Number, SuiteCommerce Site ID, Subsidiary ID
  • c — You can use the parameter c to specify the NetSuite account and retrieve all the items in the specified NetSuite account. For example, if your NetSuite account is 3925062, you can use the following query string to retrieve all the items that belongs to your NetSuite account:

    http://www.mywebstore.com/api/items?c=3925062

  • n — You can use the parameter n to specify the ID of your SuiteCommerce website and retrieve all the items in the specified SuiteCommerce website. For example, if the ID of your SuiteCommerce website is 3, you can use the following query string to retrieve all the items that belongs to this SuiteCommerce website:

    http://www.mywebstore.com/api/items?n=3

  • region — You can use the parameter region to specify the Subsidiary in a NetSuite OneWorld account and retrieve all the items in the specified Subsidiary. For example, if your Subsidiary ID is 4, you can use the following query string to retrieve all the items that belongs to this Subsidiary:

    http://www.mywebstore.com/api/items?region=4

You can also use these parameters together to further refine the search results. For example, if have more than one SuiteCommerce Website in a NetSuite account and you would like to retrieve items belonging to a particular site, you can use the following query string:

http://www.mywebstore.com/api/items?c=3925062&n=3

Note

If you specify an incorrect NetSuite account number, an incorrect SuiteCommerce Site ID, an incorrect or inactive Subsidiary ID, or if your website is not reachable, no items are returned and an error message is displayed.


Retrieve Items by Item ID

You can use the parameter id to specify the item record ID and retrieve information for a particular item. For example, you can use the following query string to retrieve the item with Item ID 123:

http://www.mywebstore.com/api/items?id=123

To return multiple items in response data, list multiple item IDs separated by commas. For example, you can use the following query string to retrieve the items with Item ID 123, 456, 789:

http://www.mywebstore.com/api/items?id=123,456,789

Note

If the item is marked as Inactive or if the Display in Web Store box is not selected on the item record, no items are returned. If you specify an invalid item ID, an error message is displayed. In case of Matrix items, active child items are returned only if the parent item is active and the Display in Web Store box is selected.


Retrieve Items by Item URL

You can use the parameter url to specify the value in the URL Component field on the item record. The url parameter returns the Item ID of item that matches the URL component value in the request.

http://www.mywebstore.com/api/items?url=Vok-500-Cellular-Phone

You can specify other parameters along with the url parameter to retrieve other item details. For example, you can use the fields parameter to retrieve associated images:

http://www.mywebstore.com/api/items?url=Vok-500-Cellular-Phone&fields=itemimages_detail

You can also use a field set that contains image information:

http://www.mywebstore.com/api/items?url=Vok-500-Cellular-Phone&fieldset=details

Note

If the item is marked as Inactive or if the Display in Web Store box is not selected on the item record, no items are returned. If you specify an invalid item URL, an error message is displayed. In case of Matrix items, active child items are returned only if the parent item is active and the Display in Web Store box is selected.


Retrieve Items by Keyword Search

You can use the parameter q to retrieve all the items that match the specified keyword. For example, q=jeans searches for that keyword in the fields listed on the Search Fields subtab.

http://www.mywebstore.com/api/items?q=jeans

Note

Matching items are returned only if the specified keyword exists in the search fields that you selected on the Web Site Setup page. For information on selecting Search Fields, see Select Search Fields.


To do a multi-term search, specify two or more terms in the URL separated by whitespace. For example, q=denim jeans searches for these keywords in the fields listed on the Search Fields subtab.

http://www.mywebstore.com/api/items?q=denim jeans

Note

Relevance is the default sort order when you use the q parameter to query the Item Search API. Your preferred sort order specified on the Sort Fields subtab is overridden. For information on selecting and configuring Sort Fields, see Select and Configure Sort Fields.


Retrieve Items by Commerce Categories
  • commercecategoryid — You can use the parameter commercecategoryid to retrieve items that belong the specified Commerce Category ID.

    http://www.mywebstore.com/api/items?commercecategoryid=12345

  • commercecategoryurl — You can use the parameter commercecategoryurl to retrieve items that belong the specified Commerce Category URL.

    http://www.mywebstore.com/api/items?commercecategoryurl=/apparel/partywear/shoes

  • commercecategoryname — You can use the parameter commercecategoryname to retrieve items that belong the specified Commerce Category.

    http://www.mywebstore.com/api/items?commercecategoryname=Summer Sale

    This parameter is dependent on the Commerce Category facet field being defined in the Web Site Setup record. For more information, see the help topic Add Commerce Categories to Website Search Index.

Note

For a sample search query and response on Commerce Categories, see Sample Search Query for Returning Categories.


Retrieve Additional Item Details

If you do not specify any input parameters with the Item Search API base URL, only the Item IDs of the items are returned. You can use the following parameters to retrieve additional item details:

  • fields — You can use the parameter fields to retrieve additional item record fields in the API response. Your request can include a valid field ID, or multiple field IDs separated by commas to return multiple fields.

    http://www.mywebstore.com/api/items?fields=custitem1,upccode

  • fieldset — You can use the parameter fieldset to retrieve all the item fields associated with a field set.

    http://www.mywebstore.com/api/items?fieldset=details

Note

When the Commerce Category field is defined in the Web Site Setup record field sets, the Commerce Category details for a given item are returned.


Flexibility in Specifying the Field Sets of Related Items
  • matrixchilditems_fieldset — You can use the parameter matrixchilditems_fieldset to specify the field set that overrides the reserved matrixchilditems field set. The matrixchilditems field set is used by the matrixchilditems_detail derived field by default to retrieve the item fields of all the matrix child items. In the following example, the default matrixchilditems field set is overridden with a field set named mini using the Item Search API parameter matrixchilditems_fieldset.

    http://www.mywebstore.com/api/items?fieldset=search&matrixchilditems_fieldset=mini

  • correlateditems_fieldset — You can use the parameter correlateditems_fieldset to specify the field set that overrides the reserved correlateditems field set. The correlateditems field set is used by the correlateditems_detail derived field by default to retrieve the item fields of all the correlated items. In the following example, the default correlateditems field set is overridden with a field set named mini using the Item Search API parameter correlateditems_fieldset.

    http://www.mywebstore.com/api/items?fieldset=search&correlateditems_fieldset=mini

  • relateditems_fieldset — You can use the parameter relateditems_fieldset to specify the field set that overrides the reserved relateditems field set. The relateditems field set is used by the relateditems_detail derived field by default to retrieve the item fields of all the related items. In the following example, the default relateditems field set is overridden with a field set named mini using the Item Search API parameter relateditems_fieldset.

    http://www.mywebstore.com/api/items?fieldset=search&relateditems_fieldset=mini

Pagination of Query Results

You can use the parameter offset in combination with another parameter limit to paginate Item Search API query results. The offset parameter specifies the offset from the first result and the limit parameter specifies the number of items that can be displayed on each page. For example, you can retrieve query results from the eleventh item to the fifteenth item using the following query string:

http://www.mywebstore.com/api/items?offset=10&limit=5

You can click next at the bottom of the query result to increment the offset parameter by the value of limit. Note that the value of limit remains unchanged. In the above example, when you click next, the value of offset changes to 15 and the next five items are displayed. Also, you can click prev at the bottom of the query result to decrease the value of the offset parameter by the value of limit. In the above example, when you click prev, the value of offset changes to 5 and the previous five items are displayed.

Note

The default value of the offset parameter is 0 and that of the limit parameter is 50. Therefore, when you do not specify offset and limit, the first 50 items are displayed in the query results.


Facet and Filter Items
  • <facet_field_name> — You can specify the facet field name and facet values to retrieve the item IDs of the items associated with the specified facets and facet values. For example, you can filter items for the specified facets and facet values:

    http://www.mywebstore.com/api/items?color=red,blue&gender=women

    If you are unsure about the facet value or if special characters are included in the facet value you want to specify in the query, you can call the Search API requesting all facets. For example, you can request all facets using the following query string:

    http://www.mywebstore.com/api/items?pricelevel=5&include=facets

    You can then use the appropriate value that is contained in the response to construct your API query.

    Note

    If you create a custom list intended for use as a facet, do not include a comma in any of the list values. In an API request, the comma is interpreted as a separator between multiple options.


  • <numeric_facet_field_ID>.ranges — You can use the parameter <numeric_facet_field_ID>.ranges to define range buckets for numeric facets fields such as price. Use the suffix ranges on the field ID to perform the search. For example, you can retrieve an array of range buckets with the number of items in each bucket using the following query string:

    http://www.mywebstore.com/api/items?pricelevel5.ranges=1-9.99,10-19.99,20-*.

    The range buckets in this example are 1 to 9.99, 10 to 19.99, and 20 or more.

    Note

    Facet ranges do not filter, but instead show additional data in the facet section of the JSON response pertaining to how many items are in each range.


  • <numeric_facet_field_ID>.from&<numeric_facet_field_ID>.to — To specify a range of values to search for on item records, you can use the parameters <numeric_facet_field_ID>.from and <numeric_facet_field_ID>to. Use the suffix from and to on the field ID to perform the search. Both from and to are required, and excluding one results in an error.

    For example, you can retrieve all the items with a price between 10 and 20 (both inclusive) using the following query string:

    http://www.mywebstore.com/api/items?pricelevel5.from=10&pricelevel5.to=20

    Note

    You can only use the field ID of the facet field in facet range filters, and not the URL component of the facet.


Include or Exclude Item Attributes
  • include — You can use the parameter include to specify an item attribute in the API request and retrieve additional data in the JSON response. For example, the following sample query includes facet fields in the JSON response:

    http://www.mywebstore.com/api/items?include=facets

  • facet.exclude — You can use the parameter facet.exclude to exclude fields from faceting in Item Search API calls. Excluding facet fields that are not essential can help speed up the API calls. The facet.exclude parameter accepts comma delimited facet field names.

    In the following example, the API call specifies a facet value for filtering (custitem_categories=Kitchen-Utensils), while excluding the field from faceting (facet.exclude=custitem_categories).

    http://www.mywebstore.com/api/items?include=facets&fieldset=search&language=en&country=US&currency=USD&pricelevel=5&c=1234567&n=2&custitem_Utensils&sort=pricelevel5&asc&limit=24&offset=0&c=1234567&facet.exclude=custitem_categories

Sort Items

You can use the parameter sort to define the sort order of search results on your website. By using the field ID you want to sort by in the API request, you can retrieve item record data sorted by the field ID included in the API request. You can find the field ID on the Sort Fields subtab on the Web Site Setup page. An Item Search API request overrides your settings on the Search Fields tab. Supported sort orders are ascending (asc) and descending (desc).

For example, you can sort the items by their store display name using the following query string:

http://www.mywebstore.com/api/items?sort=storedisplayname:asc

Items are sorted by category when the value of commercecategory and either commercecategoryid or commercecategoryurl are specified. This is dependent on the Commerce Category sort field being defined in the Web Site Setup record.

For more information about setting up web site preferences for sorting in NetSuite, see Select and Configure Sort Fields.

Specify Price Level

You can use the parameter pricelevel to specify the price level ID for items. The price level ID can be different depending on how price levels are configured in your NetSuite account. Typically, the default online price in NetSuite is pricelevel=5.

http://www.mywebstore.com/api/items?pricelevel=4&include=facets

Note

If you have set up multiple price levels for items, ensure that you add all the price level fields as sort fields. For more information, see Select and Configure Sort Fields. Also, if Alternate Price is not defined for an item but is set to be displayed in a field set, then the value of Alternate Price defaults to the Online Price. If Online Price is also not defined for the item, then the value of Alternate Price defaults to the Base Price.


When a customer with a custom price level is logged in on the web store, the price level assigned to that customer is retrieved instead of the default online price level. For example, the default online price is pricelevel=5, but the price level assigned to a certain customer may be pricelevel=4. When this customer is browsing in the web store, the customer’s assigned price, pricelevel=4 is sent in the search API call. Consequently, the custom price (pricelevel=4) is displayed to this customer for all the products in the web store.

Note

The pricelevel parameter is only usable when a user with permissions to see the requested pricelevel is logged in. In all other cases, the pricelevel displayed is in accordance with the default setting in the Web Site Set Up record.


Specify Currency

Prices are usually displayed in the default currency that you have set up for your website. In an account that uses the Multiple Currencies feature, you can use the parameter currency with the ISO Country Code to specify the currency format in which you want to display prices for the items.

http://www.mywebstore.com/api/items?fields=onlinecustomerprice_formatted,pricelevel5&currency=USD

If you are using the Multiple Currencies feature, ensure that you select the correct default locale on the currency record to avoid any errors related to currency mismatch. For example, select New Zealand (English) as the default locale for New Zealand Dollar. For more information, see the help topic Creating Currency Records.

Note

If you specify a currency that is not associated with your website or if the Online box is not checked for that currency on the Web Site Setup record, an error message is returned.


Specify Language and Country

A shopper on your website can use their local language to search and browse products on your website. The translated text that shoppers see in product views is based on the translated text you set up on item records. The JSON response data includes item attributes and field set fields in the languages you have set up in your NetSuite account. You must add the corresponding fields to a field set and also check that the field set is included in the Reference ShopFlow SuiteApp. By default, items are returned with fields containing the default language. You can use the language and country parameter to specify the translated text you set up in NetSuite.

In the following example, the search results are displayed in Spanish:

http://www.mywebstore.com/api/items?fieldset=search&country=ES&language=es

Note

You must always use the language and country parameters together. The country code that you specify should be in uppercase and the langue code should be in lowercase.


All ISO country and language codes are valid if the language is set up for use on your website. To affect the language displayed in a product view, the site template must be localized. For details on localizing site templates and using multiple languages, see the help topic Localization.

Callback Function

You can use the parameter callback to define the JavaScript callback function in order to wrap the JSON response.

For example, you can create a variable name mycallback by using the callback parameter as shown in the following sample query:

http://www.mywebstore.com/api/items?callback=mycallback

Retrieve Debug Information

You can use the parameter ssdebug and set its value to true to retrieve the debug information in the JSON response.

http://www.mywebstore.com/api/items?ssdebug=true