Item Search API Input Parameters
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 (&
).
Some parameters, when used with the base URL, 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 |
---|---|
|
Retrieve Items by NetSuite Account Number, Commerce Site ID, Subsidiary ID |
|
|
|
|
|
|
|
|
|
Retrieve Items from Personalized Catalog for a specific customer or one or more customer groups |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Retrieve Items by NetSuite Account Number, Commerce Site ID, Subsidiary ID
-
c
— You can use the parameterc
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 parametern
to specify the ID of your Commerce web store and retrieve all the items in the specified Commerce web store. For example, if the ID of your Commerce web store is 3, you can use the following query string to retrieve all the items that belongs to this Commerce web store:http://www.mywebstore.com/api/items?n=3
-
region
— You can use the parameterregion
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 Commerce web store 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
If you specify an incorrect NetSuite account number, an incorrect Commerce 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
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
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
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 about 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
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 about selecting and configuring Sort Fields, see Select and Configure Sort Fields.
Retrieve Items by Commerce Categories
-
commercecategoryid
— You can use the parametercommercecategoryid
to retrieve items that belong the specified Commerce Category ID.http://www.mywebstore.com/api/items?commercecategoryid=12345
-
commercecategoryurl
— You can use the parametercommercecategoryurl
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 parametercommercecategoryname
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 Add Commerce Categories to Website Search Index.
For a sample search query and response on Commerce Categories, see Sample Search Query for Returning Categories.
Retrieve Items from Personalized Catalog for a specific customer or one or more customer groups
To be able to use the pcv_entity
and pcv_groups
parameters, the user must have a valid NetSuite user account and be assigned a role that provides edit website or list items permissions. For more information, see Personalized Catalog Views Roles and Permissions. Note that these parameters are intended for administrative interfaces only and not for building web pages that display a personalized catalog.
-
use_pcv
— For the Personalized Catalog Views feature to take effect while retrieving items, you must use theuse_pcv
parameter with the Item Search API. When theuse_pcv
parameter is set to true, the Item Search API returns tailored selection of catalog items from the user's customer groups. The Item Search API query without theuse_pcv
parameter has the same effect asuse_pcv=F
. Therefore, when theuse_pcv
parameter is set to false, the Item Search API serves items for anonymous users regardless of whether the user is logged in or recognized.For example, a NetSuite user with sufficient permissions for PCV posts the following query:
http://www.mywebstore.com/api/items?use_pcv=T
The Item Search API lists all the items but only shows the items which should be visible for this user.
Note:By default, the Item Search API response data has a volatility of Short or Medium. Volatility refers to the CDN cache settings for your Commerce implementation. If the
use_pcv
parameter is set to true, the Item Search API always serves non-cacheable responses, which is evident in the Item Search API response where volatility=unique. The Item Search API query without theuse_pcv
parameter has the same effect asuse_pcv=F
. Therefore, if theuse_pcv
parameter is set to false, the Item Search API uses the existing caching behavior. -
pcv_entity
— You can use thepcv_entity
parameter to specify a single entity ID to be used as the basis for customer groups to apply query filtering. For thepcv_entity
parameter to take effect while retrieving items, you must also specifyuse_pcv=T
with thepcv_entity
parameter.For example, let’s consider there are items on the site assigned to these four customer groups: ALL_USERS, GUEST_USERS, RECOGNIZED_USERS and VIP_USERS. Items assigned to the VIP_USERS customer group are exclusive items and are not available for customers in other customer groups. There is a customer, say CUSTOMER1, with Customer ID 111 who belongs to the VIP_USERS customer group. A NetSuite user with sufficient permissions for PCV posts the following query:
http://www.mywebstore.com/api/items?use_pcv=T&pcv_entity=111
The Item Search API returns all the items available for customer with customer ID 111 in the response, which includes items from ALL_USERS, RECOGNIZED_USERS and VIP_USERS customer group.
Note:If you specify an invalid entity ID (for example, a string) or an incorrect entity ID (for example, a valid number but a non-existent entity ID) with the
pcv_entity
parameter, no items are returned in the Item Search API response. If you specify more than one entity ID with thepcv_entity
parameter, an error message is displayed. -
pcv_groups
— You can use thepcv_groups
parameter to specify one or more customer group IDs to apply query filtering. For thepcv_groups
parameter to take effect while retrieving items, you must also specifyuse_pcv=T
with thepcv_groups
parameter.For example, let’s consider there are items on the site assigned to these three customer groups: ALL_USERS (Customer Group ID= 1), GUEST_USERS (Customer Group ID= 2) , RECOGNIZED_USERS (Customer Group ID= 3). A NetSuite user with sufficient permissions for PCV posts the following query:
http://www.mywebstore.com/api/items?use_pcv=T&pcv_groups=3
The Item Search API returns all the items assigned to the group RECOGNIZED_USERS.
Note:If you specify an invalid group ID (for example, a string) or an incorrect group ID (for example, a valid number but a non-existent group ID) with the
pcv_groups
parameter, no items are returned in the Item Search API response. If you specify two group IDs with thepcv_groups
parameter with one existing group ID and one non-existent group ID, only the items for the existing group are returned in Item Search API response.
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 parameterfields
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 parameterfieldset
to retrieve all the item fields associated with a field set.http://www.mywebstore.com/api/items?fieldset=details
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 parametermatrixchilditems_fieldset
to specify the field set that overrides the reservedmatrixchilditems
field set. Thematrixchilditems
field set is used by thematrixchilditems_detail
derived field by default to retrieve the item fields of all the matrix child items. In the following example, the defaultmatrixchilditems
field set is overridden with a field set namedmini
using the Item Search API parametermatrixchilditems_fieldset
.http://www.mywebstore.com/api/items?fieldset=search&matrixchilditems_fieldset=mini
-
correlateditems_fieldset
— You can use the parametercorrelateditems_fieldset
to specify the field set that overrides the reservedcorrelateditems
field set. Thecorrelateditems
field set is used by thecorrelateditems_detail
derived field by default to retrieve the item fields of all the correlated items. In the following example, the defaultcorrelateditems
field set is overridden with a field set namedmini
using the Item Search API parametercorrelateditems_fieldset
.http://www.mywebstore.com/api/items?fieldset=search&correlateditems_fieldset=mini
-
relateditems_fieldset
— You can use the parameterrelateditems_fieldset
to specify the field set that overrides the reservedrelateditems
field set. Therelateditems
field set is used by therelateditems_detail
derived field by default to retrieve the item fields of all the related items. In the following example, the defaultrelateditems
field set is overridden with a field set namedmini
using the Item Search API parameterrelateditems_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.
The Item Search API is not designed for deep pagination. Therefore, using offset and limit to page through sorted results works well if you only need to access the first few pages of the search results.
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 suffixranges
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-10,10-20,20-*
.The range buckets in this example are 1 to 10, 10 to 20, and 20 or more.
The range buckets used to compute range faceting are inclusive of their lower bounds and exclusive of their upper bounds. In the above example, 10 is considered in the range bucket 10 to 20 and not in the range bucket 0 to 10.
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. Also, you can only use the field ID of the facet field in facet range filters, and not the URL component of the facet.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:When the Prices Include Tax preference is set, tax is included in the price of each item. However, the Item Search API does not support the Tax Inclusive Pricing feature. Therefore, tax exclusive prices are used when you filter the items using any price-related facet.
Include or Exclude Item Attributes
-
include
— You can use the parameterinclude
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 parameterfacet.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. Thefacet.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¤cy=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.
If you are sorting by a field which is empty for a particular item, the item is excluded from sorting and is displayed at the end of the list.
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
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.
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¤cy=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 Creating Currency Records.
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
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 more information about localizing site templates and using multiple languages, see Localization.
Callback Function
You can use the parameter callback
to define the JavaScript callback function 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