eBay Trading API
Call Reference Version 579

Restricts listings to return only items that have the Ad Format feature. If true, the values of ItemTypeFilter and StoreSearchFilter are ignored (if they are specified). That is, "AND" logic is not applied.

Container for affiliate tags. If you use affiliate tags, it is possible to get affiliate commissions based on calls made by your application. (See the eBay Partner Network for information about commissions.) Affiliate tags enable the tracking of user activity. You can use child tags of AffiliateTrackingDetails if you want call output to include a string that includes affiliate tracking information.

Limits the results to items with a minimum or maximum number of bids. You also can specify a bid range by specifying both a minimum and maximum number of bids in one call.

Retrieves statistical (histogram) information about categories that contain items that match the query. Can also cause the result to include information about buying guides that are associated with the matching categories. Does not control the set of listings to return or the details to return for each listing.

Limits the result set to items in the specified category. If no category ID is specified, all categories are searched by default.

Note: CategoryID does not control whether you will see the item's categories in the response. Set the value of DetailLevel to ItemReturnCategories to retrieve each item's primary category and secondary category (if any) in the response.

If the specified category ID doesn't match an existing category for the site, an invalid-category error message is returned. Here are a few ways to determine valid categories:
- Use the Categories input field to retrieve matching categories, and then submit the request again with one of those categories.
- Find items in all categories but set DetailLevel to ItemReturnCategories, determine the primary (or secondary) category ID for a similar item in the results, and then submit the request again with that category ID.
- Use another call like GetCategories or GetSuggestedCategories to find a valid category ID.

You must pass ProductID, Query, ExternalProductID, or CategoryID in the request. CategoryID can be used in combination with Query. It is not allowed with ExternalProductID or ProductID. If you pass CategoryID without Query, it must specify a leaf category ID. That is, it cannot be a meta-category ID (e.g., 267 for "Books").

Restricts listings to return only items that support the specified nonprofit charity organization. Retrieve CharityID values with GetCharities.

Limits the results to items ending within a time range. EndTimeFrom specifies the beginning of the time range. Specify a time in the future. If you specify a time in the past, the current time is used. If specified, EndTimeTo must also be specified (with a value equal to or later than EndTimeFrom). Express the time in GMT. Cannot be used with the ModTimeFrom filter.

Limits the results to items ending within a time range. EndTimeTo specifies the end of the time range. If specified, EndTimeFrom must also be specified (with a value equal to or earlier than EndTimeTo). Express the time in GMT. Cannot be used with the ModTimeFrom filter.

Expands search results when a small result set is returned. For example, on the US site (site ID 0), if a search would normally result in fewer than 10 items, then if you specify true for this tag, the search results are expanded. Specifically, the search returns items (if there are matches) in one or more of the following containers: InternationalExpansionArray (for items available from international sellers), FilterRemovedExpansionArray (items that would be returned if filters such as PriceRangeFilter are removed), StoreExpansionArray (for items listed in the Store Inventory Format), and AllCategoriesExpansionArray (for items available if category filters are removed). Maximum number of items returned in each expansion container is 6 to 10.

An exclusive query to only retrieve items that were listed with the specified ISBN or UPC. Only applicable for items that were listed with Pre-filled Item Information in media categories (Books, Music, DVDs and Movies, and Video Games). You must pass ProductID, Query, ExternalProductID, or CategoryID in the request. If you use ExternalProductID, do not use Query, ProductID, or CategoryID.

If true, only items with free shipping for the user's location are returned. The user's location is determined from the site ID specified in the request. If false, no filtering is done via this attribute. A listing is not considered a free shipping listing if it requires insurance or requires pick up or requires a shipping surcharge.

Optional tag that currently accepts only one value for this call: Coarse. Other values return an error. If you specify Coarse, the call returns the fields shown in the GranularityLevel table plus any tags resulting from the detail level you specify. Controls the fields to return for each listing (not the set of listings that match the query).

You can group Best Match search results by category by specifying BestMatchCategoryGroup in the Order field. When you specify BestMatchCategoryGroup in the Order field, you can also specify Group.MaxEntriesPerGroup and/or Group.MaxGroups. When you specify BestMatchCategoryGroup in the Order field, there will be fewer results returned because Best Matches in lower-level (leaf) categories and higher-level categories are taken into account. There is not a direct correlation between the number of items returned in a regular sort (or in a BestMatch sort) and the number of items that are returned when you specify BestMatchCategoryGroup in the Order field. When you specify BestMatchCategoryGroup in the Order field, not more than 2 pages of results are returned. See also the GroupCategoryID element in ItemType.

If true, each item in the result set can also include the item condition (e.g., New or Used) in the ItemSpecific property of the response. An item only includes the condition in the response if the seller filled in the Item Condition in the Item Specifics section of the listing. (That is, the condition is not returned if the seller only put the word "New" in the listing's title.)

Controls the details to return for each listing (not the set of listings that match the query).

To control whether to retrieve only new or used items, see ItemCondition (or SearchRequest).

If true, each item in the result set also includes information about the seller's feedback. Controls the details to return for each listing (not the set of listings that match the query).
For GetSearchResults, if set to true will also return the seller's User ID.

When passed with a value of true, limits the results to Get It Fast listings.

Limits the results to new or used items, plus items that have no condition specified.

Matches the new or used condition that the seller specified in the Item Specifics section of the listing. (That is, this won't specifically match on items where the seller only put the word "New" in the listing's title.)

Only applicable to sites and categories that support a sitewide (global) item condition. For example, the US site does not currently support this. See GetCategory2CS. To search for the item condition on the US site, use a product finder instead (see SearchRequest).

Filters items based on the ListingType set for the items. If ItemTypeFilter is not specified (or if the AllItemTypes value of ItemTypeFilter is specified), all listing types can be returned unless another relevant filter is specified. You cannot use GetSearchResults to search eBay Express.

Include local items in returning results near this postal code. This postal code is the basis for local search.

Limits the results to only those listings for which Item.LotSize is 2 or greater.

The maximum number of related keywords to be retrieved. Use this field if you want the search results to include recommended keywords (that is, keywords matching one or more of the original keywords) in a RelatedSearchKeywordArray container. A value of 0 (the default) means no related search information is processed.

Limits the results to active items whose status has changed since the specified time. Specify a time in the past. Time must be in GMT. Cannot be used with the EndTime filters.

Limits the results based on each item's eligibility to appear on the mobile.de site. If false, excludes eligible items from search results. If true, queries for eligible items only. If not specified, the search results are not affected. Only applicable for items listed on the eBay Germany site (site ID 77) in subcategories of mobile.de search-enabled categories.

Specifies the order in which listings are returned in a result set. Listings may be sorted by end time, start time, and in other ways listed in the SearchSortOrderCodeType. Controls the way the listings are organized in the response (not the details to return for each listing). For most sites, the default sort order is by items ending soonest. Store Inventory listings are usually returned after other listing types, regardless of the sort order.

Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call and which page of data to return. Controls the way the listings are organized in the response (not the details to return for each listing).

Limits the results to items that accept a specific payment method or methods.

Limits the result set to just those items where the price is within the specified range. The PriceRangeFilterType includes a minimum and a maximum price.

An exclusive query to retrieve items that were listed with the specified eBay catalog product. You must pass ProductID, Query, ExternalProductID, or CategoryID in the request. If you use ProductID, do not use Query, ExternalProductID, or CategoryID.

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.

Limits the result set to just those items whose location is within a specified distance of a postal code. The ProximitySearchType includes a maximum distance and a postal code.

Limits the results to listings that offer a certain number of items matching the query. If Lot is also specified, then Quantity is the number of lots multiplied by the number of objects in each lot. Use QuantityOperator to specify that you are seeking listings with quantities greater than, equal to, or less than Quantity.

Limits the results to listings with quantities greater than, equal to, or less than Quantity. Controls the set of listings to return (not the details to return for each listing).

A query that specifies a search string. The search string consists of one or more keywords to search for in the listing title and/or description. The words "and" and "or" are treated like any other word. Only use "and", "or", or "the" if you are searching for listings containing these words. You can use AND or OR logic by including certain modifiers. Wildcards (e.g., *) are also supported. Be careful when using spaces before or after modifiers and wildcards (+, -, or *). See the eBay Web Services Guide for a list of valid modifiers and examples. Query is not applicable in combination with ExternalProductID or ProductID.

Secondary search criterion that checks item descriptions for keywords that match the query, limits the search results to only charity items, limits the result set to those items with PayPal as a payment method, and/or provides other criteria to refine the search.

Limits the result set to just those items that meet location criteria: listed in a specified eBay site, location where the seller has the item, location from which the user is searching, and/or items listed with a specified currency. You cannot use GetSearchResults to search eBay Express.

A query consisting of a set of attributes (Item Specifics). Use this kind of query to search against the Item Specifics in listings (e.g., to search for a particular shoe size). If the query includes multiple attributes, the search engine will apply "AND" logic to the query and narrow the results. Use GetProductFinder to determine the list of valid attributes and how many are permitted for the specified characteristic set. Retrieves items along with any buying guide details that are associated with the specified product finder. Applicable in combination with the Query argument. Cannot be used in combination with ProductID or ExternalProductID.

If you are searching for tickets, see TicketFinder instead.

Limits the listings in the result set based on whether they are in the Gallery. The choices are items in the Gallery or Gallery and non-Gallery items.

Limits the results to those of a particular seller business type such as commercial or private.

Limits the result set to just those items that meet criteria related to eBay Stores sellers and eBay Stores. Use this to retrieve items listed in a particular seller's eBay Store or in all store sellers' eBay Stores. This filter always causes item description text to be searched with the string specified in the Query field. That is, StoreSearchFilter forces the type of search that would have occurred if you had specified SearchInDescription in the SearchFlags field.

Searches for event ticket listings only. If specified, this cannot be empty. For example, to search for all tickets (with no event, date, city, or quantity constraints), specify EventType with a value of Any. If specified, Query is optional. Query is useful when the user wants to search for a particular event name (like "eric clapton") or a venue that might be included in the listing title. If TicketFinder and SearchRequest are both specified in the same request, SearchRequest is ignored.

Retrieves the total quantity of matching items, without returning the item data. See PaginationResult.TotalNumberOfEntries in the response. If TotalOnly and Categories.CategoriesOnly are both specified in the request and their values are inconsistent with each other, TotalOnly overrides Categories.CategoriesOnly. That is, if TotalOnly is true and Categories.CategoriesOnly is false, the results include matching categories but no item data or buying guides. If TotalOnly is false and Categories.CategoriesOnly is true, the results include matching categories, item data, and buying guides. If TotalOnly is not specified, it has no logical effect.

Limits the the result set to just those items listed by one or more specified sellers or those items not listed by the one or more specified sellers.