feed APIv1_beta.10.0

Feed API Release Notes

Just getting started with the Feed 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 the Feed API releases:

Release Version

Release Date

Description of Release

v1_beta.10.0 2018-10-23

Added columns to the getItemSnapshotFeed files

v1_beta.9.0 2018-10-01 and 2018-08-01
2018-10-01

getItemSnapshotFeed: Change the data in the Title column to an escaped string when special characters are present

2018-08-01
  • Removed the restockingFeePercentage column from getItemFeed (backwards incompatible change)
  • Added Last-Modified response header to all feeds
  • New open source Feed SDK written in Java
v1_beta.8.0 2018-06-18
  • Added return and discount columns and support for the GB marketplace to getItemSnapshotFeed file
  • Added the energyEfficiencyClass column to getItemFeed file
v1_beta.7.0 2018-05-15
  • Added the getItemGroupFeed method
  • Added discount columns to the getItemFeed file
v1_beta.6.0 2018-03-19
  • Added support for the DE and GB eBay marketplaces
  • Added inferredLocalizedAspects and additionalImages columns
v1_beta.5.0 2018-03-01 Added columns for:
  • Shipping information: include/exclude countries and regions and delivery options
  • Inferred (derived) product identification

Important: These columns will first appear in the feed file for Feb. 27, 2018. All feed files after Feb. 27, will contain these columns. Be sure that your app can handle these new columns.

v1_beta.4.0 2018-02-14 Added getItemSnapshotFeed method
v1_beta.3.0 2018-01-29
  • Renamed the feed_type parameter (backwards incompatible change)
  • Added columns for payment processing and return information
v1_beta.2.0 2017-10-24 Added three available quantity columns to the Item feed file
v1_beta.1.0 2017-10-16
  • Replaced the item_summary resource with item
  • Added new resources
  • Added a new request header
v1_beta.0.0 2017-06-01 Initial API beta release

 

v1_beta.10.0

The following columns were added to the getItemSnapshotFeed file. These new columns will be in the feed file after 10-23-18 5pm UTC-7.

New Columns

Description

energyEfficiencyClass Indicates the European energy efficiency rating (EEK) of the item. This field is returned only if the seller specified the energy efficiency rating. The rating is a set of energy efficiency classes from A to G, where 'A' is the most energy efficient and 'G' is the least efficient. This rating helps buyers choose between various models.

To retrieve the manufacturer's specifications for this item, when they are available, use the getItem method in the Browse API. The information is returned in the productFicheWebUrl field.
additionalImageUrls A pipe separated (|) list of URLs for the additional images of the item. These images are in addition to the primary image, which is returned in the imageUrl column. Note: This column can contain multiple values.
deliveryOptions A comma separated list of delivery options for the item, such as SHIP_TO_HOME and SELLER_ARRANGED_LOCAL_PICKUP. This column lets you filter out items that cannot be shipped to the buyer.
shipToIncludedRegions A pipe (|) separated alphabetical list of the geographic countries and regions where the seller will ship the item. If a region is specified, you will need to subtract any countries and regions returned in the shipToExcludedRegions column to fully understand where the seller will ship. The COUNTRY: list is separated from the REGION: list with a semicolon (;).

Format Example:
COUNTRY:US|BM|GL|MX|PM;REGION:AFRICA|ASIA|CENTRAL_AMERICA_AND_CARIBBEAN|EUROPE|MIDDLE_EAST|OCEANIA|SOUTH_AMERICA|SOUTHEAST_ASIA;

Country Values: The two-letter ISO 3166 standard code of the country.

Region Values: AFRICA, AMERICAS, ANTARCTIC, ARCTIC, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EURO_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, REST_OF_ASIA, SOUTHEAST_ASIA, SOUTH_AMERICA, WORLDWIDE
shipToExcludedRegions A pipe (|) separated alphabetical list of the geographic countries and regions where the item cannot be shipped. These countries and regions refine (restrict) the shipToIncludedRegions list. The COUNTRY: list is separated from the REGION: list with a semicolon (;).

Format Example:
COUNTRY:US|BM|GL|MX|PM;REGION:AFRICA|ASIA|CENTRAL_AMERICA_AND_CARIBBEAN|EUROPE|MIDDLE_EAST|OCEANIA|SOUTH_AMERICA|SOUTHEAST_ASIA;

Country Values: The two-letter ISO 3166 standard code of the country.

Region Values: AFRICA, AMERICAS, ANTARCTIC, ARCTIC, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EURO_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, REST_OF_ASIA, SOUTHEAST_ASIA, SOUTH_AMERICA, WORLDWIDE
acceptedPaymentMethods Indicates the credit card service that will be used to process the transaction.
  • If this column contains PAYPAL, you can use the Buy Order API to checkout and purchase the item.
  • If this column is empty, you must use another method for checkout.

v1_beta.9.0

The following changes have been made to the Feed API.

2018-10-01

The following change has been made to the getItemSnapshotFeed files. All other feed files already have this encoding.

Starting with feed files generated on October 1, 2018, the Title will be an escaped string when special characters are present, using the following rules:

  • Double quotes (") and backslashes (\) in the Title are escaped with a backslash (\) character
  • If there are any tabs (\t), double quotes ("), or backslashes (\) in the Title, the entire Title will be wrapped in double quotes.

For example

Before:

Misty Rainforest Modern Masters 2017 MTG Magic Fetch Land Free Ship W\Tracking

Marvel Legends HULK 8" Figure Avengers Age of Ultron Studios 6" Series

After:

"Misty Rainforest Modern Masters 2017 MTG Magic Fetch Land Free Ship W\\Tracking"

"Marvel Legends HULK 8\" Figure Avengers Age of Ultron Studios 6\" Series"

 

2018-08-01

Removed restockingFeePercentage column

The restockingFeePercentage column was removed from the getItemFeed method because eBay has deprecated the restocking fee in listings.

Note: This is a backwards incompatible change.

Added a Last-Modified response header

The Last-Modified response header has been added to all the Feed API methods. This header returns the generation date of the feed file, which will be the latest file available.

For example:

Last-Modified Wed 21 Oct 2015 07:28:00 GMT

Also, the date field is needed only when feed_scope=NEWLY_LISTED. If you specify a date and feed_scope=ALL_ACTIVE, the date value is ignored and the latest file is returned. The date of that file is returned in the Last-Modified response header.

Provided an open source Feed SDK

In addition to the API, there is an open source Feed SDK written in Java that downloads and unzips the feed file and lets you specify field filters to curate the items in the file.

 

v1_beta.8.0

The following changes have been made to the Feed API.

Added return and discount columns to getItemSnapshotFeed

The snapshot feed files are now available for the GB eBay Great Britain (ebay.co.uk) marketplace.

The following columns were added to the getItemSnapshotFeed.

New Columns

Description

returnsAccepted Indicates whether the seller accepts returns for the item.
refundMethod An enumeration value that indicates how a buyer is refunded when an item is returned.

Code so that your app gracefully handles any future changes to this list.
returnMethod An enumeration value that indicates the alternative methods for a full refund when an item is returned. This column will have data if the seller offers the buyer an item replacement or exchange instead of a monetary refund.
returnShippingCostPayer The party responsible for the return shipping costs when an item is returned. This will be either buyer or seller.
returnPeriodValue The amount of time the buyer has to return the item after the purchase date. This can be the number of years, months, or days depending on returnPeriodUnit. For example, if this value is '30', and the returnPeriodUnit value is 'DAY', the return period is 30 days.
returnPeriodUnit An enumeration value that indicates the period of time being used to measure the duration, such as business days or months, or years.

See the TimeDurationUnitEnum type for a list of possible time-measuring units.
originalPriceValue The original selling price of the item. This lets you surface a strikethrough price for the item.
originalPriceCurrency The currency of the originalPriceValue of the item and the discountAmount.
discountAmount The calculated amount of the discount (originalPriceValue - priceValue). For example, if originalPriceValue is 70 and priceValue is 56, this value would be 14.

Note: The currency shown in originalPriceCurrency is used for both discountAmount and originalPriceCurrency.
discountPercentage The calculated discount percentage. For example, if originalPriceValue is 70 and discountAmount is 14, this value will be 20.

Added energyEfficiencyClass to getItemFeed

Added the energyEfficiencyClass column that indicates the European energy efficiency rating (EEK) of the item. This field is returned only if the seller specified the energy efficiency rating. The rating is a set of energy efficiency classes from A to G, where 'A' is the most energy efficient and 'G' is the least efficient. This rating helps buyers choose between various models.
When the manufacturer's specifications for this item are available, the link to this information is returned in the productFicheWebUrl field.

v1_beta.7.0

Added getItemGroupFeed method

The getItemGroupFeed method was added to the Feed API. This lets you download an Item Group TSV_GZIP (tab separated value gzip) feed file containing the Item Group information for items in the Item feed file that were associated with an item group. This information includes a list of the aspect (variation) names for this item group. For example, if the item was a shirt some of the aspect names could be Size, Color, etc., which are returned in the variesByLocalizedAspects column. (An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.)

The first line of the file is the header, which labels the columns and indicates the order of the values on each line. Each header is described in the Response fields section.

Added item discount information to getItemFeed

The following columns were added the Item feed file. This information gives you the ability to show the item that have been discounted.

New Columns

Description

originalPriceValue The original selling price of the item. This lets you surface a strikethrough price for the item.
originalPriceCurrency The currency of the originalPriceValue of the item and the discountAmount.
discountAmount The calculated amount of the discount (originalPriceValue - price). For example, if originalPriceValue is 70 and price is 56, this value would be 14.
Note: The currency shown in originalPriceCurrency is used for both discountAmount and originalPriceCurrency.
discountPercentage The calculated discount percentage. For example, if originalPriceValue is 70 and discountAmount is 14, this value will be 20.

v1_beta.6.0

The following changes have been made to the Feed API.

Added support for the DE and GB marketplaces

You can now download the feed files for items hosted on the Germany (ebay.de) and Great Britain (ebay.co.uk) eBay marketplaces. To do this, set the X-EBAY-C-MARKETPLACE-ID request header to either EBAY_DE or EBAY_GB.

Added two new columns

The following columns were added to the getItemFeed method.

New Columns

Description

inferredLocalizedAspects The inferredLocalizedAspects column was added to the getItemFeed method. The column contains item aspects have been programmatically determined by eBay. Just like the localizedAspects column, these aspects are a semicolon separated list of the name/value pairs for the aspects of the item, which are BASE64 encoded. If the seller provided aspects for the item, the seller's values are returned in the localizedAspects column.
additionalImages A pipe (|) separated list of URLs for the images of the item. These images are in addition to the primary image, which is returned in the imageUrl column.

 

v1_beta.5.0

The following columns, which provide shipping, delivery, and inferred product information of the item, were added to the getItemFeed method.

New Columns

Description

deliveryOptions A comma separated list of delivery options for the item, such as SHIP_TO_HOME and SELLER_ARRANGED_LOCAL_PICKUP. This column lets you filter out items that cannot be shipped to the buyer.
shipToIncludedRegions A pipe (|) separated alphabetical list of the geographic countries and regions where the seller will ship the item. If a region is specified, you will need to subtract any countries and regions returned in the shipToExcludedRegions column to fully understand where the seller will ship. The COUNTRY: list is separated from the REGION: list with a semicolon (;).

Format Example:

COUNTRY:US|BM|GL|MX|PM;REGION:AFRICA|ASIA|CENTRAL_AMERICA_AND_CARIBBEAN|EUROPE|MIDDLE_EAST|OCEANIA|SOUTH_AMERICA|SOUTHEAST_ASIA;


Country Values: The two-letter ISO 3166 standard code of the country.

Region Values: AFRICA, AMERICAS, ANTARCTIC, ARCTIC, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EURO_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, REST_OF_ASIA, SOUTHEAST_ASIA, SOUTH_AMERICA, WORLDWIDE
shipToExcludedRegions A pipe (|) separated alphabetical list of the geographic countries and regions where the item cannot be shipped. These countries and regions refine (restrict) the shipToIncludedRegions list. The COUNTRY: list is separated from the REGION: list with a semicolon (;).

Format Example:

COUNTRY:US|BM|GL|MX|PM;REGION:AFRICA|ASIA|CENTRAL_AMERICA_AND_CARIBBEAN|EUROPE|MIDDLE_EAST|OCEANIA|SOUTH_AMERICA|SOUTHEAST_ASIA;


Country Values: The two-letter ISO 3166 standard code of the country.

Region Values: AFRICA, AMERICAS, ANTARCTIC, ARCTIC, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EURO_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, REST_OF_ASIA, SOUTHEAST_ASIA, SOUTH_AMERICA, WORLDWIDE
inferredEpid The ePID (eBay Product ID of a product from the eBay product catalog) for the item, which has been programmatically determined by eBay.

If the seller provided an ePID for the item, the seller's value is returned in the epid column.
inferredGtin The GTIN (Global Trade Item Number) of the item as defined by http://www.gtin.info, which as been programmatically determined by eBay. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.

If the seller provided a GTIN for the item, the seller's value is returned in the gtin column.
inferredBrand The name brand for the item, such as Nike or Apple, which has been programmatically determined by eBay. To identify the product, this is always used along with MPN.

If the seller provided a brand for the item, the seller's value is returned in the brand column.
inferredMpn The MPN for the item, which has been programmatically determined by eBay. MPN is the manufacturer's part number, which is a unique number that identifies a specific product. To identify the product, this is always used along with brand.

If the seller provided a MPN for the item, the seller's value is returned in the mpn column.

v1_beta.4.0

You can now get an hourly snapshot feed file using the getItemSnapshotFeed method. This file contains all the items that have changed within the hour/day/category specified. You can use this file to update the information of your curated stored items.

v1_beta.3.0

The following changes have been made to the Feed API.

Renamed a query parameter

The feed_type query parameter was renamed to feed_scope. The feed_type parameter will stop being supported on March 31, 2018. Please update your application to use feed_scope before this date.

Added New Columns

The following columns were added to the Item feed file. These columns were add to the end of the existing columns in the order shown below.

New Columns

Description

acceptedPaymentMethods Indicates whether you can checkout using the Buy Order API. If this column contains PAYPAL, you can use the Buy Order API to checkout and purchase the item. If this column is empty, you must use another method for checkout.
returnsAccepted Indicates whether the seller accepts returns for the item.
refundMethod An enumeration value that indicates how a buyer is refunded when an item is returned.
returnMethod An enumeration value that indicates the alternative methods for a full refund when an item is returned. This column had data if the seller offers the buyer an item replacement or exchange instead of a monetary refund.
returnShippingCostPayer The party responsible for the return shipping costs when an item is returned. This will be either buyer or seller.
returnPeriodValue The amount of time the buyer has to return the item after the purchase date. This can be shown in the number of years, months, days, hours, or minutes. If this value is '30', and the returnPeriodUnit value is 'DAY', the return period is 30 days.
returnPeriodUnit An enumeration value that indicates period of time being used to measure the duration, such as business days, months, or years. See the TimeDurationUnitEnum type for a list of possible time-measuring units.
restockingFeePercentage

The restocking fee percentage that the seller has set on the item. Sellers have the option of setting no restocking fee for an item, or they can set the percentage to 10, 15, or 20 percent. So, if the cost of the item was $100, and the restocking percentage was 20 percent, the buyer would be charged $20 to return that item, so instead of receiving a $100 refund, they would received $80 due to the restocking fee.

Values returned are: NoRestockingFee, Percent_10, Percent_15, and Percent_20

 

v1_beta.2.0

The following columns, which represent the available quantity of the item, were added to the Item feed file. The table below lists the new columns along with their description. These columns were added as the last 3 columns in the file in the order shown.

New Columns

Description

estimatedAvailableQuantityThe estimated number of the item that are available for purchase.
availabilityThresholdTypeIndicates that the seller has more that the 'quantity display preference' value in stock for this item. For details, see availabilityThresholdType.
availabilityThresholdThe 'display item quantity' threshold value the seller has set in the seller preferences on eBay.

Announcement - October 2017

Availability of OpenAPI Specification

This release of the Feed 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: https://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 Feed API 2 JSON specification (beta)

File download     Download Feed API 2 YAML specification (beta)

v1_beta.1.0

The following changes have been made to the Feed API.

Replaced the item_summary resource

The item_summary resource was replaced by the item resource. The new item resource returns all the data that the item_summary resource returned plus 10 additional fields, such as itemLocationCountry, availability, etc. Note: The aspects, such as color, size, etc., that were returned by the item_summary resource, are now returned in the localizedAspects field.

The table below compares the fields returned by the new item resource and the deprecated item_summary resource.

Fields Returned by the New item Resource

Fields Returned the item_summary Resource

itemId ItemId
title Title
imageUrl ImageUrl
category Category
categoryId CategoryId
buyingOptions  
sellerUsername SellerUsername
sellerFeedbackPercentage SellerFeedbackPercentage
sellerFeedbackScore SellerFeedbackScore
gtin GTIN
brand Brand
mpn MPN
epid  
conditionId ConditionId
condition Condition
priceValue PriceValue
priceCurrency PriceCurrency
primaryItemGroupId  
primaryItemGroupType  
itemEndDate ItemEndDate
sellerItemRevision  
itemLocationCountry  
localizedAspects  
sellerTrustLevel  
availability  
imageAlteringProhibited  
  AgeGroup (returned in localizedAspects)
  Gender (returned in localizedAspects)
  Material (returned in localizedAspects)
  Size (returned in localizedAspects)
  SizeType (returned in localizedAspects)
  Color (returned in localizedAspects)

Added new resources

The following lists the new resources in the Feed API. Each resource has one method, that returns a TSV_GZIP (tab separated value GZIP), which is a binary file.

The table below shows information about the new resources and methods.

Method

Resource

Method

Description

GET item getItemFeed Returns a TSV_GZIP Item feed file containing all the items that were listed on a specific day in a specific category. For each item, all the item details are returned, except for the item description.

https://api.ebay.com/buy/feed/v1_beta/item

GET item_description getItemDescriptionFeed Returns a TSV_GZIP Description feed file containing the descriptions of all the items that were listed on a specific day in a specific category.

https://api.ebay.com/buy/feed/v1_beta/item_description

 

Added new request header

The feed files are very large so the GZIP file must be returned in chunks. You specify the size of the chunks in bytes using the Range request header. The Content-range response header indicates where in the full resource this partial chunk of data belongs and the total number of bytes in the file. For more information about using these headers, see Retrieving a gzip feed file.

v1_beta.0.0

This is the initial BETA release of this API.

New methods

There is only one method for the initial release.

GET /item_summary