eBay Trading API
Call Reference Version 643

For GetProductFinder and GetProductSearchResults only: Identifier for a characteristic set (an attribute set) that is mapped to a catalog-enabled category (unique across all eBay sites). Required when you use SearchAttributes (for searches based on product search page and product finder data). Returns an error with QueryKeywords (use CharacteristicSetIDs instead). Use GetProductSearchPage or GetProductFinder to determine valid IDs for the type of search you are performing.

For GetProducts only: This field is not applicable to GetProducts. However, if you are using a SOAP toolkit and you get an error indicating that this field is required for GetProducts, you can specify this field with any integer value. It will be ignored by eBay.

If true, only retrieve products that have been used to pre-fill active listings on the specified eBay site. If false, retrieve all products that match the query. For GetProducts This is useful when you use QueryKeywords and you only want to find products that have items (that is, where ItemArray is not empty).

For GetProductSearchResults: Ths can be useful when you want to find products that other sellers have recently used to pre-fill similar listings.

List of one or more IDs that indicate which domain (characteristic set) to search in. If not specified, the search is conducted across all domains (characteristic sets).

For GetProducts Only useful when QueryKeywords is specified. If you use this with ProductReferenceID or ExternalProductID, AND logic is applied. In this case, if you specify an ID that doesn't match the product, no matching product will be found. Therefore, we recommend that you only use this with QueryKeywords.

For GetProductSearchResults: Only applicable when QueryKeywords is specified. Ignored when SearchAttributes is specified.

A query that only retrieves items that were listed with stock products that have ISBN or UPC values (such as books, DVDs, CDs, and video game products). Use this query to retrieve basic details about one catalog product (or a very limited number of products). The results can optionally include items, reviews, and/or buying guides that match that product. (Specifically, the items returned are items that sellers listed with the specified product's stock information.)

If you have gotten the ISBN or UPC from another Web site or resource, you can use that ID. Otherwise, call GetProducts with QueryKeywords (or ProductReferenceID). Any matching products that include ISBN or UPC values will return those values in Product.ExternalProductID.

The request requires either QueryKeywords, ProductReferenceID, or ExternalProductID, but these fields cannot be used together.

Pagination instruction that specifies the maximum quantity of products to return for each product family within the search response whose ID matches the current request's ID. In the response, if the last family returned contains MaxChildrenPerFamily or fewer additional products, those additional products are also returned (i.e., the actual quantity returned for the last family can exceed the specified maximum value). See "Limit the Quantity of Products Returned Per Family" in the eBay Web Services Guide. The value should not include punctuation (i.e., a thousands separator is not valid).

Pagination instruction that specifies the virtual page of data to return per search request. For GetProducts, this is primarily useful when you use QueryKeywords. When you use ExternalProductID or ProductReferenceID, only one page of data is typically returned.

Required when you are performing a sell-side product finder search. (Not applicable to product search page searches.) Numeric identifier for a sell-side product finder that was used to retrieve the search attributes being used in the request. The product finder must be mapped to a catalog-enabled category (i.e., it cannot be a buy-side product finder ID) associated with the characteristics set. Use a product finder when you want to specify multiple attributes in a product search query. Call GetCategory2CS to determine which categories support sell-side product finder searches.

Identifier for a representative stock product in a product family. Used as input in GetProductFamilyMembers requests to identify a product family. Use GetProductSearchResults to determine the available IDs.

The global reference ID for an eBay catalog product. Use this query to retrieve basic details about one catalog product. The results can optionally include items, reviews, and/or buying guides that match that product. (Specifically, the items returned are items that sellers listed with the specified product's stock information.)

To determine valid reference IDs, call GetProducts with QueryKeywords (or ExternalProductID). Each matching product returns a reference ID in Product.ProductReferenceID.

Note: This value is not the same as the ProductID used in AddItem and related calls. A ProductID represents a particular version of a catalog product. (A given version could have an older or newer description, set of Item Specifics, or other details.) A ProductReferenceID is a more generic or global reference to a product (regardless of version), which is useful for buy-side searching. One product reference ID can be associated with multiple product IDs.

As of mid-2008, some sites (such as eBay US, Germany, Austria, and Switzerland) are updating, replacing, deleting, or merging some products (as a result of migrating from one catalog data provider to another). If you specify one of these products, the call may return a warning, or it may return an error if the product has been deleted.

The request requires either QueryKeywords, ProductReferenceID, or ExternalProductID, but these fields cannot be used together.

Unique alphanumeric key help you distinguish between query results in the response. You define the key. Each search request ID must be unique within the same call. Primarily useful when conducting multiple searches in the same call. If not specified, the ProductSearchResult.ID values in the response are indexed starting from 0 (zero).

One or more keywords to search for. The words "and" and "or" are treated like any other word. Only use "and", "or", or "the" if you are searching for products containing these words. To use AND or OR logic, use eBay's standard search string modifiers. Wildcards (+, -, or *) are also supported. Be careful when using spaces before or after modifiers and wildcards.

For GetProducts When you use a keyword search, eBay searches the product database for matching words in the product title, description, and/or Item Specifics, and it returns a list of matching products (with no items, reviews, or guides). (To retrieve items, reviews, and/or guides for a particular product, use ProductReferenceID instead.) If specified, you must pass in at least 3 alphanumeric characters. Some keyword queries can result in response times of 30 seconds or longer. If more than 2000 matches are found, the call fails with an error. If this kind of error occurs, refine the search by passing in more keywords and/or by using CharacteristicSetIDs to restrict the search to certain domains (such as DVDs). If you are searching for a particular book, DVD, CD, or video game and you already know its ISBN (for a book) or UPC, consider using ExternalProductID instead to retrieve more precise results. The request requires either QueryKeywords, ProductReferenceID, or ExternalProductID, but these fields cannot be used together.

For GetProductSearchResults: eBay searches only in the characteristic set specified in CharacteristicSetIDs. Both the product title and Item Specifics are searched. For each ProductSearch, either SearchAttributes or QueryKeywords is required (but do not pass both). Blank searches are not applicable (and result in a warning). If your search is using a Keyword attribute returned by GetProductSearchPage, use SearchAttributes instead.

A predefined attribute against which to search (e.g., Author). Use this to create a query based on a set of Item Specifics from the catalog. Both the product title and product Item Specifics are searched. If the query includes multiple SearchAttributes fields (one for each attribute), the search engine will apply "AND" logic to the query. Call GetProductSearchPage or GetProductFinder to determine the list of valid attributes and how many are permitted for the specified characteristic set. See the eBay Web Services guide for details. For each ProductSearch, either SearchAttributes or QueryKeywords is required (but do not pass both).

Unique identifier for a sortable attribute. Use GetProductSearchPage or GetProductFinder to determine the valid sort attribute IDs for the specified characteristic set (including the default sort attribute that will be used if you do not specify this field).