Skip to main content

browse API

Browse API Release Notes Archive

This archive document contains information about releases that go back longer than six months. For current releases, see Browse API Release Notes.

Release Version

Release Date

Description of Release

v1_beta.36.0

2020-10-07

  • The getItems method has been added to the Browse API. Multiple item IDs or item group IDs can now be searched at the same time
  • The getItem method will show itemWebUrl and itemAffiliateWebUrl for the request fieldgroups="COMPACT"

v1_beta.35.0

2020-10-01

  • Added a new error message to the search and searchByImage methods
  • Added the charity_ids and fieldgroups URI parameters to the searchByImage method
  • Removed the epid URI parameter from the searchByImage method

v1_beta_34.1

2020-09-22

Added support for the Singapore (SG) marketplace to the item_summary resource

v1_beta.34.0

2020-08-10

  • Added a new restriction to sellers:filter for the search and searchByImage methods
  • Added a new error message to the search and searchByImage methods

v1_beta.33.0

2020-06-09

  • Added a new paymentMethods container to the response of the Item resource methods
  • Added a new conditionDescription field to the response of the Item resource methods

v1_beta.32.0

2020-05-05

  • Added support for newlyListed to the sort query parameter in the search and searchByImage resource methods
  • Added new warning messages to the item resource methods
  • Added a new warnings container to the getItemsByItemGroup resource method

v1_beta.31.0

2020-04-09

Enabled the itemEndDate field to be returned in the COMPACTgetItem response

v1_beta.30.0

2020-04-09

  • Added an availableCoupons object container to the response of the item resource methods
  • Added an availableCoupons boolean flag to the response of the search and searchByImage resource methods

v1_beta.29.0

2020-03-26

  • Added support for legacyItemId to the item and search resource methods
  • Added support for autoCorrections to the search resource method

v1_beta.28.0

2020-02-10

Added support for the Goods and Services tax to the item resource methods

v1_beta.27.0

2020-01-13

  • Added fields for lot size, eBay Guaranteed Delivery, and qualified programs, such as eBay Plus,
  • Added a GST (guaranteed delivery tax) enumeration value to TaxType
  • Added a filter for Guaranteed Delivery items
  • Added new error messages

v1_beta.26.0

2019-10-11

  • Added support for Best Offer and pricing treatment to the item resource methods
  • Anonymized the postal code returned in the itemLocation.postalCode field
v1_beta.25.0

2019-09-17

Added the eligibleForInlineCheckout field to the fieldgroupsCOMPACT response in the getItem method

v1_beta.24.0

2019-09-09

Added a field that indicates whether the item can be purchased using the Buy Order API

v1_beta.23.0

2019-08-12

Added support for Best Offer and pricing treatment to search and searchByImage methods

v1_beta.22.0

2019-07-15

Added fields to support eBay's Global Shipping Program

v1_beta.21.0

2019-04-30

Added support for searching for items based on compatibility

v1_beta.20.0

2019-03-13

Added the inferredEpid field

v1_beta.19.0

2019-03-07

  • Added a method to check product and item compatibility
  • Added the ebayCollectAndRemitTax field

v1_beta.18.0

2019-02-12

Added support for searching and filtering for charity items on the US and GB marketplaces

v1_beta.17.0

2018-11-06

Changed Seller type in the item resource

v1_beta.16.0

2018-10-17

Added auction bidding fields to the getItem and getItemByLegacyId methods

v1_beta.15.0

2018-07-30

Experimental Release Added search_by_image resource (Note: This is an Experimental Release.)

v1_beta.14.0

2018-07-24

Experimental Release Added shopping_cart resource (Note: This is an Experimental Release.)

v1_beta.13.0

2018-07-19

The search method now returns the itemLocation.city field when fieldgroups is set to EXTENDED.

v1_beta.12.0

2018-07-02

  • Added shortDescription to the search method response
  • Added EXTENDED to fieldgroups, which causes the shortDescription to be returned

v1_beta.11.0

2018-03-29

Added the enabledForGuestCheckout field to the getItem, getItemsByItemGroup, and getLegacyItem methods

v1_beta.36.0

The following sections describe the changes made in this release.

Added getItems method and bulk item search functionality

The getItems method has been added to the Browse API. Multiple item ids and item group ids can now be queried for at the same time. This functionality impacts the getItem and getItems methods.

The getItem method will now show the itemWebUrl and itemAffiliateWebUrl fields for the request fieldgroups="COMPACT".

Added new error messages

Error ID

Message

11012 The specified item ids are invalid, or the format of the specified values are invalid.
11013 The specified group ids are invalid, or the format of the specified values are invalid.
11014 An item_IDs and an item_group_IDs list cannot be used at same time. Please use only one of these lists.
11015 The maximum number of item IDs has been exceeded. Please reduce the number of item IDs to {maxAllowedItemIds} or less.
11016 The maximum number of item group IDs has been exceeded. Please reduce the number of item group IDs to {maxAllowedItemGroupIds} or less.
11017 An item_ids or an item_group_ids list is required. Please use one of these lists.

v1_beta.35.0

The following sections describe the changes made in this release.

Added a new error message

The following error message was added to the search and searchbyimage methods:

Error ID

Message

12030 The number of categories in the request has exceeded the limit. Please reduce the number of categories to {allowedMaxCategories} or less.

Added two new URI parameters

The following URI parameters were added to the searchbyimage method in this release: 

URI Parameter

Description

charity_ids This parameter is used to limit the search results to only items associated with the specified charity.
fieldgroups This parameter is used to define the values that are returned in the search response.

Removed a URI parameter

Support for the epid URI parameter was removed from the searchbyimage method in this release.

Note: The epid URI parameter is still supported by the search method.

v1_beta_34.1

Support for the Singapore (SG) marketplace has been added to the item_summary resource in the Browse API.

v1_beta.34.0

Added restriction to sellers:filter for search and searchbyimage methods

A new restriction for the sellers API filter was added. This restriction limits the number of sellers returned in a search to a maximum of 250.

This filter restriction affects the search and searchbyimage methods.

Added new error message

The following error message was added to the search and searchbyimage methods:

Error ID

Message

12029 The number of sellers in the filter has exceeded the limit. Please reduce the number of sellers to 250 or fewer.

v1_beta.33.0

The following sections describe the changes made in this release.

Added paymentMethods response container

A new paymentMethods container was added to the responses of the getItem, getItemByLegacyID, and getItemsByItemGroup resource methods. This new container presents the payment methods for the item, including the payment method types, brands, and instructions for the buyer.

Added conditionDescription response field

A new conditionDescription field was added to the responses of the getItem, getItemByLegacyID, and getItemsByItemGroup resource methods. This new field presents a full text description and details for the condition of the item.

Note: This field elaborates on the value specified in the condition field, which provides only a short text description for the condition of the item (such as New or Used).

v1_beta.32.0

The following sections describe the changes made in this release.

Added newlyListed sort query parameter

Support for newlyListed was added to the sort query parameter in the search and searchByImage resource methods. This query parameter sorts the result set by listing date, showing the most recently listed item first.

Added new warning messages

The following warning messages were added to the getItem, getItemByLegacyID, and getItemsByItemGroup resource methods:

Warning ID

Message

11508 This seller is currently away. If you make a purchase, please allow additional time for your order to be processed.
11509 This seller is currently away until {sellerReturnDate}. If you make a purchase, please allow additional time for your order to be processed.

Added new warnings container

A new warnings container was added to the getItemsByItemGroup resource method, which contains all of the warning messages for the response.

v1_beta.31.0

The following section describes the change made in this release.

itemEndDate field added to the COMPACT response of getItem

Enabled the itemEndDate field to be returned in the COMPACTgetItem response. To enable a COMPACT response in getItem, the fieldgroups query parameter is used and set to COMPACT (e.g. ?fieldgroups=COMPACT).

v1_beta.30.0

The following sections describe the changes made in this release.

Added availableCoupons container

A new availableCoupons object container was added to the response of the following item operations:

  • getItem
  • getItemByLegacyId
  • getItemByItemGroup

The availableCoupons container returns a list of available coupons for an item.

Added availableCoupons boolean flag

A new availableCoupons boolean flag was added to the itemSummaries object container in the response of the search and searchByImage operations. The itemSummaries.availableCoupons boolean value indicates whether coupons are available for the item.

v1_beta.29.0

The following sections describe the changes made in this release.

Added legacyItemId support

The legacyItemId response was added to the following item operations:

  • getItem
  • getItemByLegacyId
  • getItemByItemGroup

The legacyItemId response was added to the following search operations:

  • search
  • searchByImage

Added autoCorrections support

A new auto_correct query parameter was added to the search and searchByImage operations. The responses for these operations now return an optional autoCorrections container when the auto_correct query parameter is passed.

v1_beta.28.0

The following change has been made to the item resource method.

Support was added for the Goods and Services tax.

An enumeration value of GST may now be returned as a tax type under the taxes.taxType field in the response of the three Get Item operations. The Goods and Services tax is only applicable to the eBay Australia marketplace. To support this change, the GST value has been added the TaxType enumeration type.

v1_beta.27.0

The following sections describe the changes made in this release.

item_summary and search_by_image resource changes

The following has been added to all the methods in the item_summary and search_by_image resources.

Field/Filter Name

Description

ItemSummary.qualifiedPrograms

An array of the qualified programs available for the item, such as EBAY_PLUS.

eBay Plus is a premium account option for buyers, which provides benefits such as fast free domestic shipping and free returns on selected items. Top-Rated eBay sellers must opt in to eBay Plus to be able to offer the program on qualifying listings. Sellers must commit to next-day delivery of those items.

Note: eBay Plus is available only to buyers in Germany, Austria, and Australia marketplaces.

ShippingOptionSummary.guaranteedDelivery A boolean the indicates if the item qualifies for eBay's Global Shipping Program.

guaranteedDeliveryInDays filter

Only items that can be delivered to the buyer within the specified number of days are returned. See Buy API Field Filters for details.

 

Error ID

Message

12507 To filter by 'guaranteedDeliveryInDays', you must include 'deliveryCountry'.
12508 To filter by 'guaranteedDeliveryInDays', you must include 'deliveryPostalCode' for the 'deliveryCountry'.
12509 The 'guaranteedDeliveryInDays' value {guaranteedDeliveryInDays} is invalid for 'deliveryCountry' value {deliveryCountry}. Valid values for 'guaranteedDeliveryInDays' for {deliveryCountry} must be in the range of {rangeLowerBound} to {rangeUpperBound} inclusive.
12510 The 'guaranteedDeliveryInDays' filter is not supported for the marketplace {marketplaceId}. Valid marketplaces are: {validMarketplaces}

 

item resource changes

The following has been added to all the methods in the item resource.

Field/Enum Name

Description

Item.lotSize The number of items in a lot. In other words, a lot size is the number of items that are being sold together.

A lot is a set of two or more items included in a single listing that must be purchased together in a single order line item. All the items in the lot are the same but there can be multiple items in a single lot, such as the package of batteries shown in the example below.

ItemLot DefinitionLot Size
A package of 24 AA batteriesA box of 10 packages10
A P235/75-15 Goodyear tire 4 tires 4
Fashion Jewelry Rings Package of 100 assorted rings 100

Note: Lots are not supported in all categories.

Item.qualifiedPrograms An array of the qualified programs available for the item, such as EBAY_PLUS.

eBay Plus is a premium account option for buyers, which provides benefits such as fast free domestic shipping and free returns on selected items. Top-Rated eBay sellers must opt in to eBay Plus to be able to offer the program on qualifying listings. Sellers must commit to next-day delivery of those items.

Note: eBay Plus is available only to buyers in Germany, Austria, and Australia marketplaces.

ShippingOption.guaranteedDelivery A boolean the indicates if the item qualifies for eBay's Global Shipping Program.
TaxType enum GST: New enumeration value that indicates the tax is a Global Shipping Program tax.

 

v1_beta.26.0

The following changes have been made to the item resource methods.

Added Best Offer

BEST_OFFER is now returned in the buyingOptions field in the item resource methods.

Added a value to PriceDisplayConditionEnum

Added the following enumeration value to the PriceDisplayConditionEnum type in the item resource methods.

ONLY_SHOW_ON_REQUEST: Indicates the minimum advertised price can be shown only when the buyer requests to see it.

Added pricing treatment elements

The following changes have been made to the item resource methods to support price discounts:

  • Added the MarketingPrice.priceTreatment field, which returns an enumeration value that represents the pricing treatment (discount) that was applied to the price of the item. Note: The pricing treatment affects the way and where the discounted price can be displayed.
  • Added the PriceTreatmentEnum type which defines the following values that represent a discount type.

    Enum Value

    Description

    MINIMUM_ADVERTISED_PRICE Indicates the price treatment is Minimum Advertised Price (MAP). This is the lowest price the item is allowed to be advertised/shown at and can be shown only after the item has been added to the cart. For details about when in the buying flow the item's price can appear, see priceDisplayConditionEnum.
    LIST_PRICE Indicates the price treatment is Strike through pricing (STP). For this treatment, the list price, which is crossed off (struck through) and discounted price are shown. List price is the price a seller recently listed the item for sale or sold the item for.
    MARKDOWN Indicates the price treatment is a markdown. The price before the markdown (Was price) is shown as well as the discount price. This item is part of a seller promotion and has an end date.

Anonymized postal Code in itemLocation field

Sellers set a postal code (or zip code in US) for items when they are listed. The postal code is used for calculating proximity searches. In all the Browse API methods It has been anonymized when returned in itemLocation.postalCode via the API.

 

v1_beta.25.0

Added the eligibleForInlineCheckout field to the fieldgroups COMPACT response of the getItem method.

Query Parameter

Type

Description

eligibleForInlineCheckout Boolean This field indicates if the item can be purchased using the Order API.

v1_beta.24.0

Added the following field to the getItem and getItemByLegacyId methods.

Field Name

Type

Description

eligibleForInlineCheckout

boolean

This field indicates if the item can be purchased using the Buy Order API.
  • If the value is true, this indicates that the item can be purchased using the Order API.
  • If the value is false, this indicates that the item cannot be purchased using the Order API and must be purchased on the eBay site.

v1_beta.23.0

The following changes have been made to the search and searchByImage methods.

Added Best Offer

BEST_OFFER is now returned in the itemSummaries.buyingOptions field. It has also been added to the buyingOptions filter, which gives you the ability to return only items that have Best Offer. For details about this filter, see the buyingOptions filter documentation.

Added a value to PriceDisplayConditionEnum

Added the following enumeration value to the PriceDisplayConditionEnum type.

ONLY_SHOW_ON_REQUEST: Indicates the minimum advertised price can be shown only when the buyer requests to see it.

Added pricing treatment elements

The following changes have been made to support price discounts:

  • Added the MarketingPrice.priceTreatment field, which returns an enumeration value that represents the pricing treatment (discount) that was applied to the price of the item. Note: The pricing treatment affects the way and where the discounted price can be displayed.
  • Added the PriceTreatmentEnum type which defines the following values that represent a discount type.

    Enum Value

    Description

    MINIMUM_ADVERTISED_PRICE Indicates the price treatment is Minimum Advertised Price (MAP). This is the lowest price the item is allowed to be advertised/shown at and can be shown only after the item has been added to the cart. For details about when in the buying flow the item's price can appear, see priceDisplayConditionEnum.
    LIST_PRICE Indicates the price treatment is Strike through pricing (STP). For this treatment, the list price, which is crossed off (struck through) and discounted price are shown. List price is the price a seller recently listed the item for sale or sold the item for.
    MARKDOWN Indicates the price treatment is a markdown. The price before the markdown (Was price) is shown as well as the discount price. This item is part of a seller promotion and has an end date.

v1_beta.22.0

Added the following fields that return eBay's Global Shipping Program shipping option and the import charges associated with this shipping option.

Field Name

Description

shippingOption.fulfilledThrough If the item is being shipped by eBay's Global Shipping Program, this field returns GLOBAL_SHIPPING. Otherwise this field is null.

Valid Values: GLOBAL_SHIPPING
shippingOption.importCharges The Global Shipping Program import charges for this item.

v1_beta.21.0

This release enables you to use the search method to search for items that are compatible with a specific product. You must submit a keyword, a fitment supported category, and the attributes used to define a specific product.

Note: The only products supported are cars, trucks, and motorcycles.

New URI parameter

The compatibility_filter parameter was added. You use this field to specify the attributes that define a specific product. The service returns items matching the keyword or keyword and product attributes. For example, if the keyword is brakes and compatibility_filter=Year:2018;Make:Honda, the items returned are items with brakes, 2018, or Honda in the title.

The service then uses the product attributes to determine if the item is compatible. The service returns the attributes that are compatible and the CompatibilityMatchEnum value that indicates how well the item matches the attributes. For details, see Check compatibility in the Buy Integration Guide.

New compatibility response fields

The following compatibility response fields were added.

Field

Description

itemSummaries.compatibilityMatchEnum An enumerated value that represent how well the item matches the compatibility filter properties. The values returned are:
  • EXACT - Indicates the item is compatible with all the compatibility properties submitted.
  • POSSIBLE - Indicates the item could fit the product. To further check for compatibility, you can either add more compatibility properties or view the details of the item.
itemSummaries.compatibilityProperties.localizedName The name of the product attribute that as been translated to the language of the site.
itemSummaries.compatibilityProperties.name The name of the product attribute, such as Make, Model, Year, etc.
itemSummaries.compatibilityProperties.value The value for the name attribute, such as BMW, R1200GS, 2011, etc.

New error messages

Error ID

Message

12503 There is no compatibility information found either because there is no compatibility results or the data provided in the compatibility_filter is invalid or insufficient.

12504

You must provide a category ID that supports fitment.
12505 The following compatibility attributes in the request are not supported: {attributes}.
12506 This category ID does not support fitment.

Testing in Sandbox

Testing in Sandbox is only supported using mock data. See Testing search in the Sandbox for details.

v1_beta.20.0

The inferredEpid field was added to the getItem, getItemByLegacyId, getItemsByItemGroup methods. This field returns the ePID (eBay Product ID of a product from the eBay product catalog) for the item, which has been programmatically determined by eBay using the item's title, aspects, and other data. If the seller provided an ePID for the item, the seller's value is returned in the epid field.

Note: This field is returned only for authorized Partners.

v1_beta.19.0

The following changes have been made to the Browse API.

Added a new method

Added the checkCompatibility method to the item resource. This method checks if a product is compatible with the specified item. This method can check the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay. To check for vehichle/part compatibility. you would pass in the item ID of a part as a URI parameter and specify all the attributes used to define a specific car in the compatibilityProperties container. You must also pass in EBAY_US in the X-EBAY-C-MARKETPLACE-ID request header.

If the call is successful, the response will be COMPATIBLE, NOT_COMPATIBLE, or UNDETERMINED.

URI

POST /item/{item_id}/check_compatibility

Request payload

{
  "compatibilityProperties": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

Response

{
    "compatibilityStatus": "COMPATIBLE"
}

For an example, see the Samples section of the call reference.

Added new error messages

The following new error messages have been added.

Error ID

Message

11503 The request is either empty or incomplete. For help, see the documentation for this call.
11505 The item is not valid for compatibility validation.
11506 The 'name' {compatibilityNames} appears more than once in the request.
11507 The following name(s) in the request are not supported {attributes}.

 

Added the ebayCollectAndRemitTax field

The ebayCollectAndRemitTax field is only returned if true, and indicates that eBay will collect tax (sales tax, Goods and Services tax, or VAT) for at least one line item in the order, and remit the tax to the taxing authority of the buyer's residence.

v1_beta.18.0

The following changes have been made to the Browse API.

Added searching for charity items capability

Added the ability to search for and filter for items associated with the specified charity. eBay charities are added to eBay through the PayPal Giving Fund. After the charity is on eBay they can be identified by their charity's registration ID, also known as the Employer Identification Number (EIN). For additional information, see eBay for Charity.

Note: This is supported only on the US and GB marketplaces.

Added URI parameters

The charity_ids URI parameter has been added to the search method. This parameter is a comma separated list of charity IDs. This field limits the results to only items associated with the specified charity.

For example, charity_ids=13-1788491,300108469

Added a charity filter

The charityOnly filter has been added to enable you to limit the items returned to only items associated with a charity. For example:

/buy/browse/v1/item_summary?q=pencil&filter=charityOnly:true

v1_beta.17.0

The following changes have been made to the Browse API.

Added a new enum value

The following enumeration value was added to the priceDisplayCondition type. These enumeration values indicate when the minimum advertised price (MAP) for an item can appear in the buying flow.

ONLY_SHOW_DURING_CHECKOUT - Indicates the minimum advertised price of the item can be shown only during checkout. For example, on the "buy" page.

Changed Seller type in item resource

The item_summary and item resource both contained a Seller type. But these types were not identical, which resulted in a Seller and Seller_0 type. To fix this, the Seller type in the item resource was changed to reference the new sellerDetails type.

Note: This is not a backwards incompatible change.

v1_beta.16.0

The following fields were added to the getItem and getItemByLegacyId methods. These fields return general (not specific to any bidder) bidding information for action items.

New Field

Field Description

reservePriceMet This is a boolean that indicates if the reserve price of the item has been met. A reserve price is set by the seller and is the minimum amount the seller is willing to sell the item for. If the highest bid is not equal to or higher than the reserve price when the auction ends, the listing ends and the item is not sold.

Note: This is returned only for auctions that have a reserve price.
minimumPriceToBid The minimum price of the next bid, which means to place a bid it must to equal to or greater than this amount. If the auction hasn't received any bids, the minimum bid price is the same as the starting bid. Otherwise, the minimum bid price is equal to the current bid plus the bid increment. For details about bid increments, see Automatic bidding.

v1_beta.15.0

The search_by_image resource has been added to the Browse API, which lets you search for items by an image. (Note: This is an Experimental Release.)

You pass in a Base64 image ID in the request payload and can refine the search results by category, eBay product ID (ePID), or GTIN, or a combination of these using URI parameters.

v1_beta.14.0

The shopping_cart resource has been added to the Browse API, which lets you add, remove, and change the quantity of items in an eBay member's cart. (Note: This is an Experimental Release.)

This resource has the following methods:

  • addItem - This method creates a cart for the eBay member if it doesn't exist and adds items to that cart. To use this method, you must submit a RESTful item ID and the quantity of the item.
  • getShoppingCart - This method retrieves the contents of the eBay member's cart on eBay. There is no URI parameters or request payload. This method returns the summary details of all the items in the cart; items added to the cart while on ebay.com as well as items added to the cart using the Browse API.
  • removeItem - This method removes a specific item from the eBay member's cart on eBay. You specify the ID of the item in the cart (cartItemId) you want to remove.
  • updateQuantity - This method updates the quantity value of a specific item in the cart. You specify the ID of the item in the cart (cartItemId) and the new value for the quantity.

v1_beta.13.0

The search method now populates the itemLocation.city field when fieldgroups is set to EXTENDED. This lets you filter the result set by a specific city.

v1_beta.12.0

Added the shortDescription field to the search method response. This field returns a text string that is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.). Sometimes the title doesn't give enough information but the description is too big. Surfacing the shortDescription can often provide buyers with the additional information that could help them make a buying decision.

For example:

"title": "Petrel U42W FPV Drone RC Quadcopter w/HD Camera Live Video One Key Off / Landing",
"shortDescription": "1 U42W Quadcopter. Syma X5SW-V3 Wifi FPV RC Drone Quadcopter 2.4Ghz 6-Axis Gyro with Headless Mode. Syma X20 Pocket Drone 2.4Ghz Mini RC Quadcopter Headless Mode Altitude Hold. One Key Take Off / Landing function: allow beginner to easy to fly the drone without any skill.",


Restriction: This field is returned only when fieldgroups = EXTENDED.

v1_beta.11.0

The enabledForGuestCheckout field was added to the getItem, getItemsByItemGroup, and getLegacyItem methods.

New Field

Field Description

enabledForGuestCheckout Indicates if the item can be purchased using Guest Checkout in the Order API. You can use this flag to exclude items from your inventory that are not eligible for Guest Checkout, such as gift cards.