browse APIv1_beta.20.0

Browse API Release Notes

Just getting started with the Browse API? See the following documents for details on using this API:

See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.

The API release history

The following table lists recent Browse API releases. For older releases, see the Browse API Release Notes Archive.

Release Version

Release Date

Description of Release

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.10.0

2018-02-12


2017-11-10

The getItem and getLegacyItem methods:
Removed the alternate product IDs from the additionalProductIdentities.productIdentity container.

The getItem and getLegacyItem methods:

  • Added the value PRODUCT to the fieldgroups URI parameter
  • Added product type

All Browse API methods:

  • Added unitPrice and unitPricingMeasure fields

v1_beta.9.0

2017-10-23

Added adultOnly field to the Browse API method responses

Added categoryId field to the getItem and getItemByLegacyId method responses

v1_beta.8.0

2017-09-21

  • Added fieldgroups URI parameter to the getItem method
  • Added new sellerItemRevision field to the getItem method
  • Added new error message to the search method

 

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.

v1_beta.10.0

This section covers the changes that were made in this version of the Browse API. The release on 2017-11-10 added new fields and a new fieldgroups URI parameter. The release on 2018-02-13 changed the contents of the additionalProductIdentities.productIdentity container.

2018-02-13

The additionalProductIdentities.productIdentity container will now return only one UPC and EAN product ID.

Previous Response

New Response

"additionalProductIdentities": [
  {
    "productIdentity": [
      {
        "identifierType": "UPC",
        "identifierValue": "0190198462930"
      },
      {
        "identifierType": "UPC_12",
        "identifierValue": "190198462930"
      },
      ...
      }
    ]
  },
  {
    "productIdentity": [
      {
        "identifierType": "EAN",
        "identifierValue": "0190198462930"
      },
      {
        "identifierType": "EAN_13",
        "identifierValue": "0190198462930"
      ...
      }
    ]
  },
"additionalProductIdentities": [
  {
    "productIdentity": [
      {
        "identifierType": "UPC",
        "identifierValue": "0190198462930"
      }
    ]
  },
  {
    "productIdentity": [
      {
        "identifierType": "EAN",
        "identifierValue": "0190198462930"
      }
    ]
  },

 

2017-11-10

You can now use the getItem and getLegacyItem methods to retrieve product details for an item. The product information is returned in the new product type fields. This type is included in the response when the fieldgroups URI parameter is set to PRODUCT. You can also retrieve the price per unit, which helps buyers accurately compare prices.

Added the PRODUCT fieldgroups value

When you set the URI parameter fieldgroups to PRODUCT, it adds fields to the response containing information about the product associated with the item.

Added Product type

The product type has been added to the getItem and getItemByLegacyId methods. This type is returned only if the URI parameter fieldgroups is set to PRODUCT. The following table lists the fields or types returned in the product type. See the getItem method for details about these new types and fields. For an example of the response, see Get item details and the item product information sample.

product Type Field/Types

Description

product.additionalImages An array of containers with the URLs for the product images that are in addition to the primary image.
product.additionalProductIdentities A product can have more than one identifier value for a product type, such as UPC, EAN, ect. For example, the same product UPC can have an identifier that is 12, 13, or 14 digits.

This container returns an array of all the product identifiers (type/value pairs) associated with the product. These are in addition to the identifiers returned in the mpn and gitn fields.
product.aspectGroups An array of containers for the product aspects. Each group contains the aspect group name and the aspect name/value pairs.
product.brand The brand associated with the product. To identify the product, this is always used along with MPN (manufacturer part number).
product.description The rich description of an eBay product, which might contain HTML.
product.gtins An array of all the possible GTINs values associated with the product. A GTIN is a unique Global Trade Item number of the item. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.
product.image The primary image of the product. This is often a stock photo.
product.mpns An array of all possible MPN values associated with the product. A MPNs is manufacturer part number of the product. To identify the product, this is always used along with brand.
product.title The title of the product.

 

Added unitPrice and unitPricingMeasure fields

The unitPrice and unitPricingMeasure fields were added to all the Browse APIs methods.

New Field

Field Description

unitPrice This is the price per unit for the item. The European Union requires listings for certain types of products to include the price per unit so buyers can accurately compare prices.
unitPricingMeasure The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item.

 

v1_beta.9.0

The following fields were added to the Browse API method responses.

New Field

Method

Field Description

adultOnly All Browse API methods This indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for
sellers and Searching for adult only items for buyers.
categroyId getItem and getItemByLegacyId methods The ID of the category for the item.

 

v1_beta.8.0

The following changes were made to the Browse API.

Added fieldgroups URI parameter to the getItem method

The fieldgroups URI parameter was added to the getItem method to enable you to control what is returned in the response. The Buy APIs are designed to let you create an eBay shopping experience in your app or website. This means you will need to know when item details, such as the price, availability, etc., has changed in any eBay item you are offering. You can now do this easily by setting fieldgroups to COMPACT, which reduces the response to only the fields that you need in order to check if any item detail has changed. For more information, see fieldgroups.

Add sellerItemRevision field to the getItem method

The sellerItemRevision field is n identifier generated/incremented when a seller revises the item. There are two types of item revisions; seller changes, such as changing the title, and eBay system changes, such as changing the quantity when an item is purchased. This ID is changed only when the seller makes a change to the item. This means you cannot use this value to determine if the quantity has changed.

New error message

The following error message was added to the search method.

Error ID

Error Description

12023 This keyword search results in a response that is too large to return. Either change the keyword or add additional query parameters and/or filters.