Browse API Release Notes

1.20.4

The following changes have been made in this release.

New error code

The following error code has been added to the search and searchByImage methods to handle malformed URL encoding in requests:

Code	Message
12521	The request contains malformed URL encoding. Please check that all percent-encoded characters (%) are properly formatted.

1.20.3

The following changes have been made in this release.

Schema changes

The charityTerms container can now be returned for the getItems, getItembyLegacyId, and getItemsByGroupId methods. This container returns any applicable charity information for the specified item, such as the charityOrgId, name, donationPercentage, website, and logoImage. This field is only returned when setting fieldgroups to CHARITY_DETAILS.

1.20.2

The following changes have been made in this release.

Schema changes

The itemOriginDate field has been added to the response of the search and searchByImage methods. This field returns the initial date and time when a listing was first made available. Note that this value can be different than the itemCreationDate field, which returns the date and time a listing was created.

1.20.1

The following changes have been made in this release.

Schema changes

The contactUrl field has been added to the CompanyAddress and ResponsiblePerson types of the getItem, getItems, getItemByLegacyId, and getItemsByItemGroup methods. This field returns the electronic contact information of a manufacturer and/or responsible person associated with a product (if GPSR information is provided on a listing).

1.20.0

The following changes have been made in this release.

Schema changes

The following schema changes have been made:

• The quantity_for_shipping_estimate query parameter has been added to the getItem, getItems, getItemByLegacyId, and getItemsByItemGroup methods. This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the response.
• The immediatePay response field has been added to the getItem, getItems, getItemByLegacyId, and getItemsByItemGroup methods. This boolean indicates that the seller requires immediate payment from the buyer when purchasing an item.

New error code and warning

The following error code and warning were added to the getItem, getItems, getItemByLegacyId, and getItemsByItemGroup methods:

• A new error code 11019 has been added with the following description: "The quantity_for_shipping_estimate value {quantityForShippingEstimate} is invalid. Please enter a positive value."
• A new warning 11510 has been added with the following description: "There was a problem calculating the shipping cost. Please try again."

1.19.9

The following changes have been made in this release.

This release adds the return of the actual remaining quantity for a listing through the estimatedRemainingQuantity field. This field was added to the EstimatedAvailability type in the getItem, getItems, getItemByLegacyId, and getItemsByItemGroup methods.

1.19.8

The following changes have been made in this release.

In preparation for new legal requirements by the European Union taking effect on December 13th, 2024, this release adds support for General Product Safety Regulation (GPSR) information.

Schema changes

To support the upcoming regulatory requirements, schema changes have been made to support GPSR information. The following types, and their associated fields and enumerated values, have been added to the getItem, getItemByLegacyId, and getItemsByItemGroup methods to provide seller provided GPSR information:

• CompanyAddress type (in the manufacturer container): This type is used to provide contact information for the manufacturer of the product.
• ResponsiblePerson (in the responsiblePersons container): This type provides information, such as name and contact details, for an EU-based Responsible Person or entity, associated with the product.
• ProductSafetyLabels (in the productSafetyLabels container): This type contains the ProductSafetyLabelPictogram type and ProductSafetyLabelStatement type, and provides seller provided product safety pictograms and statements for the listing.

1.19.7

The following changes have been made in this release.

Expanded support for affiliate links

Affiliate links are now supported for the Polish Marketplace (EBAY_PL).

1.19.6

The following changes have been made in this release.

Expanded values for itemLocationRegion filter

The itemLocationRegion filter has been expanded to include the following values:

• ASIA
• BORDER_COUNTRIES
• CONTINENTAL_EUROPE
• EUROPEAN_UNION
• NORTH_AMERICA
• UK_AND_IRELAND

New error code

A new error code 12517 has been added in the search method with the following description: "The 'itemLocationRegion' filter value is not supported for the marketplace {marketplaceId}. Valid values are: {validRegionValues}."

Expanded supported marketplaces

Belgium (EBAY_BE) has been added as a supported marketplace for the Browse API.

Added Accept-Language header

The Accept-Language header has been added to methods of the Browse API. This header allows users to toggle between supported languages on the Belgian and Canadian marketplaces. For more information on this header, see HTTP request headers.

1.19.5

The following changes have been made in this release.

Added itemLocationRegion filter

The search method now supports the itemLocationRegion filter. This filter allows only items located in a specific region to be returned in the response. The only currently supported value is WORLDWIDE.

New error code

A new error code 12517 has been added in the search method with the following description: "Only one item location filter can be applied at a time. Refer to the API call documentation."

1.19.4

The following changes have been made in this release.

Schema changes

To support new legal requirements by the European Union and the UK to provide Economic Operator information, the following schema changes have been made:

• The following new type has been added to the getItem, getItemByLegacyId, getItems, and getItemsByItemGroup methods:
  
  EconomicOperator: provides required Economic Operator information about the manufacturer and/or supplier of the item.
• The following new field has been added to the SellerLegalInfo type:
  
  economicOperator: Provides required information about the manufacturer and/or supplier of the item.

1.19.3

The following changes have been made in this release.

Expanded marketplace support for auto correction of browse terms

The list of marketplaces that support the auto correction of browse terms has been expanded and now includes:

• Austria
• Australia
• Canada
• Switzerland
• Germany
• Spain
• France
• United Kingdom
• Ireland
• Italy

Schema changes

There are no schema changes associated with this release.

1.19.2

The following changes have been made in this release.

Added the userId field

The userId field can now be returned for the getItems, getItembyLegacyId, and getItemsByGroupId methods. This field provides the unique identifier of a seller across all eBay sites. This value does not change, even when a user changes their username. This field is only returned when setting fieldgroups to ADDITIONAL_SELLER_DETAILS.

Added the ADDITIONAL_SELLER_INFORMATION fieldgroup

A new fieldgroups value ADDITIONAL_SELLER_DETAILS has been added to support this feature. Setting fieldgroups to ADDITIONAL_SELLER_DETAILS adds the userId field to the response.

1.19.1

The following changes have been made in this release.

Added new Error Code

A new error code 12516 has been added in the search method with description "The ‘q’ value is invalid. It must be longer than one character when using the ‘searchInDescription’ filter."

1.19.0

The following changes have been made in this release.

Added the conditionDescriptors field

To support the return of condition descriptor information for applicable items, the following new array has been added to the getItem, getItemByLegacyId, and getItemsByItemGroup method:

• conditionDescriptors: provides additional information about the condition of an item in a structured format.

1.18.4

The following changes have been made in this release.

Schema updates

To support the return of Waste Electrical and Electronic Equipment (WEEE) information, the following new field has been added to the SellerLegalInfo type:

• weeeNumber: the manufacturer number assigned to first distributors of electrical and electronic equipment.

1.18.3

The following changes have been made in this release.

Removed Shopping Cart

The Browse API no longer supports the Shopping Cart, so the shopping_cart resource and methods, addItem, getShoppingCart, removeItem, and updateQuantity, have been removed from the documentation set.

ted value. This value indicates that the item is being shipped through the eBay International Shipping program. This change affects responses for the methods getItem, getItemByLegacyId, and getItemsByItemGroup.

1.18.2

The following changes have been made in this release.

Added the field hazardousMaterialsLabels

The following methods now return the field hazardousMaterialsLabels: getItem, getItemByLegacyId, and getItemsByItemGroup.

The hazardousMaterialsLabels field provides information about hazardous material labels that apply to an item. It includes arrays of two additional fields, hazardPictogram and hazardStatement.

Added the field repairScore

The following methods now return the field repairScore: getItem, getItemByLegacyId, and getItemsByItemGroup.

The repairScore field represents the Repair Index, a value that indicates how easy it is to repair the item. Score values range from 0.1 (hardest to repair) to 10.0 (easiest), always including a single decimal place. Note: Support for this field is currently limited to the France marketplace.

1.18.1

The following changes have been made in this release.

Added error for limit and offset relation condition

Error code 12515 was added to the search and searchByImage methods.

Error ID	Message
12515	The 'offset' value must be either zero or a multiple of the 'limit' value.

1.18.0

The following changes have been made in this release.

categoryName field

Each category object returned by the methods search and searchByImage now includes the field categoryName. Previously, only categoryId was returned.

leafCategoryIds array

Responses for the methods search and searchByImage now include an array of leaf category IDs for each item. An item can have up to two leaf categories. When this is the case, the leaf category IDs are returned in the order primary, secondary.

International Shipping

The field shippingOptions.fulfilledThrough now includes INTERNATIONAL_SHIPPING as a supported enumera

1.17.0

The following changes have been made in this release.

Added categoryIdPath response field to Browse API

The getItem, getItemByLegacyId, getItems, and getItemsByItemGroup methods now return the response field categoryIdPath. This field contains the IDs of every category in the item path, separated by pipe characters, starting with the top level parent category.

For example, if an item belongs to the top level category Home and Garden (category ID 11700), followed by Home Improvement (159907), Heating, Cooling and Air (69197), and Thermostats (115947), the field would return the value: 11700|159907|69197|115947.

1.16.0

The following changes have been made in this release.

CLASSIFIED_AD is added as a buyingOptions value

The string value CLASSIFIED_AD can be applied as a buyingOptions filter for the following methods:

• search
• searchByImage

The string value CLASSIFIED_AD is now returned in the buyingOptions array response for the following methods:

• getItem
• getItemByLegacyId
• getItems
• getItemsByItemGroup
• search
• searchByImage

In addition, the string value CLASSIFIED_AD is now included in the BUYING_OPTIONS_REFINEMENTS fieldgroup and may be returned within the buyingOptionDistributions array for those searches where BUYING_OPTIONS_REFINEMENTS has been set as a fieldgroup.

1.15.0

The following changes have been made in this release.

Added itemCreationDate response field

The following methods now return the itemCreationDate field:

• getItem
• getItemByLegacyId
• getItems
• getItemsByItemGroup

This response field returns a timestamp that indicates the date and time an item listing was created.

1.14.0

The following changes have been made in this release.

Added shippingOptions to the response fields for getItems and to the COMPACT option for getItem

The getItems method now returns the shippingOptions array of fields.

shippingOptions fields are also returned when the parameter "fieldgroups=COMPACT" is passed in with the getItem method.

1.13.0

The following changes have been made in this release.

Added addOnServices response field to Browse Item API

The getItem, getItemByLegacyId, and getItemsByItemGroup methods now return the response field addOnServices, an array of add-on services that apply to an item, such as the eBay Authenticity Guarantee service.

An add-on service may be optional or required and may apply a fee to the item purchase.

1.12.0

The following changes have been made in this release.

Added itemCreationDate and listingMarketplaceId response fields to Browse Item API

The getItem, getItemByLegacyId, getItemsByItemGroup, and search methods now return the response field listingMarketplaceId. This value indicates the eBay marketplace where the item is listed.

The search method now returns the response field itemCreationDate. This value indicates the date and time when the item listing was created.

1.11.0

The following changes have been made in this release.

Added sellerCustomPolicies and ecoParticipationFee response fields to Browse Item API

The getItem, getItemByLegacyId, and getItemsByItemGroup methods now return the response fields sellerCustomPolicies and ecoParticipationFee.

These fields implement support for extended producer responsibility (EPR) laws and regulations that are in effect in some countries.

The sellerCustomPolicies field lists custom policies that a seller applies to a listing. Currently, these policies can be one of the following types:

• PRODUCT_COMPLIANCE: Discloses product information as required for regulatory compliance.
• TAKE_BACK: Describes the seller's legal obligation to take back a previously purchased item when the buyer purchases a new one.

The ecoParticipationFee field defines the amount remitted to an eco organization, applied to the cost of the eventual disposal of the item.

Added five auction-related response fields to Browse Item API

The getItem (COMPACT) and getItems methods now return the following five auction-related response fields:

• bidCount: an integer value that indicates the current number of bids for an auction item.
• currentBidPrice: a string indicating the current highest bid for an auction item.
• minimumPriceToBid: a string indicating the minimum price of the next bid; to place a bid it must be equal to or greater than this amount.
• reservePriceMet: a boolean value indicating if the seller-specified reserve price for an auction item has been met.
• uniqueBidderCount: an integer value indicating the number of different eBay users who have placed one or more bids on an auction item.

1.10.0

The following changes have been made in this release.

Added priorityListing and watchCount response fields to Browse Item API

The getItem, getItems, getItemByLegacyId, and getItemsByItemGroup methods now return the response fields priorityListing and watchCount.

The priorityListing field is a boolean value that indicates whether the listing is a part of a Promoted Listing campaign.

The watchCount field is an integer value that indicates the number of users that have added the item to their watch list.

Added watchCount response field to Browse Search API

The search and searchByImagemethods now return the response field watchCount.

The watchCount field is an integer value that indicates the number of users that have added the item to their watch list.

Added priorityListing filter to Browse Search API

The search method now supports the priorityListing filter parameter. When set to true, this filter returns only items that are a part of a Promoted Listing campaign.

1.9.0

The following changes have been made in this release.

Added Browse API support for AT and CH marketplaces

The Browse API methods item and item_summary are enabled for the Austria (AT) and Switzerland (CH) marketplaces.

1.8.0

The following changes have been made in this release.

Added priorityListing response field

The search method now returns the priorityListing field.

When the value is true, this field indicates that the seller has made the item a priority listing, such as by making it a Promoted Listing. Promoted Listings are available to Above Standard and Top Rated sellers with recent sales activity. For more information, see Promoted Listings.

Added EndingSoonest sort option

Search results can now be sorted by EndingSoonest. This shows items in order of the date and time when the listing ends, starting with the listing with the nearest end date/time.

1.7.0

The following changes have been made in this release.

Added AUTHENTICITY_GUARANTEE to qualifiedPrograms filter

Support for AUTHENTICITY_GUARANTEE was added to the qualifiedPrograms filter URI parameter in the search and searchByImage resource methods. The new filter returns only the items that are qualified for the Authenticity Guarantee program. This program enables third-party authenticators to perform authentication verification inspections on items.

1.6.0

The following changes have been made in this release.

Added itemEndDate response field

The search and searchByImage methods now return the itemEndDate field.

This field represents the date and time up to which the item can be purchased. This value is returned in UTC format, which you can convert into the local time of the buyer.

Added topRatedBuyingExperience response field

The search and searchByImage methods now return the topRatedBuyingExperience field.

This field indicates if the item is a top-rated plus item. There are three benefits of a top-rated plus item: a minimum 30-day money-back return policy, shipping the item in 1 business day with tracking provided, and the added comfort of knowing that this item is from an experienced seller with the highest buyer ratings. See the Top Rated Plus Items and Becoming a Top Rated Seller and qualifying for Top Rated Plus help topics for more information.

Added bidCount filter parameter

Support for a new bidCount filter parameter was added to the search and searchByImage methods.

The new filter returns only auction items with a number of bids that is within the specified range.

1.5.0

The following changes have been made in this release.

Added tyreLabelImageUrl response field

The following methods now return the tyreLabelImageUrl field:

• getItem
• getItemByLegacyId
• getItemsByItemGroup
• search
• searchByImage

This new field provides a URL to the image that shows the information on the tyre label.

1.4.2

The following changes have been made in this release.

Added support for new marketplaces

The item and item_summary resources now support the following marketplaces:

• Ireland (EBAY_IE)
• Netherlands (EBAY_NL)
• Poland (EBAY_PL)

1.4.1

The following changes have been made in this release.

Updated error message 12029 and added error message 12032 for search and searchByImage

The error message for error code 12029 was updated for the search and searchByImage methods:

Old Error Message	New Error Message
The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer.	The maximum number of listings that can be retrieved is 10,000, so your offset value must be less than 10,000. If 10,000 or more listings are matching your search criteria, consider narrowing the scope of your search.

Error code 12032 was added to the search and searchByImage methods:

Error ID	Message
12032	The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer.

1.4.0

The following changes have been made in this release.

Full details on the release (e.g., This release includes new API endpoints for product search, allowing developers to easily query product data.).

1.3.0

The following changes have been made in this release.

Added searchInDescription filter URI parameter

Support for a new searchInDescription filter URI parameter was added to the search resource method.

The new filter returns only the items with titles or descriptions matching the specified keyword.

1.2.0

The following changes have been made in this release.

Added AUTHENTICITY_VERIFICATION to qualifiedPrograms filter

Support for AUTHENTICITY_VERIFICATION was added to the qualifiedPrograms filter URI parameter in the search and searchByImage resource methods. The new filter returns only the items that are qualified for the Authenticity Guarantee program. This program enables third-party authenticators to perform authentication verification inspections on items.

Added AuthenticityVerificationProgram type to item methods

A new AuthenticityVerificationProgram type was added to the item resource methods. The authenticityVerification container is returned for items that are qualified for the Authenticity Guarantee program.

1.1.0

The following changes have been made in this release.

New regionId field added for included and excluded shipping regions.

A new regionId field is now returned for each shipping region that is returned under the regionIncluded and regionExcluded containers for all 'get item' responses. Based on the regionType value, values for the regionId may include two-letter, ISO 3166 country codes, two-letter abbreviations for US states or Canadian provinces, or eBay-defined IDs that represent large geographical regions or special domestic regions within an individual country.

1.0.0

The following changes have been made in this release.

This is the initial general availability (GA) release for the Browse API. This release does not include any functionality or schema changes for the Browse API methods.