Skip to main content

GET/item

This method lets you download a TSV_GZIP (tab separated value gzip) Item feed file. The feed file contains all the items from all the child categories of the specified category. 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.

There are two types of item feed files generated:

  • A daily Item feed file containing all the newly listed items for a specific category, date, and marketplace (feed_scope = NEWLY_LISTED)
  • A weekly Item Bootstrap feed file containing all the items in a specific category and marketplace (feed_scope = ALL_ACTIVE)

Note: Filters are applied to the feed files. For details, see Feed File Filters. When curating the items returned, be sure to code as if these filters are not applied as they can be changed or removed in the future.
Note:The downloaded file will be gzipped automatically, so there is no reason to supply Accept-Encoding:gzip as a header. If this header is supplied, the downloaded file will be compressed twice, and this has no extra benefit.

Downloading feed files

Item feed files are binary gzip files. If the file is larger than 100 MB, the download must be streamed 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 Retrieve a gzip feed file.

In addition to the API, there is an open source Feed SDK written in Java that downloads, combines files into a single file when needed, and unzips the entire feed file. It also lets you specify field filters to curate the items in the file.

Note: A successful call will always return a TSV.GZIP file; however, unsuccessful calls generate errors that are returned in JSON format. For documentation purposes, the successful call response is shown below as JSON fields so that the value returned in each column can be explained. The order of the response fields shows the order of the columns in the feed file.

Restrictions

For a list of supported sites and other restrictions, see API Restrictions.

Input

Resource URI

GET https://api.ebay.com/buy/feed/v1_beta/item?
feed_scope=string&
category_id=string&
date=string

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

ParameterTypeDescription
feed_scopestringThis query parameter specifies the type of feed file to return.

Valid Values:
  • NEWLY_LISTED - Returns the daily Item feed file containing all Good 'Til Cancelled items that were listed on the day specified by the date parameter in the category specified by the category_id parameter.
  • ALL_ACTIVE - Returns the weekly Item Bootstrap feed file containing all the Good 'Til Cancelled items in the category specified by the category_id parameter.

    Note: Bootstrap files are generated every Tuesday and the file is available on Wednesday. However, the exact time the file is available can vary so we recommend you download the Bootstrap file on Thursday. The items in the file are the items that were in the specified category on Sunday.

Occurrence: Required

category_idstringThis query parameter specifies the eBay top-level category ID of the items to be returned in the feed file.

The list of eBay category IDs changes over time and category IDs are not the same across all the eBay marketplaces. To get a list of the top-level categories for a marketplace, you can use the Taxonomy API getCategoryTree method. This method retrieves the complete category tree for the marketplace. The top-level categories are identified by the categoryTreeNodeLevel field.

For example:
  "categoryTreeNodeLevel": 1

For details see Get Categories for Buy APIs.

Restriction: Must be a top-level (L1) category other than Real Estate. Items listed under Real Estate L1 categories are excluded from all feeds in all marketplaces.

Occurrence: Required

datestringThis query parameter specifies the date of the daily Item feed file (feed_scope=NEWLY_LISTED) you want to retrieve.

The date is required only for the daily Item feed file. If you specify a date for the Item Bootstrap file (feed_scope=ALL_ACTIVE), the date is ignored and the latest file is returned. The date the Item Bootstrap feed file was generated is returned in the Last-Modified response header.

The Item feed files are generated every day and there are 14 daily files available.

Note: The daily Item feed files are available each day after 9AM MST (US Mountain Standard Time), which is -7 hours UTC time.

There is a 48 hour latency when generating the Item feed files. This means you can download the file for July 10th on July 12 after 9AM MST.

For categories with a large number of items, the latency can be up to 72 hours.
Format: yyyyMMdd

Requirements:
  • Required when feed_scope=NEWLY_LISTED
  • Must be within 3-14 days in the past

Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
AcceptstringThe formats that the client accepts for the response.

A successful call will always return a TSV.GZIP file; however, unsuccessful calls generate errors that are returned in JSON format.

Default: application/json,text/tab-separated-values

Occurrence: Required

X-EBAY-C-MARKETPLACE-IDstringThe ID of the eBay marketplace where the item is hosted. This value is case sensitive.

For example:
  X-EBAY-C-MARKETPLACE-ID = EBAY_US

For a list of supported sites see, API Restrictions.

Occurrence: Required

RangestringThis header specifies the range in bytes of the chunks of the gzip file being returned.

Format: bytes=startpos-endpos

For example, the following retrieves the first 10 MBs of the feed file.

  Range bytes=0-10485760

For more information about using this header, see Retrieving a gzip feed file.

Maximum: 100 MB (10MB in the Sandbox)

Occurrence: Required

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/buy.item.feed

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
Content-rangeThe content-range response header indicates where in the full resource this partial chunk of data belongs. It returns the lower and upper values in bytes (specified by the Range header) of the chunk and the total size of the file being downloaded in bytes.

Maximum range: 100 MB

The following is an example of a content-range response, where 0-10 is the lower and upper limit in bytes and 1000 is the total size of the file in bytes.

  0-10/1000

The following example of a content-range response indicates the value of the Range header is invalid and a 416 status code is returned.

   */1000

For more information and examples, see Retrieving a gzip feed file.
Last-ModifiedReturns the generated date of the feed file, which will be the latest file available. For example:
Last-Modified  Wed, 21 Oct 2015 07:28:00 GMT

Response payload

Important: The successful response of this call is always a TSV_GZIP file. However, the response is shown as JSON fields for each column so that the value returned in each column can be explained. The order in which the response fields are listed is the order of the columns in the feed file.

{ /* ItemResponse */
"items" : [
{ /* Item */
"itemId" : "string",
"title" : "string",
"imageUrl" : "string",
"category" : "string",
"categoryId" : "string",
"buyingOptions" : "string",
"sellerUsername" : "string",
"sellerFeedbackPercentage" : "string",
"sellerFeedbackScore" : "string",
"gtin" : "string",
"brand" : "string",
"mpn" : "string",
"epid" : "string",
"conditionId" : "string",
"condition" : "string",
"priceValue" : "string",
"priceCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"primaryItemGroupId" : "string",
"primaryItemGroupType" : "string",
"itemEndDate" : "string",
"sellerItemRevision" : "string",
"itemLocationCountry" : "string",
"localizedAspects" : "string",
"sellerTrustLevel" : "SellerTrustLevelEnum : [TOP_RATED,ABOVE_STANDARD]",
"availability" : "AvailabilityEnum : [TEMPORARILY_UNAVAILABLE,AVAILABLE,UNAVAILABLE]",
"imageAlteringProhibited" : "boolean",
"estimatedAvailableQuantity" : "integer",
"availabilityThresholdType" : "AvailabilityThresholdEnum : [MORE_THAN]",
"availabilityThreshold" : "integer",
"returnsAccepted" : "boolean",
"returnPeriodValue" : "integer",
"returnPeriodUnit" : "TimeDurationUnitEnum : [YEAR,MONTH,DAY...]",
"refundMethod" : "RefundMethodEnum : [MONEY_BACK,MERCHANDISE_CREDIT]",
"returnMethod" : "ReturnMethodEnum : [REPLACEMENT,EXCHANGE]",
"returnShippingCostPayer" : "ReturnShippingCostPayerEnum : [SELLER,BUYER]",
"acceptedPaymentMethods" : "string",
"deliveryOptions" : "DeliveryOptionsEnum : [SHIP_TO_HOME,SELLER_ARRANGED_LOCAL_PICKUP,IN_STORE_PICKUP...]",
"shipToIncludedRegions" : "string",
"shipToExcludedRegions" : "string",
"inferredEpid" : "string",
"inferredGtin" : "string",
"inferredBrand" : "string",
"inferredMpn" : "string",
"inferredLocalizedAspects" : "string",
"additionalImageUrls" : "string",
"originalPriceValue" : "string",
"originalPriceCurrency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"discountAmount" : "string",
"discountPercentage" : "string",
"energyEfficiencyClass" : "string",
"qualifiedPrograms" : "string",
"lotSize" : "integer",
"lengthUnitOfMeasure" : "LengthUnitOfMeasureEnum : [INCH,FEET,CENTIMETER...]",
"packageWidth" : "string",
"packageHeight" : "string",
"packageLength" : "string",
"weightUnitOfMeasure" : "WeightUnitOfMeasureEnum : [POUND,KILOGRAM,OUNCE...]",
"packageWeight" : "string",
"shippingCarrierCode" : "string",
"shippingServiceCode" : "string",
"shippingType" : "string",
"shippingCost" : "string",
"shippingCostType" : "string",
"additionalShippingCostPerUnit" : "string",
"quantityUsedForEstimate" : "integer",
"unitPrice" : "string",
"unitPricingMeasure" : "string",
"legacyItemId" : "string",
"alerts" : "string",
"sellerAccountType" : "string",
"tyreLabelImageUrl" : "string",
"priorityListingPayload" : "string",
"itemCreationDate" : "string",
"itemWebUrl" : "string",
"defaultImageUrl" : "string",
"itemAffiliateWebUrl" : "string",
"ageGroup" : "string",
"color" : "string",
"pattern" : "string",
"size" : "string",
"gender" : "string",
"material" : "string",
"totalUnits" : "string",
"ecoParticipationFeeValue" : "string",
"ecoParticipationFeeCurrency" : "string",
"takeBackPolicyLabel" : "string",
"takeBackPolicyDescription" : "string",
"hazmatSignalWordId" : "string",
"hazmatSignalWord" : "string",
"hazmatStatementIds" : "string",
"hazmatStatementDescriptions" : "string",
"hazmatPictogramIds" : "string",
"hazmatPictogramDescriptions" : "string",
"hazmatPictogramImageUrls" : "string",
"hazmatAdditionalInformation" : "string",
"repairScore" : "string",
"conditionDescriptors" : "string",
"sellerUserId" : "string"
}
]
}

Response fields

Output container/fieldTypeDescription
itemsarray of Item

The container for the array of items returned by the getItemFeed method. The data in the file is tab separated and the first row is the header, which labels the columns and indicates the order of the values on each line. The header labels match the fields that are described in the Response fields section.

Occurrence: Conditional

items.itemIdstring

The unique identifier of an item in eBay RESTful format. An example would be v1|1**********2|4**********2.

Occurrence: Always

items.titlestring

The seller created title of the item. This text is 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"

Occurrence: Always

items.imageUrlstring

The URL to the primary image of the item. This is the URL of the largest image available based on what the seller submitted.

Occurrence: Always

items.categorystring

The label of the category. For example: Toys & Hobbies|Action Figures|Comic Book Heroes

Occurrence: Always

items.categoryIdstring

The ID of the category of the item. For example: The ID for Toys & Hobbies|Action Figures|Comic Book Heroes is 158671.

Occurrence: Always

items.buyingOptionsstring

A comma separated list of the purchase options available for the item. Currently the only supported option is FIXED_PRICE.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Always

items.sellerUsernamestring

The seller's eBay user name.

Occurrence: Always

items.sellerFeedbackPercentagestring

The percentage of the seller's total positive feedback.

Occurrence: Always

items.sellerFeedbackScorestring

The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller.

Occurrence: Always

items.gtinstring

The unique Global Trade Item Number of the item as defined by https://www.gtin.info. This can be a UPC (Universal Product Code), EAN (European Article Number), or an ISBN (International Standard Book Number) value.

Occurrence: Conditional

items.brandstring

The name brand of the item, such as Nike, Apple, etc.

Occurrence: Conditional

items.mpnstring

The manufacturer part number, which is a number that is used in combination with brand to identify a product.

Occurrence: Conditional

items.epidstring

The eBay product identifier of a product from the eBay product catalog. You can use this value in the Browse API search method to retrieve items for this product and in the Marketing API methods to retrieve 'also viewed' and 'also bought' products to encourage up-selling and cross-selling.

Occurrence: Conditional

items.conditionIdstring

The identifier of the condition of the item. For example, 1000 is the identifier for NEW. For a list of condition names and IDs, see Item Condition IDs and Names.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.conditionstring

The text describing the condition of the item. For a list of condition names, see Item Condition IDs and Names.

Occurrence: Conditional

items.priceValuestring

The price of the item, which can be a discounted price. If it is discounted, information about the discount is returned in the originalPriceValue, originalPriceCurrency, discountAmount, and discountPercentage columns.

Note: The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see the VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

items.priceCurrencyCurrencyCodeEnum

The currency used for the price of the item. Generally, this is the currency used by the country of the eBay site offering the item.

Occurrence: Always

items.primaryItemGroupIdstring

The unique identifier for the item group that contains this item. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Occurrence: Conditional

items.primaryItemGroupTypestring

The item group type. Supported value: SELLER_DEFINED_VARIATIONS, indicates that the item group was created by the seller.

Code so that your app gracefully handles any future changes to this list.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.itemEndDatestring

A timestamp that indicates the date and time an auction listing will end.

This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which can be converted into the local time of the buyer.

Occurrence: Conditional

items.sellerItemRevisionstring

An identifier generated/incremented when a seller revises the item. There are two types of item revisions:

  • Seller changes, such as changing the title
  • 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.

Occurrence: Conditional

items.itemLocationCountrystring

The country where the item is physically located.

Occurrence: Conditional

items.localizedAspectsstring

A semicolon separated list of the name/value pairs for the aspects of the item, which are Base64 encoded. The aspect label is separated by a pipe (|), the aspect name and value are separated by a colon (:) and the name/value pairs are separated by a semicolon (;).

Example without Label

   Encoded Format:
   encodedName:encodedValue;encodedName:encodedValue;encodedName:encodedValue

   Encoded Example (The delimiters are emphasized):
   U2l6ZQ==:WEw=;Q29sb3I=:UmVk;U2xlZXZlcw==:TG9uZw==

   Decoded:
   Size:XL;Color:Red;Sleeves:Long


Example with Label

   Encoded Format:
   encodedLabel|encodedName:encodedValue;encodedName:encodedValue;encodedLabel|

   Encoded Example (The delimiters are emphasized):
   UHJvZHVjdCBJZGVudGlmaWVycw==|R1RJTg==:MDE5MDE5ODA2NjYzMw==;QlJBTkQ=:QXBwbGU=;UHJvZHVjdCBLZXkgRmVhdHVyZXM=|TW9kZWw=:aVBob25lIDc=

   Decoded:
   Product Identifiers|GTIN:0190198066633;BRAND:Apple;Product Key Features|Model:iPhone 7

Note: The separators ( | : ; ) are not encoded. You must decode each label, name, and value separately. You cannot decode the entire string.

For more information, see Encoded Aspects in the Buying Integration Guide.

Occurrence: Conditional

items.sellerTrustLevelSellerTrustLevelEnum

An enumeration value representing the eBay status of the seller.

Valid Values: TOP_RATED, ABOVE_STANDARD, or an empty value.

An empty value indicates a return of anything other than TOP_RATED or ABOVE_STANDARD.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

items.availabilityAvailabilityEnum

An enumeration value representing the item's availability (possibility of being purchased).

Values:

  • AVAILABLE
  • TEMPORARILY_UNAVAILABLE
  • UNAVAILABLE
Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

items.imageAlteringProhibitedboolean

A boolean that indicates whether the images can be altered. If the value is true, you cannot modify the image.

Note: Due to image licensing agreements and other legal concerns, modification (including resizing) of some images is strictly prohibited. These images are for display as-is only.

Occurrence: Always

items.estimatedAvailableQuantityinteger

The estimated quantity of this item that are available for purchase. Because the quantity of an item can change several times within a second, it is very difficult to return the exact quantity. So instead of returning quantity, the estimated availability of the item is returned.

Note: If the seller of an item has the available threshold setting turned on, the value of this field will be null, and the availability of the item will instead be expressed through the availabilityThresholdType and availabilityThreshold fields.
Note: To see if a listing is available for purchase, review the itemEndDate and estimatedAvailablityStatus fields. If the item has an EndDate in the past, or the estimatedAvailabilityStatus is OUT_OF_STOCK, the item is unavailable for purchase.

Occurrence: Conditional

items.availabilityThresholdTypeAvailabilityThresholdEnum

This column has a value only when the seller sets their availability threshold preference. The value of this column will show MORE_THAN, which indicates that the seller has more than the available threshold preference in stock for this item. Because the quantity of an item can change several times within a second, it is very difficult to return the exact quantity.

Note: This field and the availabilityThreshold field will be returned as null if the actual quantity meets or drops below the threshold value, and then the buyer will want to look at the value in the estimatedAvailableQuantity field.

Occurrence: Conditional

items.availabilityThresholdinteger

This column has a value only when the seller sets their availability threshold preference. The value of this column will be "10", which is the threshold value.

Note: This field and the availabilityThresholdType field will be returned as null if the actual quantity meets or drops below the threshold value, and then the buyer will want to look at the value in the estimatedAvailableQuantity field.

Occurrence: Conditional

items.returnsAcceptedboolean

Indicates whether the seller accepts returns for the item.

Occurrence: Always

items.returnPeriodValueinteger

The amount of days that the buyer has to return the item after the purchase date. For example, if this value is '30', the return period is 30 days.

Occurrence: Conditional

items.returnPeriodUnitTimeDurationUnitEnum

An enumeration value that indicates the period of time being used to measure the duration, such as business days, months, or years.

TimeDurationUnitEnum is a common type shared by multiple eBay APIs and fields to express the time unit, but for return period duration, this value will always be DAY.

Occurrence: Conditional

items.refundMethodRefundMethodEnum

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.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.returnMethodReturnMethodEnum

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.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.returnShippingCostPayerReturnShippingCostPayerEnum

The party responsible for the return shipping costs when an item is returned.

Valid Values: BUYER or SELLER

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.acceptedPaymentMethodsstring

This field is returned empty. For a list of payment methods available for a marketplace, see eBay help pages or the actual View Item page.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Always

items.deliveryOptionsDeliveryOptionsEnum

A comma-separated list of available delivery options. This column lets you filter out items than cannot be shipped to the buyer.

Valid Values: SHIP_TO_HOME, SELLER_ARRANGED_LOCAL_PICKUP, IN_STORE_PICKUP, and PICKUP_DROP_OFF.

Code so that your app gracefully handles any future changes to this list.

Occurrence: Always

items.shipToIncludedRegionsstring

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

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.shipToExcludedRegionsstring

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

Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

items.inferredEpidstring

The ePID (eBay Product ID of a product in 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 actually provided an ePID at listing time for the item, the ePID value is returned in the epid column instead.

Occurrence: Conditional

items.inferredGtinstring

The GTIN (Global Trade Item Number) of the product as defined by https://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.

Occurrence: Conditional

items.inferredBrandstring

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.

Occurrence: Conditional

items.inferredMpnstring

The MPN (Manufacturer's Part Number) for the item, which has been programmatically determined by eBay. 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.

Occurrence: Conditional

items.inferredLocalizedAspectsstring

A semicolon separated list of the name/value pairs for the aspects of the item, which are Base64 encoded. These aspects have been programmatically determined by eBay. If the seller provided aspects for the item, the seller's values are returned in the localizedAspects column.

The aspect label is separated by a pipe (|), the aspect name and value are separated by a colon (:) and the name/value pairs are separated by a semicolon (;).

Example without Label

   Encoded Format:
   encodedName:encodedValue;encodedName:encodedValue;encodedName:encodedValue

   Encoded Example (The delimiters are emphasized):
   U2l6ZQ==:WEw=;Q29sb3I=:UmVk;U2xlZXZlcw==:TG9uZw==

   Decoded:
   Size:XL;Color:Red;Sleeves:Long


Example with Label

   Encoded Format:
   encodedLabel|encodedName:encodedValue;encodedName:encodedValue;encodedLabel|

   Encoded Example (The delimiters are emphasized):
   UHJvZHVjdCBJZGVudGlmaWVycw==|R1RJTg==:MDE5MDE5ODA2NjYzMw==;QlJBTkQ=:QXBwbGU=;UHJvZHVjdCBLZXkgRmVhdHVyZXM=|TW9kZWw=:aVBob25lIDc=

   Decoded:
   Product Identifiers|GTIN:0190198066633;BRAND:Apple;Product Key Features|Model:iPhone 7

Note: The separators ( | : ; ) are not encoded. You must decode each label, name, and value separately. You cannot decode the entire string.

For more information, see Encoded Aspects in the Buying Integration Guide.

Occurrence: Conditional

items.additionalImageUrlsstring

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.

Occurrence: Conditional

items.originalPriceValuestring

The original selling price of the item. This lets you surface a strikethrough price for the item.

Occurrence: Conditional

items.originalPriceCurrencyCurrencyCodeEnum

The currency of the originalPriceValue of the item and the discountAmount.

Occurrence: Conditional

items.discountAmountstring

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.

Occurrence: Conditional

items.discountPercentagestring

The calculated discount percentage. For example, if originalPriceValue is 70 and discountAmount is 14, this value will be 20.

Occurrence: Conditional

items.energyEfficiencyClassstring

Indicates the European energy efficiency rating (EEK) of the item. Data is returned in this column 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.

Occurrence: Conditional

items.qualifiedProgramsstring

A pipe separated list of the qualified programs available for the item.

Valid Values:

  • EBAY_PLUS: Indicates an item is eligible for 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.

    Note: eBay Plus is available only to buyers in Germany, Austria, and Australia marketplaces.
  • AUTHENTICITY_GUARANTEE: Indicates that the item is eligible for the eBay Authenticity Guarantee program. This program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers.
  • FEATURED: Indicates that an item is eligible to be placed in a Focus Category. Focus Categories are specific categories dedicated to a certain type of product that allow a seller to better reach their target audience and increase their sales.

Occurrence: Conditional

items.lotSizeinteger

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.

For example:

Item Lot Definition Lot Size
A package of 24 AA batteries A box of 10 packages 10
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.

Occurrence: Conditional

items.lengthUnitOfMeasureLengthUnitOfMeasureEnum

The unit of measurement used for the package dimensions, such as INCH, FEET, CENTIMETER, or METER.

Code so that your app gracefully handles any future changes to this list.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.packageWidthstring

The width of the shipping package that contains the item.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.packageHeightstring

The height of the shipping package that contains the item.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.packageLengthstring

The length of the shipping package that contains the item.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.weightUnitOfMeasureWeightUnitOfMeasureEnum

The unit of measurement used for the package weight, such as POUND, KILOGRAM, OUNCE, or GRAM.

Code so that your app gracefully handles any future changes to this list.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.packageWeightstring

The weight of the package that contains the item.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.shippingCarrierCodestring

The name of the shipping provider, such as FedEx, or USPS.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.shippingServiceCodestring

The type of shipping service. For example, USPS First Class.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.shippingTypestring

The type of a shipping option, such as EXPEDITED, ONE_DAY, STANDARD, ECONOMY, PICKUP, etc.

Occurrence: Conditional

items.shippingCoststring

The final shipping cost for all the items after all discounts are applied.

Note: The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see the VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Conditional

items.shippingCostTypestring

Indicates the class of the shipping cost.

Valid Values: FIXED or CALCULATED.

Occurrence: Conditional

items.additionalShippingCostPerUnitstring

Any per item additional shipping costs for a multi-item purchase. For example, let's say the shipping cost for a power cord is $3. But for an additional cord, the shipping cost is only $1. So if you bought 3 cords, the shippingCost would be $3 and this value would be $2 ($1 for each additional item).

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.quantityUsedForEstimateinteger

The number of items used when calculating the estimation information.

Important! This field no longer returns values and is scheduled for deprecation.

Occurrence: Conditional

items.unitPricestring

This is the price per unit for the item. Some European countries require listings for certain types of products to include the price per unit so buyers can accurately compare prices.

For example:

"unitPricingMeasure": "100g",
"unitPrice": {
  "value": "7.99",
  "currency": "GBP"

Occurrence: Conditional

items.unitPricingMeasurestring

The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item. This helps buyers compare prices.

For example, the following tells the buyer that the item is 7.99 per 100 grams.

"unitPricingMeasure": "100g",
"unitPrice": {
  "value": "7.99",
  "currency": "GBP"

Occurrence: Conditional

items.legacyItemIdstring

The unique identifier of the eBay listing that contains the item. This is the traditional/legacy ID that is often seen in the URL of the listing View Item page.

Occurrence: Always

items.alertsstring

A pipe-separated list of alerts available for the item.

For example, if the DELAYED_DELIVERY alert was returned for an item, it would indicate a delay in shipping by the seller.

Occurrence: Conditional

items.sellerAccountTypestring

A string value that specifies whether the seller is a business or an individual. This is determined when the seller registers with eBay. If the seller registers for a business account, the value returned in this field will be BUSINESS. If the seller registers for a private account, the value returned in this field will be INDIVIDUAL.

Note: 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.

Code so that your app gracefully handles any future changes to this list.

Valid Values: BUSINESS or INDIVIDUAL

Occurrence: Conditional

items.tyreLabelImageUrlstring

The URL to the image that shows the information on the tyre label.

Occurrence: Conditional

items.priorityListingPayloadstring

EPN (eBay Partner Network) publishers append this value to their affiliate tracking URL when using an EPN tracking link to track changes that occur to Priority Listing items.

Example:amdata=enc%3AAQAFAAAAkB1DmsmXf%2BqZ%2BCEMGdebW6oR75GCMdBmc4MCQ%2FCEPqgKHbT0jdWhPwfY5LdUs6HTaP0eBlwKE7Smy2eDslewF7l3xjwWxjqwzNAnsYgxn2PiGkTKbiQSQytFUiymdtANpk1qOnBOoMGMK%2BWsji7jYlvySSs9o9s24TxD6RqWZpNrltzOU7mfnv3H40SZ3YESzg%3D%3D

See Creating an EPN Tracking Link for information on EPN tracking links.

Occurrence: Conditional

items.itemCreationDatestring

A timestamp indicating when the item was created.

Format: UTC yyyy-MM-ddThh:mm:ss.sssZ

Occurrence: Always

items.itemWebUrlstring

The URL of the View Item page of the item.

For example:

Single SKU:
https://www.ebay.de/itm/2********0

MSKU:
https://www.ebay.com/itm/2********9?var=5********2

Occurrence: Conditional

items.defaultImageUrlstring

URL to the gallery or default image of the item. The other images of the item are returned in the additionalImageUrls field.

For example

https://i.ebayimg.com/00/s/M********w/z/W********p/$_1.JPG?set_id=8********F

Occurrence: Conditional

items.itemAffiliateWebUrlstring

The URL of the View Item page of the item, with the affiliate tracking ID appended to it.

For example

https://www.ebay.de/itm/2********0?mkevt=1&mkcid=1&mkrid=707-53477-19255-0&campid=CAMPAIGNID&toolid=2***6&customid=CUSTOMID

Occurrence: Conditional

items.ageGroupstring

The age group that the product is recommended for.

Valid values: newborn, infant, toddler, kids, adult.

Occurrence: Conditional

items.colorstring

The color of the item.

Occurrence: Conditional

items.patternstring

Text describing the pattern used on the item. For example, paisley.

Note: All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

items.sizestring

The size of the item.

Occurrence: Conditional

items.genderstring

In cases where items could vary by gender, this specifies for which gender the product is intended. Possible values include male, female, and unisex.

Occurrence: Conditional

items.materialstring

The material that the item is made of.

Occurrence: Conditional

items.totalUnitsstring

For an item that is priced by the unit, the total number of units that are on offer. For example, if the item is priced by the meter and 50 cm is on offer, the totalUnits would be 0.5 m.

Occurrence: Conditional

items.ecoParticipationFeeValuestring

The amount of the Eco Participation Fee, a fee paid toward the eventual disposal of the purchased item.

Occurrence: Conditional

items.ecoParticipationFeeCurrencystring

The currency in which the Eco Participation Fee for the item is paid.

Occurrence: Conditional

items.takeBackPolicyLabelstring

The seller-defined label of the TAKE_BACK custom policy for the item. A TAKE_BACK policy describes the seller's regulatory responsibility to take back a purchased item for disposal when the buyer purchases a new one.

Occurrence: Conditional

items.takeBackPolicyDescriptionstring

The seller-defined description of the TAKE_BACK custom policy for the item.

Occurrence: Conditional

items.hazmatSignalWordIdstring

The ID of the signal word for the hazardous material.

Occurrence: Conditional

items.hazmatSignalWordstring

The localized signal word for the hazardous material, such as 'Danger'.

Occurrence: Conditional

items.hazmatStatementIdsstring

The IDs of hazardous material statements, separated by the pipe symbol. For example:

H200|H221

Occurrence: Conditional

items.hazmatStatementDescriptionsstring

The Base64 encoded descriptions of hazardous material statements, separated by the pipe symbol. For example:

encoded(Unstable explosives)|encoded(Flammable gas)

Occurrence: Conditional

items.hazmatPictogramIdsstring

The IDs of hazardous material pictograms, separated by the pipe symbol. For example:

SGH01|SGH02

Occurrence: Conditional

items.hazmatPictogramDescriptionsstring

The Base64 encoded descriptions of hazardous material pictograms, separated by the pipe symbol. For example:

encoded(exploding bomb)|encoded(flame)

Occurrence: Conditional

items.hazmatPictogramImageUrlsstring

The image URLs of hazardous material pictograms, separated by the pipe symbol. For example:

https://img1|https://img2

Occurrence: Conditional

items.hazmatAdditionalInformationstring

Base64 encoded additional information about the hazardous material.

Occurrence: Conditional

items.repairScorestring

A score that describes how easy it is to repair the product. Score values range from 0.1 (hardest to repair) to 10.0 (easiest), always including a single decimal place.

Occurrence: Conditional

items.conditionDescriptorsstring

Note: Condition descriptors are currently only available for the following trading card categories:

  • Non-Sport Trading Card Singles
  • CCG Individual Cards
  • Sports Trading Card Singles

This field contains a list of the name/value pairs for the condition descriptors of the item, which are Base64 encoded. The descriptors are separated as follows:
  • Name and value pairs are separated by a colon :
    Name:Value

    Base64 encoding the above pair yields TmFtZQ==:VmFsdWU=
  • Multiple descriptors are separated by a semicolon ;
    Name1:Value1;Name2:Value2

    Base64 encoding the above multiple descriptors yields TmFtZTE=:VmFsdWUx;TmFtZTI=:VmFsdWUy
  • Multiple values are separated by a pipe |
    Name1:Value1|Value2|Value3;Name2:Value1|Value2|Value3

    Base64 encoding the above multiple values (for multiple descriptors) yields TmFtZTE=:VmFsdWUx|VmFsdWUy|VmFsdWUz;TmFtZTI=:VmFsdWUx|VmFsdWUy|VmFsdWUz
Note: The separators ( : ; | ) are not encoded. You must decode each name, and value or values separately. You cannot decode the entire string.
The name and value are numeric IDs that map to the name and value, respectively, of a condition descriptor. A condition descriptor name-value pair provides more information about an item's condition in a structured way. Descriptors are name-value attributes that can be either from a closed set or open text. For more information on the numeric IDs and their text equivalents, use the getItemConditionPolicies method of the Metadata API.

Occurrence: Conditional

items.sellerUserIdstring

The unique identifier of an eBay user across all eBay sites. This value does not change, even when a user changes their username.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
204No Content
This code is returned when there are no items that meet the criteria for this feed file. See Feed File Filters for details.
206Partial Content
400Bad request
403Forbidden
404Not found
416Range not satisfiable
500Internal server error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
13000API_FEEDREQUESTThe request contains data that is invalid. Correct the request and submit the call again. For help, see the API Reference documentation for this call.
13003API_FEEDREQUESTThe 'feed_scope' {feed_scope} submitted is invalid. Valid values: {feedScopes}
13004API_FEEDREQUESTThe 'category_id' {category_id} submitted is invalid. See the API documentation for help on how to find category IDs.
13005API_FEEDREQUESTThe 'date' {feedDate} submitted is invalid. Either the date format is wrong, or the files are not available for the specific date. Valid values: {earliestDate} to {latestDate} in the past. The format is yyyyMMdd.
13006API_FEEDAPPLICATIONThere was a problem with an eBay internal system or process. Wait a few minutes and retry the call. If that doesn't work, contact eBay Support.
13007API_FEEDREQUESTThe feed file requested cannot be found. It is possible the file requested is in the process of being generated. Either change the date or try the call again later.
13009API_FEEDREQUESTThe mandatory 'feed_scope' query parameter is missing. Valid values: {feedScopes}
13010API_FEEDREQUESTThe mandatory 'category_id' query parameter is missing.
13011API_FEEDREQUESTThe mandatory 'date' query parameter is missing. Valid values: {earliestDate} to {latestDate} days in the past. The format is yyyyMMdd.
13012API_FEEDREQUESTThe marketplace Id {marketplaceId} is invalid. Valid values: {allowedMarketplaces}
13013API_FEEDREQUESTThe mandatory 'X-EBAY-C-MARKETPLACE-ID' header is missing. Valid values: {allowedMarketplaces}
13014API_FEEDREQUESTThe marketplace Id {marketplaceId} is not supported. Valid values: {allowedMarketplaces}
13015API_FEEDREQUESTThe mandatory 'Range' request header is missing. For help, see the API Reference documentation for this call.
13016API_FEEDREQUESTThe 'Range' request header format is invalid. Format: 'bytes=start position-end position'. For help, see the API Reference documentation for this call.
13017API_FEEDREQUESTThe 'Range' header is invalid. Please verify that the start and end positions are correct. For help, see the API Reference documentation for this call.
13018API_FEEDREQUESTThe start position in the range header is invalid.
13019API_FEEDREQUESTThe end position in the range header is invalid.
13022API_FEEDREQUESTThe 'category_id' {category_id} submitted is not supported.
13023API_FEEDBUSINESSInsufficient permissions to access this API for the marketplace {marketplaceId}. Please contact eBay Technical Support for further assistance.
13024API_FEEDBUSINESSInsufficient permissions to access this API for the category {category_id}. Please contact eBay Technical Support for further assistance.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Download the Daily Item Feed File

This sample returns a GZIP file with items listed on September 18, 2018 in the Cameras & Photo category. In this example, the size of the file being returned is 240MB (251658240 bytes) and the request Range header specifies to return the first 10MB (10485760 bytes).

Input

The inputs are feed_scope=NEWLY_LISTED, category_id, and date URI parameters.

The request parameters are: Range bytes=0-10485760 and X-EBAY-C-MARKETPLACE-ID EBAY_US. For more information about using these headers, see HTTP request headers.

GEThttps://api.ebay.com/buy/feed/v1_beta/item?feed_scope=NEWLY_LISTED&category_id=625&date=20180918

Output

If the call is successful, the portion of the file specified by the Range header, is returned. The call returns a 206 HTTP status and the Content-range bytes=0-10485760/251658240 response header.

Sample 2: Download the Weekly Bootstrap Item Feed File

This sample returns the latest weekly Item Bootstrap feed file. It contains all the 'Good 'Til Cancelled' items in the category specified.

Note: Bootstrap files are generated every Tuesday and the file is available on Wednesday. However, the exact time the file is available can vary so we recommend you download the Bootstrap file on Thursday. The items in the file are the items that were in the specified category on Sunday.

Input

The inputs are feed_scope=ALL_ACTIVE and category_id URI parameters.

The request parameters are: Range bytes=0-10485760 and X-EBAY-C-MARKETPLACE-ID EBAY_US. For more information about using these headers, see HTTP request headers.

GEThttps://api.ebay.com/buy/feed/v1_beta/item?feed_scope=ALL_ACTIVE&category_id=625

Output

If the call is successful, the portion of the file specified by the Range header, is returned. The call returns a 206 HTTP status and the Content-range bytes=0-10485760/251658240 response header.

Note: You can use the Feed SDK to download the entire file and you can also apply filters.