Product Catalog Search Service

The Product Catalog Search Service is a SOAP API that enables developers to query and retrieve specific product information from an advertiser’s product catalogs. Developers may search by any number of criteria including price, currency, country, serviceable area and UPC.

Note: Product catalogs with ads designated as private (within the CJ Account Manager) are not available through the Product Catalog Search API. In the future, Commission Junction plans to support this functionality, in which only the advertiser-designated publishers will have access to these private product catalogs.

To access the Product Catalog Search Service in REST instead of SOAP, click here.

Click the following links to display more specific information.

• Request Parameters

  Request Parameters

  Refer to the following table for a list of the required and optional request parameters.  All parameter names and values are case sensitive.

  Important: You must provide all required parameters and at least one of the optional parameters. Submitting an empty request does not return all possible results; an empty request returns zero results.

  Parameter Name	Value	Req?	Description
  developerKey	String	Required	Your developer key obtained from the Web Services Developer Site.
  websiteId	String	Required	This value is your Web site ID (PID), which enables the system to generate the appropriate link code in the response. The PID must match the Web site PID which you used to register for the developer key (passed in the developerKey parameter).
  advertiserIds	String	Optional	Limits the results to a set of particular advertisers (CIDs) using one of the following four values. CIDs: You may provide list of one or more advertiser CIDs, separated by commas, to limit the results to a specific sub-set of merchants. Empty String: You may provide an empty string to remove any advertiser-specific restrictions on the search. joined: This special value (joined) restricts the search to advertisers with which you have a relationship. notjoined: This special value (notjoined) restricts the search to advertisers with which you do not have a relationship.
  keywords	String	Optional	This value restricts the search results based on keywords found in the advertiser’s name, the product name or the product description. This parameter may be left blank if other parameters (such as upc, isbn) are provided. You may use simple Boolean logic operators (’r;+’, ’r;-’r;) to obtain more relevant search results. By default, the system assumes basic OR logic. The examples below illustrate how these operators affect search results. Query Results "kitchen sink" Any product with the word "kitchen" or "sink" "+kitchen +sink" Any product with the words "kitchen" and "sink" "+kitchen -sink" Any product with "kitchen" and without "sink" "kitchen +sink" All the products with the word "sink"; if they also contain "kitchen", it increases the product’s relevancy.
  serviceableArea	String	Optional	Limits the results to a specific set of advertisers’ targeted areas.
  isbn	String	Optional	Limits the results to a specific product from multiple merchants identified by the appropriate unique identifier; ISBN.
  upc	String	Optional	Limits the results to a specific product from multiple merchants identified by the appropriate unique identifier; UPC.
  manufacturerName	String	Optional	Limits the results to a particular manufacturer's name.
  manufacturerSku	Long	Optional	Limits the results to a particular manufacturer's SKU number.
  advertiserSku	String	Optional	Limits the results to a particular advertiser SKU.
  lowPrice	Double	Optional	Limits the results to products with a price greater than or equal to the lowPrice. Tip: Use in conjunction with the highPrice to specify a specific range of prices Note: Only whole numbers are supported for this request parameter. The lowPrice parameter is inclusive, whereas the highPrice parameter is exclusive. For example, using a low price of 10 and a high price of 20 will return everything from 10 to 19.99.
  highPrice	Double	Optional	Limits the results to products with a price less than or equal to the highPrice. Tip: Use in conjunction with the lowPrice to specify a specific range of prices. Note: Only whole numbers are supported for this request parameter. The lowPrice parameter is inclusive, whereas the highPrice parameter is exclusive. For example, using a low price of 10 and a high price of 20 will return everything from 10 to 19.99.
  lowSalePrice	Double	Optional	Limits the results to products with a price greater than or equal to the Advertiser offered lowSalePrice. Note: Only whole numbers are supported for this request parameter. The lowSalePrice parameter is inclusive, whereas the highSalePrice parameter is exclusive. For example, using a low sale price of 10 and a high sale price of 20 will return everything from 10 to 19.99.
  highSalePrice	Double	Optional	Limits the results to products with a price less than or equal to the Advertiser offered highSalePrice. Note: Only whole numbers are supported for this request parameter. The lowSalePrice parameter is inclusive, whereas the highSalePrice parameter is exclusive. For example, using a low sale price of 10 and a high sale price of 20 will return everything from 10 to 19.99.
  currency	String	Optional	Limits the results to one of the following currencies. USD EUR GBP
  sortBy	String	Optional	Sort the results in the response by one of the following values. Name Advertiser ID Advertiser Name Currency Price salePrice Manufacturer SKU UPC Note: Only the results returned in the particular request are sorted by the value of this parameter. The system automatically sorts all matching results in the index (not just the results in the specific request) by relevance to keyword value sent in the request. Example Sample search parameter values for this example: keywords = shoes startAt = 0 maxResults = 500 sortBy = Price Suppose the index contains 5,432 possible results. The system automatically sorts those results based on their relevance to the keywords value (shoes). Then, the system pulls the top 500 results and sorts those 500 results based on your sortBy value (Price). Thus, the response includes the 500 most relevant matches, sorted by price.
  sortOrder	String	Optional	Specifies the order in which the results are sorted; the following case-sensitive values are acceptable. asc: ascending (default value) dec: descending
  startAt	String	Optional	Specifies the first record to return in the request. The first record is 0. Leaving this parameter blank assigns a default value of 0. Please refer to the note below the table for more information.
  maxResults	String	Optional	Specifies the number of records to return in the request. Leaving this parameter blank assigns a default value of 50. Note: 1000 results is the system limit for results per request. If you request a value greater than 1000, the system only returns 1000. Please refer to the note below the table for more information.

  Note: If startAt is 10,000 or more, the system will return a response with zero products found. If startAt is lower than 10,000, but (startAt + maxResults) is more then 10,000, then the system will only return up to the 10,000th hit. For example, if an incoming request specifies startAt=9985 and maxResults=50, then the search will return records with startAt=9985 but only up to 15 records in the response.

  The following table provides an example of how to use startAt and maxResults values to obtain a total of 1000 results, with 250 results at a time.

  Request number	startAt value	maxResults value
  Request 1	0	250
  Request 2	250	250
  Request 3	500	250
  Request 4	750	250

  For more information refer to the forums at the Web Services Developer Site (http://webservices.cj.com).

• Response Fields

  Response Fields

  The response includes information about the general response, as well as specific information for each record in the response. By default, the results are sorted by price, from low to high. All parameter names and values are case sensitive.

   

  General

  The response includes the following information about the overall set of results in the response.

  Field Name	Value	Description
  count	Integer	The number of results included in the response.  This value is always less than or equal to the maxResults value. Note: The count value may be smaller than maxResults depending on the startAt value. For example, if a particular search has 115 possible matches, and you specified a startAt value of 0 and a maxResults value of 200, the service would only return (and the count value would be equal to) the 115 possible results.
  offset	Integer	This is the page number; it is equal to the startAt value you provide.
  products	Array	An array of product records. Refer to the Per Record (Product) table below for the fields returned for each product record in the response.
  totalResults	Integer	The total number of matching products in the index, regardless of the number of results in the actual response (the value of the maxResults parameter).

  Per Record (Product)

  The response includes the following fields for each record (i.e., product).

  Note: Product data is based on the information provided by the advertiser. Advertisers may choose to not provide some product data (for example, the upc field), and as a result, this info is also unavailable through the Product Catalog Search service.

  Field Name	Value	Description
  adId	String	The associated ad identification number.
  advertiserId	Integer	The advertiser’s CID.
  advertiserName	String	The advertiser’s name.
  buyUrl	String	The URL on the advertiser's Web site where you may purchase the product.
  catalogId	String	The identification number for the associated Commission Junction product catalog.
  currency	String	The 3-letter currency code associated with the product.
  description	String	A description of the product.
  imageUrl	String	A direct link to an image of the product.
  inStock	String	Displays whether the product is currently in stock.
  isbn	String	Unique identifier (ISBN) for a product or products that would identify the same product from multiple merchants.
  manufacturerName	String	The name of the manufacturer of the associated product.
  manufacturerSku	String	The manufacturer sku number for the associated product.
  name	String	The name of the product.
  price	Double	The actual price of the associated product.
  retailPrice	Double	The suggested retail price of the product.
  salePrice	Double	The advertiser offered sale price of the product.
  sku	String	The associated product’s SKU number.
  upc	String	Unique identifier (UPC) for a product or products that identifies the same product from multiple merchants.

• Errors

  Errors

  Error	Description
  Not Authenticated	The system could not authenticate your developer key.