You are here: Buy APIs > Browse API > Release Notes

Browse API Release Notes

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

Announcements

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.

Availability of OpenAPI Specification

This release of the Browse API includes Beta version downloadable JSON and YAML formats of the API contract that comply with version 2.0 of the OpenAPI Specification. The OpenAPI Specification is a widely adopted standard for describing RESTful APIs. The eBay API specification files can facilitate your development process through the ability to generate client code in numerous languages, using the Swagger-Codegen tools, as well as the ability to easily view and test the API via the Swagger UI projects. Development of the OpenAPI Specification is overseen by the Open API Initiative, an open source collaborative project of the Linux Foundation.

Note: If you want to use the Swagger editing tool for viewing and testing, we advise you use the version of the editor that is compatible with 2.0 OpenAPI specifications: http://editor2.swagger.io/

Read the eBay API documentation for comprehensive API details, including allowed values, constraints, method-specific error messages, and implementation details.

File download  Download Browse API JSON specification (beta)

File download  Download Browse API YAML specification (beta)

The API release history

The following table lists the Browse API releases:

Release Version

Release Date

Description of Release

v1_beta.7.0

2017-06-07

Search for Items call

  • Added gtin URI parameter
  • Removed the gtin field filter (backwards incompatible change)
  • Added error messages

v1_beta.6.0

2017-05-25

  • Get Item, Get Item by Item Group, and Get Item by Legacy Id calls

    • Added fields to the response
    • Added support for legacy SKU
  • Search for Items call
    • Added fieldgroup and aspect_filter URI parameters
    • Added refinement response containers
    • Added filters
    • Added constraint information: maximum number of items returned is 10,000
  • Remove Get Item Feed call from Browse API. This functionality was moved to the Feed API.
  • Added support for additional eBay marketplaces
  • Added Taxonomy API information to the documentation, which retrieves category Ids

v1_beta.5.0

2017-04-20

  • New Get Legacy Item call that retrieves items using legacy item Ids
  • New Get Item by Item Group call
  • Get Item call, changes to the response, added a request header
  • Search for Items call, added filters and changes to the response
  • Buying Integration Guide update

v1_beta.4.0

2017-01-11

  • Added a field to the Get Item and Search for Items calls.
  • Removed fields that were deprecated in version v1_beta.3.0.
  • Updated the information regarding the requirement to join eBay Partner Network.
  • Added error messages.
  • Added documentation for the a restriction in Search for Items call request.

v1_beta.3.0

2016-11-17

Changes to fields in Get Item and Get Item Group calls

v1_beta.2.0

2016-11-08

Changes to field names, new filter, and new Image type.

v1_beta.1.0 2016-10-28 New field filters and a query parameter change.

v1_beta.0.0

2016-10-19 Initial API beta release

v1_beta.7.0

The following changes were made to the Search for Items call.

Added gtin URI parameter

Added a gtin URI parameter, which lets you search by GTIN (other Global Trade Item Number) or UPC (Universal Product Code) value. It can be used alone or with the other query parameters; category_ids, epid, or q.

For example:

/buy/browse/v1/item_summary/search?gtin:{099482432621}

Removed gtin field filter

The gtin field filter was removed. Note: This is a backwards incompatible change.

&filter=gtin:099482432621

Added new error messages

The following error messages were added.

Error Id

Error Description

12019 Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
12020 The 'fieldgroups' value {fieldgroups} is invalid when multiple 'category_ids' are specified. Either change the call to have only one value in 'category_ids' or remove the 'fieldgroups'.
12021 The 'epid' value {value} is invalid. For information, see the API call reference documentation.
12022 The 'gtin' value {value} is invalid. For information, see the API call reference documentation.

v1_beta.6.0

The following changes have been made in this release.

Get Item, Get Item by Item Group, and Get Item by Legacy Id call changes

The following response fields were added.

New Field/Container Name

Description

conditionId The identifier of the condition. For example, 1000 is the identifier for NEW.
epid An identifier of a product in the eBay product (epid) catalog. This indicates the product in which the item belongs.
productFicheWebUrl The URL to a page containing the manufacture's specification of an item, which helps buyers make a purchasing decision. This information is available for items that include the European energy efficiency rating (EEK) but is not available for all items with an EEK rating. This field is returned only if this information is available. The EEK rating of the item is returned in the energyEfficiencyClass field.
seller.sellerLegalInfo.email The seller's email address.
seller.sellerLegalInfo.fax The seller's fax number.
seller.sellerLegalInfo.imprint This is a free-form string created by the seller. This is information often found on business cards, such as address. This is information used by some countries.
seller.sellerLegalInfo.legalContactFirstName The seller's first name.
seller.sellerLegalInfo.legalContactLastName The seller's last name.
seller.sellerLegalInfo.name The name of the seller's business.
seller.sellerLegalInfo.phone The seller's phone number.
seller.sellerLegalInfo.registrationNumber The seller trade registration number.
seller.sellerLegalInfo.sellerProvidedLegalAddress The container for the seller's address to be used to contact them.
seller.sellerLegalInfo.termsOfService This is a free-form string created by the seller. This is the seller's terms or condition, which is in addition to the seller's return policies.
seller.sellerLegalInfo.vatDetails.issuingCountry The seller's VAT (value added tax) country code. VAT is a tax added by some European countries.
seller.sellerLegalInfo.vaDetails.vatId The seller's VAT (value added tax) Id. VAT is a tax added by some European countries.
taxes.includedInPrice Indicates if tax was applied for the cost of the item.
taxes.shippingAndHandlingTaxed Indicates if tax is applied for the shipping cost.
taxes.taxJurisdiction.region The region of the tax jurisdiction.
taxes.taxJurisdiction.region.regionName A free-form string that indicates the name of the region. This value can be the name of a world region (such as the "Middle East" or "Southeast Asia"), a country, or a domestic region within a country (such as "Alaska/Hawaii" or "US Protectorates") depending on the value of regionType. This value should be WORLDWIDE if the regionType value is WORLDWIDE.
taxes.taxJurisdiction.region.regionType Indicates the type of region. Valid values: COUNTRY, COUNTRY_REGION, STATE_OR_PROVINCE, WORLD_REGION, and WORLDWIDE
taxes.taxJurisdiction.taxJurisdictionId The identifier of the tax jurisdiction.
taxes.taxPercentage The percentage of tax.
taxes.taxType Container that returns the tax type. Valid values: PROVINCE_SALES_TAX, REGION, STATE_SALES_TAX, and VAT

 

Added support for legacy SKU

The legacy_variation_sku URI parameter was added to the Get Item By Legacy Id call. This parameter accepts the legacy SKU of the item and when used with the legacy_variation_id URI parameter, returns the specific item in an item group.

The following is an example of using the value of the ItemID and SKU fields, which were returned by the Trading API, to get the RESTful itemId value.

browse/v1/item/get_item_by_legacy_id?legacy_item_id=110039490209&legacy_variation_sku=V-00031-WHM

Search for Items call changes

The following section describes the changes that were made to the Search for Items call.

Added fieldgroups and aspect_filter URI parameters

The following URI parameters were added to the Search for Items call.

New URI Parameters

Description

fieldgroups

This controls what is returned in the response. The default is MATCHING_ITEMS, which returns the items that match the keyword or category specified.

The ASPECT_REFINEMENTS, BUYING_OPTION_REFINEMENTS, CATEGORY_REFINEMENTS, and CONDITION_REFINEMENTS values return all the aspects, buying options, categorys, and conditions metadata of the items along with the number of items in each. This data that can be used to create histograms.

You can also use include refinements and MATCHING_ITEMS to return both the metadata and items.

For complete details, see fieldgroups in the Browse Call Reference.

aspect_filter

This is an optional field that lets you limit the response to a category, which is required, and name/value aspect pairs. For example, in a clothing category one aspect pair would be Color/Red.

 

For example, the call below uses the category Id for Women's Clothing. This will return only items for a woman's red shirt.

/buy/browse/v1/item_summary/search?q=shirt&aspect_filter=categoryId:15724,Color:{Red}

 

To get a list of the aspects pairs and the category, which is returned in the dominantCategoryId field, set fieldgroups to ASPECT_REFINEMENTS.

/buy/browse/v1/item_summary/search?q=shirt&fieldgroups=ASPECT_REFINEMENTS

epid

The EPID is the eBay product identifier of a product from the eBay product catalog. Only items in the specified EPID are returned. The Get Item, Get Item By Legacy Id, and Get Item by Item Group calls return the EPID of the item.

       /buy/browse/v1/item_summary/search?filter=epid:{15032}

Maximum: 1

Required: The call must have catedgory_ids, epid, or q (or any combination of these)

Added fields to the response

The following fields and containers were added to the Search for Items call response.

New Fields

Description

Example

dominantCategoryId

The identifier of the category that has the most items.

"dominantCategoryId": "20863",

itemSummaries.
   conditionId

The identifier of the condition of the item.

"conditionId": "1000",

itemSummaries.
  epid

An identifier of a product in the eBay product (EPID) catalog. This indicates the product in which the item belongs.

"epid": "691335615",
refinement.
   aspectDistributions

This container returns name/values pair of the various aspects, the number of items matching this aspect, and the HATEOAS reference for the aspect. It also returns the dominantCategoryId field.

This container is returned when you set fieldgroups to ASPECT_REFINEMENTS or FULL in the request.

"dominantCategoryId": "20863",
"aspectDistributions": [
  {
    "localizedAspectName": "Brand",
    "aspectValueDistributions": [
      {
        "localizedAspectValue": "adidas",
        "matchCount": 187,
        "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search?q=world+cup+soccer+ball&limit=50&aspect_filter=categoryId%3A20863,Brand%3A%7Badidas%7D"
      },
      {
        "localizedAspectValue": "Nike",
        "matchCount": 7,
        "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball&limit=50 &aspect_filter=categoryId%3A20863,Brand%3A%7BNike%7D"
      },
refinement.
   buyingOptionDistributions
This container returns the buying option type, the number of items matching this option, and the HATEOAS reference for the option. Only AUCTION and FIXED_PRICE options are supported.

 

This container is returned when you set fieldgroups to BUYING_OPTION_REFINEMENTS or FULL in the request.

"buyingOptionDistributions": [
  {
    "buyingOption": "AUCTION",
    "matchCount": 41,
    "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball &limit=50&filter=buyingOptions%3A%7BAUCTION%7D"
  },
refinement.
   categoryDistributions

This container returns the category name and Id, and the number of items in this category, and the HATEOAS reference for the option.

 

This container is returned when you set fieldgroups to CATEGORY_REFINEMENTS or FULL in the request.

"categoryDistributions": [
  {
    "categoryName": "Clothing, Shoes & Accessories",
    "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball&limit=50 &category_ids=11450",
    "categoryId": "11450",
    "matchCount": 10856
  },
refinement.
   conditionDistributions
This container returns the condition name and Id, the number of items with this condition, the HATEOAS reference for the condition. Only NEW, USED, and UNSPECIFIED are returned.

 

This container is returned when you set fieldgroups to CONDITION_REFINEMENTS or FULL in the request.

"conditionDistributions": [
  {
    "condition": "NEW",
    "conditionId": "1000",
    "matchCount": 12281,
    "refinementHref": "https://api.ebay.com/buy/browse/v1/item_summary/search? q=world+cup+soccer+ball &limit=50&filter=conditions%3A%7BNEW%7D"
  },

 

Added new filters

The following filters were added the Search for Items calls.

Filter Name

Syntax

Description

conditionIds filter=conditionIds:{1000|1500} Only items with the specified condition Id are returned. For more information on item conditions for some popular eBay categories, see the Item Condition IDs and Names. Multiple values can be used for this filter and are separated by the pipe symbol - '|'.
itemStartDate filter=itemStartDate:[2016-11-14T07:47:48Z.. 2016-12-14T07:47:48Z] Only items scheduled to start within the specified date-time range are returned. The first date-time value is the start of the range and the second date-time value is the end of the range. The start and end range value are separated by two dots ('..').
maxDeliveryCost filter=maxDeliveryCost:0 Only items with free shipping are returned. Note: The only value supported is zero.
paymentMethods filter=paymentMethods:{CREDIT_CARD} Only items that offer payment by credit card are returned. Currently, only CREDIT_CARD is supported.

 

Added constraint information

Search can return a maximum of 10,000 items.

Removed Get Item Feed call from Browse API

The Get Item Feed call has been removed from the Browse API. This capability will be available in the new Feed API soon.

Added support for additional eBay marketplaces

The Browse API is now available on the following eBay marketplaces.

  • EBAY-AU - Australia (ebay.com/au)
  • EBAY-CA - Canada (English) (ebay.ca)
  • EBAY-DE - Germany (ebay.de)
  • EBAY-ES - Spain (ebay.es)
  • EBAY-FR - France (ebay.fr)
  • EBAY-IT - Italy (ebay.it)
  • EBAY-UK - Great Britain (ebay.co.uk)
  • EBAY-US - USA (ebay.com)

 

Added Taxonomy API information

The new Taxonomy API can be used to find categories you want to browse or search. It provides calls that enable the you to browse or search the category tree hierarchy. See the Finding Categories for Buy API Calls.

v1_beta.5.0

The following changes have been made in this release.

New Get Legacy Item call

The new Get Legacy Item call lets you pass in legacy Ids the and returns the item details and the REST item Id, which you can use in the Browse API Get Item calls. A legacy Id is an item Id returned by the eBay traditional APIs, such as the Trading API or Finding API.

For more information about how to use legacy Ids with the Buy APIs, see Legacy API compatibility in the Buying Integration Guide.

This call returns the item details, so it requires you pass in either the item Id of a non-variation item or the item Ids of both the parent and child of a item group (item with variations).

GET https://api.ebay.com/buy/browse/v1/item/get_item_by_legacy_id?
   legacy_item_id=string&
   legacy_variation_id=string

URI parameters

  • legacy_item_id - Specifies either:
    • The legacy item Id of an item that is not part of a group.
    • The legacy item Id of a group, which would be the group parent Id.
      Note: If you pass in a group Id, you must also use the legacy_variation_id field and pass in the legacy Id of the specific item variation (child Id).
  • legacy_variation_id - Specifies the legacy item Id of a specific item in an item group.

Response

New Get Item by Item Group call

The new Get Item by Item Group call, which replaces the Get Item Group call, improves the way variation information is returned and provides additional information, such as bid, estimated item availability, marketing discount, return terms, quantity sold, additional shipping, etc.

https://api.ebay.com/buy/browse/v1/item/get_items_by_item_group?item_group_id=string

Changes to the response

The Get Item by Item Group call has the same response as the other Get Item calls with the following exceptions.

  • Three additional fields:
    • commonDescriptions - An array of containers for a description and the item Ids of all the items that have this exact description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container along with the Ids of all the items that have this description. If the description is unique, it is returned in the items.description field.
    • commonDescriptions.description - The item description that is used by more than one of the item variations.
    • commonDescriptions.itemIds - A list of item Ids that have the description.
  • All the other fields, which are the item details, are the same as the Get Item and Get Legacy Item calls except these fields are returned in a container named items. The Get Item by Item Group call returns the item details for each item in the group, so for each item in the group there will be an items container.

Response

 

Get Item call changes

The following section describes the changes that were made to the Get Item call.

Added X-EBAY-C-ENDUSERCTX contextualLocation

Although the X-EBAY-C-ENDUSERCTX header containing contextualLocation is optional, it is strongly recommended that you use it when submitting the Get Item call. This header increases the accuracy of the estimated delivery window information and is needed for the calculated shipping. You always include the country code and you also include the zip code if zip codes are used in that country.

For example: X-EBAY-C-ENDUSERCTX contextualLocation=country%3DUS%2Czip%3D19406

Response

Changes to the response

The following table compares the response from the prior release (Previous) with this release (New). The bolded text in the table indicates either new types/fields or types/fields that have been replaced or renamed.

Previous

New

  estimatedAvailabilities
  estimatedAvailabilities.availabilityThreshold
  estimatedAvailabilities.availabilityThresholdType
  estimatedAvailabilities.deliveryOptions
availabilityStatusForShipToHome estimatedAvailabilities.estimatedAvailabilityStatus
  estimatedAvailabilities.estimatedAvailableQuantity
  primaryItemGroup
primaryItemGroupHref primaryItemGroup.itemGroupHref
primaryItemGroupId primaryItemGroup.itemGroupId
  primaryItemGroup.itemGroupImages
  primaryItemGroup.itemGroupImages.height
  primaryItemGroup.itemGroupImages.imageUrl
  primaryItemGroup.itemGroupImages.width
  primaryItemGroup.itemGroupTitle
  primaryItemGroup.itemGroupType
shippingOptions shippingOptions
  shippingOptions.additionalShippingCostPerUnit (ConvertedAmount)
  shippingOptions.cutOffDateUsedForEstimate
  shippingOptions.maxEstimatedDeliveryDate
  shippingOptions.minEstimatedDeliveryDate
  shippingOptions.quantityUsedForEstimate
shippingOptions.shippingCarrierName shippingOptions.shippingCarrierCode
shippingOptions.shippingCost (Amount) shippingOptions.shippingCost (ConvertedAmount)
shippingOptions.shippingCost.currency shippingOptions.shippingCost.currency
shippingOptions.shippingCost.value shippingOptions.shippingCost.value
  shippingOptions.shippingCost.convertedFromCurrency
  shippingOptions.shippingCost.convertedFromValue
  shippingOptions.shippingCostType
shippingOptions.shippingServiceName shippingOptions.shippingServiceCode
  shippingOptions.shipToLocationUsedForEstimate
  shippingOptions.shipToLocationUsedForEstimate.country
  shippingOptions.shipToLocationUsedForEstimate.postalCode
shippingOptions.trademarkSymbol shippingOptions.trademarkSymbol
shippingOptions.type shippingOptions.type

 

Search for Items call changes

The following section describes the changes that were made to the Search for Items call.

Added filters

The following filters were added. For details about these filters, see Search Filter Usage Details.

  • returnsAccepted - Excludes items that cannot be returned to the seller
  • excludeCategoryIds - Excludes items in the specified categories

Changes to the response

The following table lists the fields that were added, deprecated, and the one type that was replaced.

Field or Type

Change

Description

itemSummaries.shippingOptions.maxEstimatedDeliveryDate

Added

The end date of the delivery window (latest projected delivery date).

itemSummaries.shippingOptions.minEstimatedDeliveryDate

Added

The start date of the delivery window (earliest projected delivery date).

itemSummaries.itemGroupType

Added

Indicates the item group type. Currently only SELLER_DEFINED_VARIATIONS is supported and indicates this is an item group created by the seller.

Note: This field is populated only for item groups (item with variations).

itemSummaries.itemHref

Added

A HATEOAS reference to the item.

Note: In the last release, this field was always populated. Now, it is populated only for group items (an item with variations).

Amount

Replaced with ConvertedAmount

This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable.

Note: The ConvertedAmount type has two additional fields; convertedFromCurrency and convertedFromValue.

topRatedBuyingExperience

Removed.

 

 

Buying Integration Guide update

The following changes were made to the Buying Integration Guide:

v1_beta.4.0

The following changes have been made in this release.

Changes to fields

Field Name

Change

Description

itemWebUrl

Added to the Get Item and Search for Items calls

The URL to the View Item page of the item.

sellerProvidedDescription

Removed (deprecated). Use the description field instead.

 

generatedShortDescription

Removed (deprecated). Use the shortDescription field instead.

 

Change to Buying integration guide

The Buying Integration Guide said that in order to use the Buying APIs you must join the eBay Partner Network. This is incorrect. It should have said you need to join the eBay Partner Network if you wanted to use Get Item Feed call and/or participate in revenue sharing through the eBay Partner Network.

Added errors

The following errors have been added to the Search for Items call.

Error ID

Category

Description

12013

BUSINESS

Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category.

12014

BUSINESS

The sellerAccountTypes filter is only supported for certain marketplaces. Please check the documentation for more information.

12015

REQUEST

The postal code filter value is invalid for the specified country and this filter was ignored.

Added documentation for a restriction in Search for Items request

In a Search for Items request, you cannot use the * wildcard character in the q field. This restriction has been added to the documentation. For example:

GET https://api.ebay.com/buy/browse/v1/item_summary/search?q=*

v1_beta.3.0

The following changes have been made in this release.

Changes to fields in the Get Item call

Field Name

Change

Description

description

The sellerProvidedDescription field was renamed description.

The full description of the item as written by the seller. This can be plain text or rich content.

shortDescription

The generateShortDescription field was renamed shortDescription.

A snippet of the full item description and will always be plain text.

Changes to fields in the Get Item Group call

Field Name

Change

Description

description

The description field replaces the sellerProvidedDescription field because it is being deprecated.

The full description of the item as written by the seller. This can be plain text or rich content.

shortDescription

The shortDescription field replaces the generateShortDescription field because it is being deprecated.

A snippet of the full item description and will always be plain text.

sellerProvidedDescription

Do not use this field. It has been deprecated and will be removed. Use the description field instead.

 

generatedShortDescription

Do not use this field. It has been deprecated and will be removed. Use the shortDescription field instead.

 

v1_beta.2.0

The following changes have been made in this release.

Added type

The new type called Image was added. It replaces string as the data type for fields that return image URLs. Image has the following fields.

  • width – An integer representing the width of the image.
  • height – An integer representing the height of the image.
  • imageUrl – A string that is the URL of the image.

Note: Currently only the imageUrl field is getting populated. The height and width fields were added for future use.

Added fields

The following new response fields were added.

seller.sellerAccountTypes

Indicates if the seller is a business or an individual. This is determined when the seller registers with eBay. If they register for a business account, this value will be BUSINESS. If they register for a private account, this value will be INDIVIDUAL. This designation is required by the tax laws in some countries.

 

This field is returned only on the following sites.

EBAY-AT, EBAY-BE, EBAY-CH, EBAY-DE, EBAY-ES, EBAY-FR, EBAY-GB, EBAY-IE, EBAY-IT, and EBAY-PL

 

Valid values:

  • BUSINESS
  • INDIVIDUAL
string
item.subtitle An additional shorten title for the item that is created by the seller. string

Added a filter

The sellerAccountTypes filter was added and filters the results by sellers with INDIVIDUAL or BUSINESS accounts. You can filter by either INDIVIDUAL or BUSINESS. But you cannot filter by both.

The following new response field was added.

New Field Description Data Type
seller.sellerAccountTypes

Only items from the specified seller account type are returned in the response. The seller account type indicates if the seller is a business or an individual. This is determined when the seller registers with eBay.

 

If they register for a business account, they have a business account. If they register for a private account, they have an individual account. This designation is required by the tax laws in some countries.

 

You can filter by either BUSINESS or INDIVIDUAL. But you cannot filter by both.

 

This filter is supported on the following sites.

EBAY-AT, EBAY-BE, EBAY-CH, EBAY-DE, EBAY-ES, EBAY-FR, EBAY-GB, EBAY-IE, EBAY-IT, and EBAY-PL

 

Valid values:

  • BUSINESS
  • INDIVIDUAL
string

Removed or renamed response fields

Several response fields were deleted, renamed, or had their data type changed. These response fields are discussed in the table below:

Field Name Change Data type Change
itemSummary.thumbnailImages   Changed from list of strings to a list of images
itemSummary.imageUrl Renamed to image Changed from string to image type
itemSummary.additionalImageUrls Renamed to itemSummary.additionalImages Changed from list of strings to a list of images
seller.logoImageUrl Deleted  
discription Renamed to generatedShortDescription  
discriptionInHTML Renamed to sellerProvidedDescription  
imageUrl Renamed to image Changed from string to image type
additionalImageUrls Renamed to additionalImages Changed from list of strings to a list of images
seller.logoImageUrl Deleted  

v1_beta.1.0

The following changes were made to the Browse API since the 10/17/2016 release.

Search for Items call Changes

The following changes have been made to the Search for Items call.

Changed query parameter

A category_ids query parameter has been added. With this query parameter, one eBay category ID can be specified, and only items listed in this category will be retrieved. Below is an example of its usage:

GET https://api.ebay.com/buy/browse/v1/item_summary/search?category_ids=29792

Note: If a top-level (L1) category is specified with the category_ids query parameter, a search string must also be included in call URI using the q query parameter. Below is an example of this use case:

GET https://api.ebay.com/buy/browse/v1/item_summary/search?q=Outliers&category_ids=1854946

Note: This is a backwards incompatibility change. If you have previously integrated with/used categoryId as a filter value, you will need to make updates to use the category_ids query parameter instead.

Added field filters

Several new filter types were added. These filter types and their values are specified through the existing filter query parameter. Each of these filter types are discussed in the table below:

Filter type Syntax Description Supported Values
buyingoptions filter=buyingOptions:{FIXED_PRICE}

Only items using the specified buying format(s) are returned. Supported values are FIXED_PRICE (basic fixed-price and auctions with Buy It Now feature), and AUCTION (auctions without Buy It Now feature). Multiple values can be used for this query parameter and are separated by the pipe symbol - '|'.

 

 

FIXED_PRICE, AUCTION. Default is FIXED_PRICE.
conditions filter=conditions:{NEW} Only items in the specified condition(s) are returned. Supported values are NEW, USED, and UNSPECIFIED. Item condition values can vary by category. For more information on item conditions for some popular eBay categories, see the Item conditions by category help topic. Multiple values can be used for this query parameter and are separated by the pipe symbol - '|'. NEW, USED, UNSPECIFIED
deliveryCountry filter=deliveryCountry:US Only items that can be shipped to the specified country are returned. The two-digit country codes defined in the ISO 3166-1 standard are used. This filter, along with deliveryPostalCode, are not applicable (and is ignored if set) when the user is using local pickup filters. The two-digit ISO 3166-1 country codes.
deliveryOptions filter=deliveryOptions:SELLER_ARRANGED_PICKUP_LOCATION Only local pickup items are returned. Currently, the only supported value is SELLER_ARRANGED_PICKUP_LOCATION. This query parameter (along with the four other 'pickup' query parameters) must be included if the user is looking for local pickup items. SELLER_ARRANGED_LOCAL_PICKUP
deliveryPostalCode filter=deliveryPostalCode:95125 Only items that can be shipped to the specified postal/zip code are returned. If this filter is used, the deliveryCountry must also be set. This filter, along with deliveryCountry, are not applicable (and is ignored if set) when the user is using local pickup filters. A valid postal code (also known as zip code in the US).
excludeSellers filter=excludeSellers:{rpsseller|bigSales} Any items from the specified seller(s) are not returned in the response. Multiple values can be used for this query parameter and are separated by the pipe symbol - '|'. Use the sellers' eBay user IDs. eBay user ID(s) for sellers.
gtin filter=gtin:099482432621 Only items matching the GTIN value are returned. Currently, only UPC (Universal Product Code) values are supported, but other Global Trade Item Number (GTIN) types may be supported in future. A valid UPC value.
itemEndDate filter=itemEndDate:[2016-11-14T07:47:48Z.. 2016-12-14T07:47:48Z] Only items scheduled to end within the specified date-time range are returned. The date-time format defined in the ISO 8601 standard is used. The first date-time value is the start time and the second date-time value is the end time. The start and end time are separated by two dots ('..'). It is possible to only use a start time or only use an end time. If only a start time is used, every listing ending after that time is returned. If only a end time is used, every listing ending before that time is returned. If only specifying a start time, the two dots ('..') are not needed (e.g. filter=itemEndDate:[2016-11-14T07:47:48Z]). If only specifying an end time, the two dots ('..') are required before the end time (e.g. filter=itemEndDate:[..2016-12-14T07:47:48Z]). A date range.
itemLocationCountry filter=itemLocationCountry:US Only items located in the specified country are returned. Use the two-digit country codes defined in the ISO 3166-1 standard. Only one country code value can be used for this query parameter. This filter is not applicable (and is ignored if set) when the user is using local pickup filters. The two-digit ISO 3166-1 country codes.
pickupCountry filter=pickupCountry:US This filter, along with the three other 'pickup' filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved. The pickupCountry value is the two-digit country code defined in the ISO 3166-1 standard. When the user is looking for 'local pickup' items, the deliveryOptions filter must also be used. The two-digit ISO 3166-1 country codes.
pickupPostalCode filter=pickupPostalCode:95125 This filter, along with the three other 'pickup' filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved. The pickupPostalCode value is generally the postal code for the buyer's address. When the user is looking for 'local pickup' items, the deliveryOptions filter must also be used. A valid postal code (also known as zip code in the US).
pickupRadius filter=pickupRadius:25 This filter, along with the three other 'pickup' filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are be retrieved. The pickupRadius value defines the distance that the buyer is willing to travel (in miles or km) from the postal code defined in the pickupPostalCode query parameter to pick up the item. When the user is looking for 'local pickup' items, the deliveryOptions filter must also be used. An integer value in increments of 5, such as 5, 10, 15, 20, 25, etc.)
pickupRadiusUnit filter=pickupRadiusUnit:mi This filter, along with the three other 'pickup' filters, sets the local pickup radius. Only items that are available through local pickup and within the pickup radius set by the user are retrieved. The pickupRadiusUnit defines the distance measurement unit used for the pickup radius. When the user is looking for 'local pickup' items, the deliveryOptions filter must also be used. mi, km
priceCurrency filter=priceCurrency:USD This filter is only needed and applicable if the price (range) filter is used. It assigns the currency tied to the price. Use the three-digits currency codes defined in the ISO 4217 standard. The two-digit ISO 4217 currency codes.

Removed filter field

categoryId was removed as a valid filter value, and users can search on a Category ID by using the new category_ids query parameter.

Added a sort value

Retrieved items can now be sorted by distance. If distance is used in a sort query parameter, the retrieved items will be returned in ascending order according to local pickup distance. The distance sort value is only applicable if the local pickup filters are used.

Added response fields

Several new response fields were added. These response fields are discussed in the table below:

New Field Description Data type Supported/Applicable Values/Syntax
itemSummaries.topRatedBuyingExperience A true value in this boolean indicates that the item is part of a top-rated listing. To qualify as a top-rated listing, the seller must meet all requirements for being a top-rated seller, the item must have an expedited handling time (0 or 1 days), and the seller must offer a return policy with a return window of at least 30 days. To see more information on the requirements for a top-rated seller and top-rated listing in the US, see the Becoming a Top Rated Seller and qualifying for Top Rated Plus help topic. This particular help topic also discusses the Top Rated requirements on other sites. This fields is always returned. boolean true, false
"topRatedBuyingExperience": "true"
itemSummaries.energyEfficiencyClass The enumeration value returned in this field indicates the energy efficiency rating of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. Currently, this field is only applicable for the Germany site, and this field will only be returned if the seller specified the energy efficiency rating through item specifics at listing time. string A+++, A++, A+, A, B, C, D, E, F, G
"energyEfficiencyClass": "A+"
itemSummaries.itemLocation The itemLocation container gives the location of the item. This container consists of fields you typically see for an address, including postalCode (string), county (string), stateOrProvince (string), addressLine1 (string), addressLine2 (string), city (string), and country (2-digit ISO code). ItemLocationImpl
"itemLocation": {
   "postalCode": "95125",
   "county": "Santa Clara",
   "stateOrProvince": "CA",
   "addressLine1": "2025 Hamilton Ave.",
   "city": "San Jose",
   "country": "US"
}
itemSummaries.buyingOptions The enumeration value(s) returned in this field indicates the buying options available for the item. Buying options include fixed-price (FIXED_PRICE) and auction (AUCTION). both FIXED_PRICE and AUCTION are returned for auction listings enabled with the Buy It Now feature. enum FIXED_PRICE, AUCTION
"buyingOptions":["AUCTION", "FIXED_PRICE"]
itemSummaries.bidCount This integer value indicates the total number of bids that have been placed against an auction item. This field will only be returned if the buying format is AUCTION. integer "bidCount": 8
itemSummaries.currentBidPrice This container displays the current highest bid for an auction item. The value (string) field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This field will only be returned if the buying format is AUCTION. Amount
"currentBidPrice": {
   "value": "23.5",
   "currency": "USD"
}
itemSummaries.condition The value returned in this field will indicate the condition of the item. This field is always returned. string "condition": "New"
itemSummaries.categories This container consists of the primary listing category ID of the item (as well as secondary listing category if item was listed in two categories).  
Category
   "categories": [
      {
         "categoryId": "171243"
      },
]
itemSummaries.additionalImageUrls This container is an array of URLs for additional images that were included with the item. Gallery Plus images. string
"additionalImageUrls": [
   "http://galleryplus.ebayimg.com/ws/web/142039580579_2/225x225.jpg",
   ...
[
itemSummaries.thumbnailImages This container is an array of thumbnail images for the item. For each image, the URL thumbnailImageUrl (string) to the image is given, as well as the width (integer) and height (integer). ThumbnailImages  
itemSummaries.distanceFromPickupLocation This container indicates the distance away that the item is from the pickupPostalCode. This container is only returned if the "local pickup" filter fields are used in the request. The child fields of distanceFromPickupLocation is unitOfMeasure (mi or km are supported values) and value (string), which is the actual distance away from the pickupPostalCode. TargetLocation
"distanceFromPickupLocation": {
   "unitOfMeasure": "mi",
   "value": "25"
}
itemSummaries.itemAffiliateWebUrl This URL is the link to the View Item page with an affiliate tracking ID included. This field is only returned if the seller enabled affiliate tracking for the listing.

Request Header X-EBAY-C-ENDUSERCTX needs to be populated with value

affiliateCampaignId=${ePN Campaign Id}, affiliateReferenceId=${reference Id}

affiliateCampaignId is a mandatory field
Eg: affiliateCampaignId=123454, affiliateReferenceId=referenceId
string
itemSummaries.pickupOptions The enumeration value(s) returned in this field indicates the local pickup options available for the item. Possible values include ARRANGED_LOCATION and STORE. PickupOptionSummary ARRANGED_LOCATION, STORE
"pickupOptions": ["STORE", "ARRANGED_LOCATION"]
itemSummaries.shippingOptions This container consists of the shipping cost and type. ShippingCostType values include FIXED (flat-rate shipping) and CALCULATED (calculated shipping). ShippingOptionSummary
"shippingOptions": [
   {
      "shippingCostType": "FIXED",
      "shippingCost": {
         "value": "0.0",
         "currency": "USD"
      }
   }
]

Get Item call changes

New response fields have been added to the Get Item calls.

Added response fields

Several new response fields were added. One response field (shippingOptions.deliveryCost) was renamed to shippingOptions.shippingCost. Note: This change is a backwards incompatibility change. You must update your code to change the name of this field from deliveryCost to shippingCost. These response fields are discussed in the table below:

New Field Description Data type
topRatedBuyingExperience A true value in this boolean indicates that the item is part of a top-rated listing. To qualify as a top-rated listing, the seller must meet all requirements for being a top-rated seller, the item must have an expedited handling time (0 or 1 days), and the seller must offer a return policy with a return window of at least 30 days. To see more information on the requirements for a top-rated seller and top-rated listing in the US, see the Becoming a Top Rated Seller and qualifying for Top Rated Plus help topic. This particular help topic also discusses the Top Rated requirements on other sites. This fields is always returned. boolean
energyEfficiencyClass The enumeration value returned in this field indicates the energy efficiency rating of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. Currently, this field is only applicable for the Germany site, and this field will only be returned if the seller specified the energy efficiency rating through item specifics at listing time. string
buyingOptions The enumeration value(s) returned in this field indicates the buying options available for the item. Buying options include fixed-price (FIXED_PRICE) and auction (AUCTION). both FIXED_PRICE and AUCTION are returned for auction listings enabled with the Buy It Now feature. enum
bidCount This integer value indicates the total number of bids that have been placed against an auction item. This field will only be returned if AUCTION is returned in the buyingOptions field. integer
currentBidPrice This container displays the current highest bid for an auction item. The value (string) field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This field will only be returned if the buying format is AUCTION. Amount
itemAffiliateWebUrl

This URL is the link to the View Item page with an affiliate tracking ID included. This field is only returned if the seller enabled affiliate tracking for the listing. This field is return only if you include affiliateCampaignId in the X-EBAY-C-ENDUSERCTX request header.

The affiliateCampaignId value is a mandatory field and the affiliateReferenceId value is optional and can be any value you want to use to identify this item.

affiliateCampaignId=${ePN Campaign Id}, affiliateReferenceId=${reference Id}

Example of the response field:

"itemAffiliateWebUrl": "http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=wikibuy&customid=&toolid=10050&mpre=http%3A%2F%2Fwww.ebay.com%2Fitm%2FApple-iPhone-6S-Latest-Model-64GB-Space-Gray-Factory-Unlocked-Smartphone-%2F272419891755%3Fvar%3D0"

string

shippingOptions.shippingCost

This particular field was renamed from ‘deliveryCost’ to ‘shippingCost’. Although its name changed, this field still has the same purpose/functionality. Note: This is a backwards incompatibility change. ShippingOptionSummary
uniqueBidderCount This integer value indicates the number of different eBay users who have placed one or more bids on an auction item. This field is only applicable to auction listings. integer

v1_beta.0.0

This is the initial BETA release of this API.

New calls

  • Item
    • Get Item
  • Item Feed
    • Get Item Feed
  • Item Group
    • Get Item Group
  • Item Summary
    • Search for Items