Skip to main content

GET/item/{item_id}

This method retrieves the details of a specific item, such as description, price, category, all item aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery, and other information the buyer needs to make a purchasing decision.

The Buy APIs are designed to let you create an eBay shopping experience in your app or website. This means you will need to know when something, such as the availability, quantity, etc., has changed in any eBay item you are offering. This is easily achieved by setting the fieldgroups URI parameter to one of the following values:

  • COMPACT
    Reduces the response to only those fields necessary in order to determine if any item detail has changed. This field group must be used alone.
  • PRODUCT
    Adds fields to the default response that return information about the product/item. This field group may also be used in conjunction with ADDITIONAL_SELLER_DETAILS.
  • ADDITIONAL_SELLER_DETAILS
    Adds an additional field to the response that returns the seller's user ID. This field group may also be used in conjunction with PRODUCT.
For additional information, refer to fieldgroups.

Restrictions

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

eBay Partner Network: In order to be commissioned for your sales, you must use the URL returned in the itemAffiliateWebUrl field to forward your buyer to the ebay.com site.

Input

Resource URI

GET https://api.ebay.com/buy/browse/v1/item/{item_id}?

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
item_idstringThis path parameter specifies the unique RESTful identifier of the item being retrieved.

RESTful Item ID Format: v1|#|#

For a single SKU listing, pass in the item ID:
v1|2**********2|0
For a multi-SKU listing, pass in the identifier of the variation:
v1|1**********2|4**********2

For more information about item IDs for RESTful APIs, refer to Item ID legacy API compatibility overview in the Buying Integration Guide.

Occurrence: Required

fieldgroupsarray of stringThis parameter controls what is returned in the response. If this field is not set, the method returns all the details of the item.

Note: Multiple fieldgroups can be set and applied simultaneously. However, COMPACT must be used alone. Otherwise, an error will occur.
Valid Values:
  • PRODUCT
    This field group adds the product container to the response.
  • COMPACT
    This field group returns only the following fields which let you quickly check if the availability or price of the item has changed, if the item has been revised by the seller, or if an item's top-rated plus status has changed for items you have stored.
    • itemId
    • bidCount
    • currentBidPrice
    • eligibleForInlineCheckout
    • estimatedAvailabilities
    • gtin
    • itemAffiliateWebURL
    • itemCreationDate
    • ItemWebURL
    • legacyItemId
    • minimumPriceToBid
    • price
    • priorityListing
    • reservePriceMet
    • sellerItemRevision
    • shippingOptions
    • taxes
    • topRatedBuyingExperience
    • uniqueBidderCount
    For Example:
    To determine if a stored item's information is current, perform the following:
    1. Pass in the item ID and set fieldgroups to COMPACT.
      item/v1|4**********8|0?fieldgroups=COMPACT
    2. Do one of the following:
      • If sellerItemRevision is returned and a revision number for this item has not been stored, record the number and pass in the item ID in the getItem method to retrieve the most recent information.
      • If the revision number is different from the value you have stored, update the value and pass in the item ID in the getItem method to retrieve the most recent information.
      • If sellerItemRevision is not returned or has not changed, where needed, update the item information with the information returned in the response.
  • ADDITIONAL_SELLER_DETAILS
    This adds the userId field to the response.

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
Accept-LanguagestringThis header is used to indicate the natural language and locale preferred by the user for the response.

This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example:
  • When targeting the French locale of the Belgium marketplace, it is required to pass in fr-BE to specify this. If this locale is not specified, the language will default to Dutch.
  • When targeting the French locale of the Canadian marketplace, it is required to pass in fr-CA to specify this. If this locale is not specified, the language will default to English.

Occurrence: Conditional

X-EBAY-C-ENDUSERCTXstringThis header is required to support revenue sharing for eBay Partner Network and to improve the accuracy of shipping and delivery time estimations.

For additional information, refer to Use request headers in the Buying Integration Guide.

Occurrence: Optional

X-EBAY-C-MARKETPLACE-IDstringThis header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US.

Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.
See MarketplaceIdEnum for a list of supported marketplaces.

Occurrence: Strongly Recommended

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

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

This call has no response headers.

Response payload

{ /* Item */
"additionalImages" : [
{ /* Image */ }
],
"brand" : "string",
"color" : "string",
"epid" : "string",
"gender" : "string",
"gtin" : "string",
"image" :
{ /* Image */ },
"itemId" : "string",
"mpn" : "string",
"size" : "string",
"title" : "string",
}

Response fields

Output container/fieldTypeDescription
additionalImagesarray of Image

An array of containers with the URLs for the images that are in addition to the primary image. The primary image is returned in the image.imageUrl field.

Occurrence: Conditional

additionalImages.heightinteger

Reserved for future use.

Occurrence: Conditional

additionalImages.imageUrlstring

The URL of the image.

Occurrence: Always

additionalImages.widthinteger

Reserved for future use.

Occurrence: Conditional

addonServicesarray of AddonService

A list of add-on services that may be selected for the item or that may apply automatically.

Occurrence: Conditional

addonServices.selectionAddonServiceSelectionEnum

This field indicates whether the add-on service must be selected for the item.

Occurrence: Conditional

addonServices.serviceFeeConvertedAmount

The amount charged for the add-on service.

Occurrence: Conditional

addonServices.serviceFee.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

addonServices.serviceFee.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

addonServices.serviceFee.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

addonServices.serviceFee.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

addonServices.serviceIdstring

The ID number of the add-on service.

Occurrence: Conditional

addonServices.serviceTypeAddonServiceTypeEnum

The type of add-on service, such as AUTHENTICITY_GUARANTEE.

Occurrence: Conditional

adultOnlyboolean

This indicates if the item is for adults only. For more information about adult-only items on eBay, see Adult items policy for sellers and Adult-Only items on eBay for buyers.

Occurrence: Always

ageGroupstring

(Primary Item Aspect) The age group for which the product is recommended. For example, newborn, infant, toddler, kids, adult, etc. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

authenticityGuaranteeAuthenticityGuaranteeProgram

A container for information about whether an item, or the item group when returned for the getItemsByItemGroup method, is qualified for the Authenticity Guarantee program.

Note: The AUTHENTICITY_GUARANTEE value being returned by the getItemsByItemGroup method indicates that at least one item in the item group supports this program, but doesn't guarantee that the program is available to all items in the item group. To verify if the Authenticity Program is indeed available for the item that you are interested in, grab the items.itemId value for that item and use the getItem method. This method will return specific details on that particular item, including whether or not the Authenticity Guarantee Program is available for the item. Look for the qualifiedPrograms array and authenticityGuarantee container in the getItem response for this information.

Under the Authenticity Guarantee program, the seller ships a purchased item to a a third-party authenticator who inspects the item and provides an authentication card for it before the item is shipped to the buyer. If the buyer returns the item, the authenticator first verifies that it is the same item in the same condition before returning it to the seller.

Note: Refer to the Authenticity Guarantee page for more information.

Occurrence: Conditional

authenticityGuarantee.descriptionstring

An indication that the item is qualified for the Authenticity Guarantee program.

Occurrence: Conditional

authenticityGuarantee.termsWebUrlstring

The URL to the Authenticity Guarantee program terms of use.

Occurrence: Conditional

authenticityVerificationAuthenticityVerificationProgram

A container for information about whether an item is from a verified seller.

Occurrence: Conditional

authenticityVerification.descriptionstring

An indication that the item is from a verified seller.

Occurrence: Conditional

authenticityVerification.termsWebUrlstring

The URL to the Authenticity Verification program terms of use.

Occurrence: Conditional

availableCouponsarray of AvailableCoupon

A list of available coupons for the item.

Note: The Browse API only acknowledges item-level coupons. This array will only return coupons linked with an item. Store-level coupons offered by sellers across their entire store will not be returned.

Occurrence: Conditional

availableCoupons.constraintCouponConstraint

The limitations or restrictions of the coupon.

Occurrence: Conditional

availableCoupons.constraint.expirationDatestring

This timestamp provides the expiration date of the coded coupon.

Occurrence: Conditional

availableCoupons.discountAmountAmount

The discount amount after the coupon is applied.

Occurrence: Conditional

availableCoupons.discountAmount.currencyCurrencyCodeEnum

The list of valid currencies. Each ISO 4217 currency code includes the currency name followed by the numeric value.

For example, the Canadian Dollar code (CAD) would take the following form: Canadian Dollar, 124.

Occurrence: Conditional

availableCoupons.discountAmount.valuestring

The value of the discounted amount.

Occurrence: Conditional

availableCoupons.discountTypeCouponDiscountType

The type of discount that the coupon applies.

Occurrence: Conditional

availableCoupons.messagestring

A description of the coupon.

Note: The value returned in the termsWebUrl field should appear for all experiences when displaying coupons. The value in the availableCoupons.message field must also be included if returned in the API response.

Occurrence: Conditional

availableCoupons.redemptionCodestring

The coupon code.

Occurrence: Conditional

availableCoupons.termsWebUrlstring

The URL to the coupon terms of use.

Note: The value returned in the termsWebUrl field should appear for all experiences when displaying coupons. The value in the availableCoupons.message field must also be included if returned in the API response.

Occurrence: Conditional

bidCountinteger

This integer value indicates the total number of bids that have been placed against an auction item. This field is returned only for auction items.

Occurrence: Conditional

brandstring

(Primary Item Aspect) The name brand of the item, such as Nike, Apple, etc. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

buyingOptionsarray of string

A comma separated list of all the purchase options available for the item. The values returned are:

  • FIXED_PRICE - Indicates the buyer can purchase the item for a set price using the Buy It Now button.
  • AUCTION - Indicates the buyer can place a bid for the item. After the first bid is placed, this becomes a live auction item and is the only buying option for this item.
  • BEST_OFFER - Indicates the buyer can send the seller a price they're willing to pay for the item. The seller can accept, reject, or send a counter offer. For more information on how this works, see Making a Best Offer.
  • CLASSIFIED_AD - Indicates that the final sales transaction is to be completed outside of the eBay environment.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

categoryIdstring

The ID of the leaf category for this item. A leaf category is the lowest level in that category and has no children.

Occurrence: Always

categoryIdPathstring

The IDs of every category in the item path, separated by pipe characters, starting with the top level parent category.

For example, if an item belongs to the top level category Home and Garden (category ID 11700), followed by Home Improvement (159907), Heating, Cooling and Air (69197), and Thermostats (115947), the field would return the value: 11700|159907|69197|115947.

Occurrence: Always

categoryPathstring

Text that shows the category hierarchy of the item. For example: Computers/Tablets & Networking, Laptops & Netbooks, PC Laptops & Netbooks

Occurrence: Always

colorstring

(Primary Item Aspect) Text describing the color of the item. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

conditionstring

A short text description for the condition of the item, such as New or Used. For a list of condition names, see Item Condition IDs and Names.

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

Occurrence: Conditional

conditionDescriptionstring

A full text description for the condition of the item. This field elaborates on the value specified in the condition field and provides full details for the condition of the item.

Occurrence: Conditional

conditionDescriptorsarray of ConditionDescriptor

This array is used by the seller to provide additional information about the condition of an item in a structured format. Condition descriptors are name-value attributes that indicate details about a particular condition of an item.

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

Occurrence: Conditional

conditionDescriptors.namestring

The name of a condition descriptor. The value(s) for this condition descriptor is returned in the associated values array.

Occurrence: Conditional

conditionDescriptors.valuesarray of ConditionDescriptorValue

This array displays the value(s) for a condition descriptor (denoted by the associated name field), as well as any other additional information about the condition of the item.

Occurrence: Conditional

conditionDescriptors.values.additionalInfoarray of string

Additional information about the condition of an item as it relates to a condition descriptor. This array elaborates on the value specified in the content field and provides additional details about the condition of an item.

Occurrence: Conditional

conditionDescriptors.values.contentstring

The value for the condition descriptor indicated in the associated name field.

Occurrence: Conditional

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

currentBidPriceConvertedAmount

The container that returns 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 container will only be returned for auction items.

Occurrence: Conditional

currentBidPrice.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

currentBidPrice.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

currentBidPrice.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

currentBidPrice.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

descriptionstring

The full description of the item that was created by the seller. This can be plain text or rich content and can be very large.

Occurrence: Always

ecoParticipationFeeConvertedAmount

The Eco Participation fee, a fee paid by the buyer that is applied to the cost of the eventual disposal of the purchased item. The fee is remitted in full to the eco organization.

Currently, this value is required for electronic devices and furniture.

Occurrence: Conditional

ecoParticipationFee.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

ecoParticipationFee.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

ecoParticipationFee.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

ecoParticipationFee.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

eligibleForInlineCheckoutboolean

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

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

Occurrence: Always

enabledForGuestCheckoutboolean

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

Occurrence: Always

energyEfficiencyClassstring

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

Occurrence: Conditional

epidstring

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

Occurrence: Conditional

estimatedAvailabilitiesarray of EstimatedAvailability

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

Occurrence: Conditional

estimatedAvailabilities.availabilityThresholdinteger

This field is return only when the seller sets their 'display item quantity' preference to Display "More than 10 available" in your listing (if applicable). The value of this field will be "10", which is the threshold value.

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

Occurrence: Conditional

estimatedAvailabilities.availabilityThresholdTypeAvailabilityThresholdEnum

This field is return only when the seller sets their Display Item Quantity preference to Display "More than 10 available" in your listing (if applicable). The value of this field will be MORE_THAN. This indicates that the seller has more than the 'quantity display preference', which is 10, in stock for this item.

The following are the display item quantity preferences the seller can set.

  • Display "More than 10 available" in your listing (if applicable)
    • If the seller enables this preference, this field is returned as long as there are more than 10 of this item in inventory.
    • If the quantity is equal to 10 or drops below 10, this field is not returned and the estimated quantity of the item is returned in the estimatedAvailableQuantity field.
  • Display the exact quantity in your items
    If the seller enables this preference, the availabilityThresholdType and availabilityThreshold fields are not returned and the estimated quantity of the item is returned in the estimatedAvailableQuantity field.

    Note: Because the quantity of an item can change several times within a second, it is impossible to return the exact quantity.

Code so that your app gracefully handles any future changes to these preferences.

Occurrence: Conditional

estimatedAvailabilities.deliveryOptionsarray of DeliveryOptionsEnum

An array of available delivery options.

Valid Values: SHIP_TO_HOME, SELLER_ARRANGED_LOCAL_PICKUP, IN_STORE_PICKUP, PICKUP_DROP_OFF, or DIGITAL_DELIVERY

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

Occurrence: Conditional

estimatedAvailabilities.estimatedAvailabilityStatusAvailabilityStatusEnum

An enumeration value representing the inventory status of this item.

Note: Be sure to review the itemEndDate field to determine whether the item is available for purchase.

Valid Values: IN_STOCK, LIMITED_STOCK, or OUT_OF_STOCK

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

Occurrence: Conditional

estimatedAvailabilities.estimatedAvailableQuantityinteger

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

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

estimatedAvailabilities.estimatedRemainingQuantityinteger

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

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

estimatedAvailabilities.estimatedSoldQuantityinteger

The estimated number of this item that have been sold.

Occurrence: Conditional

genderstring

(Primary Item Aspect) The gender for the item. This is used for items that could vary by gender, such as clothing. For example: male, female, or unisex. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

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

hazardousMaterialsLabelsHazardousMaterialsLabels

Hazardous materials labels for the item.

Occurrence: Conditional

hazardousMaterialsLabels.additionalInformationstring

Additional information about the hazardous materials labels.

Occurrence: Conditional

hazardousMaterialsLabels.pictogramsarray of HazardPictogram

An array of hazard pictograms that apply to the item.

Occurrence: Conditional

hazardousMaterialsLabels.pictograms.pictogramDescriptionstring

The description of the hazard pictogram, such as Flammable.

Occurrence: Conditional

hazardousMaterialsLabels.pictograms.pictogramIdstring

The ID of the hazard pictogram.

Occurrence: Conditional

hazardousMaterialsLabels.pictograms.pictogramUrlstring

The URL of the hazard pictogram.

Occurrence: Conditional

hazardousMaterialsLabels.signalWordstring

The signal word for the hazardous materials label (such as Danger or Warning).

Occurrence: Conditional

hazardousMaterialsLabels.signalWordIdstring

The ID of the signal word for the hazardous materials label.

Occurrence: Conditional

hazardousMaterialsLabels.statementsarray of HazardStatement

An array of hazard statements for the item.

Occurrence: Conditional

hazardousMaterialsLabels.statements.statementDescriptionstring

A description of the nature of the hazard, such as whether the material is toxic if swallowed.

Occurrence: Conditional

hazardousMaterialsLabels.statements.statementIdstring

The ID of the hazard statement.

Occurrence: Conditional

imageImage

The URL of the primary image of the item. The other images of the item are returned in the additionalImages container.

Occurrence: Always

image.heightinteger

Reserved for future use.

Occurrence: Conditional

image.imageUrlstring

The URL of the image.

Occurrence: Always

image.widthinteger

Reserved for future use.

Occurrence: Conditional

inferredEpidstring

The ePID (eBay Product ID of a product from the eBay product catalog) for the item, which has been programmatically determined by eBay using the item's title, aspects, and other data.

If the seller provided an ePID for the item, the seller's value is returned in the epid field.

Note: This field is returned only for authorized Partners.

Occurrence: Conditional

itemAffiliateWebUrlstring

The URL to the View Item page of the item which includes the affiliate tracking ID.

Note: In order to receive commissions on sales, eBay Partner Network affiliates must use this URL to forward buyers to the listing on the eBay marketplace.
The itemAffiliateWebUrl is only returned if:

  • The marketplace through which the item is being viewed is part of the eBay Partner Network. Currently Singapore (EBAY_SG) is not supported.

    For additional information, refer to eBay Partner Network.
  • The seller enables affiliate tracking for the item by including the X-EBAY-C-ENDUSERCTX request header in the method.

Occurrence: Conditional

itemCreationDatestring

A timestamp that indicates the date and time an item listing was created.

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

itemEndDatestring

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

If a fixed-price listing has ended, this field indicates the date and time the listing ended.

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

itemIdstring

The unique RESTful identifier of the item.

Occurrence: Always

itemLocationAddress

The physical location of the item.

Occurrence: Conditional

itemLocation.addressLine1string

The first line of the street address.

Note: This is conditionally returned in the itemLocation field.

Occurrence: Conditional

itemLocation.addressLine2string

The second line of the street address. This field is not always used, but can be used for "Suite Number" or "Apt Number".

Occurrence: Conditional

itemLocation.citystring

The city of the address.

Occurrence: Always

itemLocation.countryCountryCodeEnum

The two-letter ISO 3166 standard code for the country of the address.

Occurrence: Always

itemLocation.countystring

The county of the address.

Occurrence: Conditional

itemLocation.postalCodestring

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

Occurrence: Conditional

itemLocation.stateOrProvincestring

The state or province of the address.

Note: This is conditionally returned in the itemLocation field.

Occurrence: Conditional

itemWebUrlstring

The URL of the View Item page of the item. This enables you to include a "Report Item on eBay" link that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay.

Occurrence: Always

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

listingMarketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace where the item is listed.

Occurrence: Always

localizedAspectsarray of TypedNameValue

An array of containers that show the complete list of the aspect name/value pairs that describe the variation of the item.

Occurrence: Conditional

localizedAspects.namestring

The text representing the name of the aspect for the name/value pair, such as Color.

Occurrence: Conditional

localizedAspects.typeValueTypeEnum

This indicates if the value being returned is a string or an array of values.

Valid Values:

  • STRING - Indicates the value returned is a string.
  • STRING_ARRAY - Indicates the value returned is an array of strings.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

localizedAspects.valuestring

The value of the aspect for the name/value pair, such as Red.

Occurrence: Conditional

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.

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

manufacturerCompanyAddress

Contact information for the manufacturer of the product.

Occurrence: Conditional

manufacturer.addressLine1string

The first line of the product manufacturer's street address.

Occurrence: Conditional

manufacturer.addressLine2string

The second line of the product manufacturer's street address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'.

Occurrence: Conditional

manufacturer.citystring

The city of the product manufacturer's street address.

Occurrence: Conditional

manufacturer.companyNamestring

The company name of the the product manufacturer.

Occurrence: Conditional

manufacturer.countryCountryCodeEnum

The two-letter ISO 3166 standard code for the country of the address.

Occurrence: Conditional

manufacturer.countryNamestring

The country name of the product manufacturer's street address.

Occurrence: Conditional

manufacturer.countystring

The county of the product manufacturer's street address.

Occurrence: Conditional

manufacturer.emailstring

The product manufacturer's business email address.

Occurrence: Conditional

manufacturer.phonestring

The product manufacturer's business phone number.

Occurrence: Conditional

manufacturer.postalCodestring

The postal code of the product manufacturer's street address.

Occurrence: Conditional

manufacturer.stateOrProvincestring

The state or province of the product manufacturer's street address.

Occurrence: Conditional

marketingPriceMarketingPrice

The original price and the discount amount and percentage.

Occurrence: Conditional

marketingPrice.discountAmountConvertedAmount

This container returns the monetary amount of the seller discount.

Occurrence: Conditional

marketingPrice.discountAmount.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

marketingPrice.discountAmount.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

marketingPrice.discountAmount.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

marketingPrice.discountAmount.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

marketingPrice.discountPercentagestring

This field expresses the percentage of the seller discount based on the value in the originalPrice container.

Occurrence: Conditional

marketingPrice.originalPriceConvertedAmount

This container returns the monetary amount of the item without the discount.

Occurrence: Conditional

marketingPrice.originalPrice.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

marketingPrice.originalPrice.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

marketingPrice.originalPrice.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

marketingPrice.originalPrice.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

marketingPrice.priceTreatmentPriceTreatmentEnum

Indicates the pricing treatment (discount) that was applied to the price of the item.

Note: The pricing treatment affects the way and where the discounted price can be displayed.

Occurrence: Conditional

materialstring

(Primary Item Aspect) Text describing what the item is made of. For example, silk. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

minimumPriceToBidConvertedAmount

The minimum price of the next bid, which means to place a bid it must be equal to or greater than this amount. If the auction hasn't received any bids, the minimum bid price is the same as the starting bid. Otherwise, the minimum bid price is equal to the current bid plus the bid increment. For details about bid increments, see Automatic bidding.

Occurrence: Conditional

minimumPriceToBid.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

minimumPriceToBid.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

minimumPriceToBid.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

minimumPriceToBid.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

mpnstring

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.

Occurrence: Conditional

patternstring

(Primary Item Aspect) Text describing the pattern used on the item. For example, paisley. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

paymentMethodsarray of PaymentMethod

The payment methods for the item, including the payment method types, brands, and instructions for the buyer.

Occurrence: Conditional

paymentMethods.paymentMethodTypePaymentMethodTypeEnum

The payment method type, such as credit card or cash.

Occurrence: Conditional

paymentMethods.paymentMethodBrandsarray of PaymentMethodBrand

The payment method brands, including the payment method brand type and logo image.

Occurrence: Conditional

paymentMethods.paymentMethodBrands.paymentMethodBrandTypePaymentMethodBrandEnum

The payment method brand, such as Visa or PayPal.

Occurrence: Conditional

paymentMethods.paymentMethodBrands.logoImageImage

The details of the logo image, such as the size and URL.

Note: Currently, only the imageUrl is populated.

Occurrence: Conditional

paymentMethods.paymentMethodBrands.logoImage.heightinteger

Reserved for future use.

Occurrence: Conditional

paymentMethods.paymentMethodBrands.logoImage.imageUrlstring

The URL of the image.

Occurrence: Always

paymentMethods.paymentMethodBrands.logoImage.widthinteger

Reserved for future use.

Occurrence: Conditional

paymentMethods.paymentInstructionsarray of PaymentInstructionEnum

The payment instructions for the buyer, such as cash in person or contact seller.

Occurrence: Conditional

paymentMethods.sellerInstructionsarray of SellerInstructionEnum

The seller instructions to the buyer, such as accepts credit cards or see description.

Occurrence: Conditional

priceConvertedAmount

The cost of just the item. This amount does not include any adjustments such as discounts or shipping costs.

Note: The price does include 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

price.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

price.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

price.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

price.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

priceDisplayConditionPriceDisplayConditionEnum

Indicates when in the buying flow the item's price can appear for minimum advertised price (MAP) items, which is the lowest price a retailer can advertise/show for this item.

Occurrence: Conditional

primaryItemGroupItemGroupSummary

The container that returns details of a primary item group (parent ID of an item group). An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

When an item group is created, one of the item variations, such as the red shirt size L, is chosen as the "parent". All the other items in the group are the children, such as the blue shirt size L, red shirt size M, etc.

Note: This container is returned only if the item_id in the request is for an item group (items with variations, such as color and size).

Occurrence: Conditional

primaryItemGroup.itemGroupAdditionalImagesarray of Image

An array of containers with the URLs for images that are in addition to the primary image of the item group. The primary image is returned in the itemGroupImage field.

Occurrence: Conditional

primaryItemGroup.itemGroupAdditionalImages.heightinteger

Reserved for future use.

Occurrence: Conditional

primaryItemGroup.itemGroupAdditionalImages.imageUrlstring

The URL of the image.

Occurrence: Always

primaryItemGroup.itemGroupAdditionalImages.widthinteger

Reserved for future use.

Occurrence: Conditional

primaryItemGroup.itemGroupHrefstring

The HATEOAS reference of the parent page of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Occurrence: Conditional

primaryItemGroup.itemGroupIdstring

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

Occurrence: Conditional

primaryItemGroup.itemGroupImageImage

The URL of the primary image of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Occurrence: Conditional

primaryItemGroup.itemGroupImage.heightinteger

Reserved for future use.

Occurrence: Conditional

primaryItemGroup.itemGroupImage.imageUrlstring

The URL of the image.

Occurrence: Always

primaryItemGroup.itemGroupImage.widthinteger

Reserved for future use.

Occurrence: Conditional

primaryItemGroup.itemGroupTitlestring

The title of the item that appears on the item group page. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Occurrence: Conditional

primaryItemGroup.itemGroupTypeItemGroupTypeEnum

An enumeration value that indicates the type of the item group. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc.

Occurrence: Conditional

primaryProductReviewRatingReviewRating

The container that returns the product rating details, such as review count, rating histogram, and average rating.

Occurrence: Conditional

primaryProductReviewRating.averageRatingstring

The average rating given to a product based on customer reviews.

Occurrence: Conditional

primaryProductReviewRating.ratingHistogramsarray of RatingHistogram

An array of containers for the product rating histograms that shows the review counts and the product rating.

Occurrence: Conditional

primaryProductReviewRating.ratingHistograms.countinteger

The total number of user ratings that the product has received.

Occurrence: Conditional

primaryProductReviewRating.ratingHistograms.ratingstring

This is the average rating for the product. As part of a product review, users rate the product. Products are rated from one star (terrible) to five stars (excellent), with each star having a corresponding point value - one star gets 1 point, two stars get 2 points, and so on. If a product had one four-star rating and one five-star rating, its average rating would be 4.5, and this is the value that would appear in this field.

Occurrence: Conditional

primaryProductReviewRating.reviewCountinteger

The total number of reviews for the item.

Occurrence: Conditional

priorityListingboolean

This field is returned as true if the listing is part of a Promoted Listing campaign. Promoted Listings are available to Above Standard and Top Rated sellers with recent sales activity.

For more information, see Promoted Listings.

Occurrence: Always

productProduct

The container that returns the product information of the item.

Occurrence: Conditional

product.additionalImagesarray of Image

An array of containers with the URLs for the product images that are in addition to the primary image.

Occurrence: Conditional

product.additionalImages.heightinteger

Reserved for future use.

Occurrence: Conditional

product.additionalImages.imageUrlstring

The URL of the image.

Occurrence: Always

product.additionalImages.widthinteger

Reserved for future use.

Occurrence: Conditional

product.additionalProductIdentitiesarray of AdditionalProductIdentity

An array of product identifiers associated with the item. This container is returned if the seller has associated the eBay Product Identifier (ePID) with the item and in the request fieldgroups is set to PRODUCT.

Occurrence: Conditional

product.additionalProductIdentities.productIdentityarray of ProductIdentity

An array of product identifier/value pairs for the product associated with the item. This is returned if the seller has associated the eBay Product Identifier (ePID) with the item and the request has fieldgroups set to PRODUCT.

The following table shows what is returned, based on the item information provided by the seller, when fieldgroups is set to PRODUCT.

ePID ProvidedProduct ID(s) ProvidedResponse
NoNoThe AdditionalProductIdentity container is not returned.
NoYesThe AdditionalProductIdentity container is not returned but the product identifiers specified by the seller are returned in the localizedAspects container.
YesNoThe AdditionalProductIdentity container is returned listing the product identifiers of the product.
YesYesThe AdditionalProductIdentity container is returned listing all the product identifiers of the product and the product identifiers specified by the seller are returned in the localizedAspects container.

Occurrence: Conditional

product.additionalProductIdentities.productIdentity.identifierTypestring

The type of product identifier, such as UPC and EAN.

Occurrence: Conditional

product.additionalProductIdentities.productIdentity.identifierValuestring

The product identifier value.

Occurrence: Conditional

product.aspectGroupsarray of AspectGroup

An array of containers for the product aspects. Each group contains the aspect group name and the aspect name/value pairs.

Occurrence: Conditional

product.aspectGroups.aspectsarray of Aspect

An array of the name/value pairs for the aspects of the product. For example: BRAND/Apple

Occurrence: Conditional

product.aspectGroups.aspects.localizedNamestring

The text representing the name of the aspect for the name/value pair, such as Brand.

Occurrence: Conditional

product.aspectGroups.aspects.localizedValuesarray of string

The text representing the value of the aspect for the name/value pair, such as Apple.

Occurrence: Conditional

product.aspectGroups.localizedGroupNamestring

The name of a group of aspects.

In the following example, Product Identifiers and Process are product aspect group names. Under the group name are the product aspect name/value pairs.

Product Identifiers
   Brand/Apple
   Product Family/iMac

Processor
   Processor Type/Intel
   Processor Speed/3.10

Occurrence: Conditional

product.brandstring

The brand associated with product. To identify the product, this is always used along with MPN (manufacturer part number).

Occurrence: Conditional

product.descriptionstring

The rich description of an eBay product, which might contain HTML.

Occurrence: Conditional

product.gtinsarray of string

An array of all the possible GTINs values associated with the product. A GTIN is a 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

product.imageImage

The primary image of the product. This is often a stock photo.

Occurrence: Conditional

product.image.heightinteger

Reserved for future use.

Occurrence: Conditional

product.image.imageUrlstring

The URL of the image.

Occurrence: Always

product.image.widthinteger

Reserved for future use.

Occurrence: Conditional

product.mpnsarray of string

An array of all possible MPN values associated with the product. A MPNs is manufacturer part number of the product. To identify the product, this is always used along with brand.

Occurrence: Conditional

product.titlestring

The title of the product.

Occurrence: Conditional

productFicheWebUrlstring

The URL of a page containing the manufacturer's specification of this item, which helps buyers make a purchasing decision. This information is available only for items that include the European energy efficiency rating (EEK) but is not available for all items with an EEK rating and is returned only if this information is available. The EEK rating of the item is returned in the energyEfficiencyClass field.

Occurrence: Conditional

productSafetyLabelsProductSafetyLabels

This container provides product safety labels which were provided by the seller, for the listing.

The getProductSafetyLabels method of the Sell Metadata API can be used to retrieve the full set of available Product Safety pictogram labels and safety statements.

Occurrence: Conditional

productSafetyLabels.pictogramsarray of ProductSafetyLabelPictogram

An array of seller provided comma-separated string values that provides identifier, URL, and description for one or more pictograms associated with the listing.

Occurrence: Conditional

productSafetyLabels.pictograms.pictogramDescriptionstring

The description of the safety label pictogram.

Occurrence: Conditional

productSafetyLabels.pictograms.pictogramIdstring

The identifier of the safety label pictogram.

Occurrence: Conditional

productSafetyLabels.pictograms.pictogramUrlstring

The URL of the safety label pictogram.

Occurrence: Conditional

productSafetyLabels.statementsarray of ProductSafetyLabelStatement

An array of seller provided comma-separated string values that provide identifier and description for one or more product safety statements associated with the listing.

Occurrence: Conditional

productSafetyLabels.statements.statementDescriptionstring

A description of the nature of the product safety label statement.

Occurrence: Conditional

productSafetyLabels.statements.statementIdstring

The identifier of the product safety label statement.

Occurrence: Conditional

qualifiedProgramsarray of string

An array of the qualified programs available for the item, or for the item group when returned for the getItemsByItemGroup method, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION.

Note: The AUTHENTICITY_GUARANTEE value being returned by the getItemsByItemGroup method indicates that at least one item in the item group supports this program, but doesn't guarantee that the program is available to all items in the item group. To verify if the Authenticity Program is indeed available for the item that you are interested in, grab the items.itemId value for that item and use the getItem method. This method will return specific details on that particular item, including whether or not the Authenticity Guarantee Program is available for the item. Look for the qualifiedPrograms array and authenticityGuarantee container in the getItem response for this information.

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

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

The eBay Authenticity Guarantee program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers.

Occurrence: Conditional

quantityLimitPerBuyerinteger

The maximum number for a specific item that one buyer can purchase.

Occurrence: Conditional

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

reservePriceMetboolean

This indicates if the reserve price of the item has been met. A reserve price is set by the seller and is the minimum amount the seller is willing to sell the item for.

If the highest bid is not equal to or higher than the reserve price when the auction ends, the listing ends and the item is not sold.

Note: This is returned only for auctions that have a reserve price.

Occurrence: Conditional

responsiblePersonsarray of ResponsiblePerson

This array provides information about one or more EU-based Responsible Persons or entities associated with the listing.

Occurrence: Conditional

responsiblePersons.addressLine1string

The first line of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.addressLine2string

The second line of the Responsible Person's address. This field is not always used, but can be used for secondary address information such as 'Suite Number' or 'Apt Number'.

Occurrence: Conditional

responsiblePersons.citystring

The city of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.companyNamestring

The name of the the Responsible Person or entity.

Occurrence: Conditional

responsiblePersons.countryCountryCodeEnum

The two-letter ISO 3166 standard of the country of the address.

Occurrence: Conditional

responsiblePersons.countryNamestring

The country name of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.countystring

The county of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.emailstring

The email of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.phonestring

The phone number of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.postalCodestring

The postal code of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.stateOrProvincestring

The state or province of the Responsible Person's street address.

Occurrence: Conditional

responsiblePersons.typesarray of ResponsiblePersonTypeEnum

The type(s) associated with the Responsible Person or entity.

Occurrence: Conditional

returnTermsItemReturnTerms

The container that returns an overview of the seller's return policy.

Occurrence: Conditional

returnTerms.extendedHolidayReturnsOfferedboolean

This indicates if the seller has enabled the Extended Holiday Returns feature on the item. Extended Holiday Returns are only applicable during the US holiday season, and gives buyers extra time to return an item. This 'extra time' will typically extend beyond what is set through the returnPeriod value.

Occurrence: Conditional

returnTerms.refundMethodRefundMethodEnum

An enumeration value that indicates how a buyer is refunded when an item is returned.

Valid Values: MONEY_BACK or MERCHANDISE_CREDIT

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

Occurrence: Conditional

returnTerms.restockingFeePercentagestring

This string field indicates 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 receive $80 due to the restocking fee.

Occurrence: Conditional

returnTerms.returnInstructionsstring

Text written by the seller describing what the buyer needs to do in order to return the item.

Occurrence: Conditional

returnTerms.returnMethodReturnMethodEnum

An enumeration value that indicates the alternative methods for a full refund when an item is returned. This field is returned if the seller offers the buyer an item replacement or exchange instead of a monetary refund.

Valid Values:

  • REPLACEMENT - Indicates that the buyer has the option of receiving money back for the returned item, or they can choose to have the seller replace the item with an identical item.
  • EXCHANGE - Indicates that the buyer has the option of receiving money back for the returned item, or they can exchange the item for another similar item.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

returnTerms.returnPeriodTimeDuration

The amount of time the buyer has to return the item after the purchase date.

Occurrence: Conditional

returnTerms.returnPeriod.unitTimeDurationUnitEnum

An enumeration value that indicates the units of the time span (e.g., HOURS). The enumeration value in this field defines the period of time being used to measure the duration.

Refer to TimeDurationUnitEnum for the list of supported values.

Occurrence: Conditional

returnTerms.returnPeriod.valueinteger

Retrieves the duration of the time span (no units). The value in this field indicates the number of years, months, days, hours, or minutes in the defined period.

Occurrence: Conditional

returnTerms.returnsAcceptedboolean

Indicates whether the seller accepts returns for the item.

Occurrence: Conditional

returnTerms.returnShippingCostPayerReturnShippingCostPayerEnum

This enumeration value indicates whether the buyer or seller is responsible for return shipping costs when an item is returned.

Valid Values:

  • SELLER - Indicates the seller will pay for the shipping costs to return the item.
  • BUYER - Indicates the buyer will pay for the shipping costs to return the item.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

sellerSellerDetail

The container that returns basic and detailed about the seller of the item, such as name, feedback score, and contact information.

Occurrence: Always

seller.feedbackPercentagestring

The percentage of the total positive feedback.

Occurrence: Always

seller.feedbackScoreinteger

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

Occurrence: Always

seller.sellerAccountTypestring

This 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 the following 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, EBAY_PL

Valid Values: BUSINESS or INDIVIDUAL

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

Occurrence: Conditional

seller.sellerLegalInfoSellerLegalInfo

The container with the seller's contact info and fields that are required by law.

Occurrence: Conditional

seller.sellerLegalInfo.emailstring

The seller's business email address.

Occurrence: Conditional

seller.sellerLegalInfo.faxstring

The seller' business fax number.

Occurrence: Conditional

seller.sellerLegalInfo.imprintstring

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.

Occurrence: Conditional

seller.sellerLegalInfo.legalContactFirstNamestring

The seller's first name.

Occurrence: Conditional

seller.sellerLegalInfo.legalContactLastNamestring

The seller's last name.

Occurrence: Conditional

seller.sellerLegalInfo.namestring

The name of the seller's business.

Occurrence: Conditional

seller.sellerLegalInfo.phonestring

The seller's business phone number.

Occurrence: Conditional

seller.sellerLegalInfo.registrationNumberstring

The seller's registration number. This is information used by some countries.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddressLegalAddress

The container that returns the seller's address to be used to contact them.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.addressLine1string

The first line of the street address.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.addressLine2string

The second line of the street address. This field is not always used, but can be used for 'Suite Number' or 'Apt Number'.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.citystring

The city of the address.

Occurrence: Always

seller.sellerLegalInfo.sellerProvidedLegalAddress.countryCountryCodeEnum

The two-letter ISO 3166 standard code for the country of the address.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.countryNamestring

The name of the country of the address.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.countystring

The name of the county of the address.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.postalCodestring

The postal code of the address.

Occurrence: Conditional

seller.sellerLegalInfo.sellerProvidedLegalAddress.stateOrProvincestring

The state or province of the address.

Occurrence: Always

seller.sellerLegalInfo.termsOfServicestring

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.

Occurrence: Conditional

seller.sellerLegalInfo.vatDetailsarray of VatDetail

An array of the seller's VAT (value added tax) IDs and the issuing country. VAT is a tax added by some European countries.

Occurrence: Conditional

seller.sellerLegalInfo.vatDetails.issuingCountryCountryCodeEnum

The two-letter ISO 3166 standard of the country issuing the seller's VAT (value added tax) ID. VAT is a tax added by some European countries.

Occurrence: Conditional

seller.sellerLegalInfo.vatDetails.vatIdstring

The seller's VAT (value added tax) ID. VAT is a tax added by some European countries.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperatorEconomicOperator

Provides required information about the manufacturer and/or supplier of the item.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.companyNamestring

The company name of the registered Economic Operator.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.addressLine1string

The first line of the registered Economic Operator's street address.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.addressLine2string

The second line, if any, of the registered Economic Operator's street address. This field is not always used, but can be used for 'Suite Number' or 'Apt Number'.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.citystring

The city of the registered Economic Operator's street address.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.stateOrProvincestring

The state or province of the registered Economic Operator's street address.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.postalCodestring

The postal code of the registered Economic Operator's street address.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.countrystring

The two-letter ISO 3166 standard abbreviation of the country of the registered Economic Operator's address.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.phonestring

The registered Economic Operator's business phone number.

Occurrence: Conditional

seller.sellerLegalInfo.economicOperator.emailstring

The registered Economic Operator's business email address.

Occurrence: Conditional

seller.sellerLegalInfo.weeeNumberstring

The Waste Electrical and Electronic Equipment (WEEE) registration number required for any seller to place electrical and electronic equipment on the market in Germany. This manufacturer number is assigned to the first distributors of electrical and electronic equipment and comprises a country code and an 8-digit sequence of digits (e.g. “WEEE Reg. No. DE 12345678”).

Occurrence: Conditional

seller.userIdstring

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

seller.usernamestring

The user name created by the seller for use on eBay.

Occurrence: Always

sellerCustomPoliciesarray of SellerCustomPolicy

A list of the custom policies that are applied to a listing.

Occurrence: Conditional

sellerCustomPolicies.descriptionstring

The seller-defined description of the policy.

Occurrence: Conditional

sellerCustomPolicies.labelstring

The seller-defined label for an individual custom policy.

Occurrence: Conditional

sellerCustomPolicies.typeSellerCustomPolicyTypeEnum

The type of custom policy, such as PRODUCT_COMPLIANCE or TAKE_BACK.

Occurrence: Conditional

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. This means you cannot use this value to determine if the quantity has changed.

Occurrence: Conditional

shippingOptionsarray of ShippingOption

An array of shipping options containers that have the details about cost, carrier, etc. of one shipping option.

Note: For items with calculated shipping, this array is only returned if the X-EBAY-C-ENDUSERCTX header is supplied.

Occurrence: Conditional

shippingOptions.additionalShippingCostPerUnitConvertedAmount

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

Occurrence: Conditional

shippingOptions.additionalShippingCostPerUnit.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

shippingOptions.additionalShippingCostPerUnit.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

shippingOptions.additionalShippingCostPerUnit.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.additionalShippingCostPerUnit.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

shippingOptions.cutOffDateUsedForEstimatestring

The deadline date that the item must be purchased by in order to be received by the buyer within the delivery window ( maxEstimatedDeliveryDate and minEstimatedDeliveryDate fields). This field is returned only for items that are eligible for 'Same Day Handling'. For these items, the value of this field is what is displayed in the Delivery line on the View Item page.

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

Occurrence: Conditional

shippingOptions.fulfilledThroughFulfilledThroughEnum

If the item is being shipped by the eBay Global Shipping program, this field returns GLOBAL_SHIPPING.

If the item is being shipped using the eBay International Shipping program, this field returns INTERNATIONAL_SHIPPING.

Otherwise, this field is null.

Occurrence: Conditional

shippingOptions.guaranteedDeliveryboolean

Although this field is still returned, it can be ignored since eBay Guaranteed Delivery is no longer a supported feature on any marketplace. This field may get removed from the schema in the future.

Occurrence: Conditional

shippingOptions.importChargesConvertedAmount

The Global Shipping Program import charges for this item.

Occurrence: Conditional

shippingOptions.importCharges.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

shippingOptions.importCharges.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

shippingOptions.importCharges.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.importCharges.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

shippingOptions.maxEstimatedDeliveryDatestring

The end date of the delivery window (latest projected delivery date). This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer.

Note: For the best accuracy, always include the location of where the item is be shipped in the contextualLocation values of the X-EBAY-C-ENDUSERCTX request header.

Occurrence: Conditional

shippingOptions.minEstimatedDeliveryDatestring

The start date of the delivery window (earliest projected delivery date). This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer.

Note: For the best accuracy, always include the location of where the item is be shipped in the contextualLocation values of the X-EBAY-C-ENDUSERCTX request header.

Occurrence: Conditional

shippingOptions.quantityUsedForEstimateinteger

The number of items used when calculating the estimation information.

Occurrence: Conditional

shippingOptions.shippingCarrierCodestring

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

Occurrence: Always

shippingOptions.shippingCostConvertedAmount

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

Note: The cost does include 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 cost. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

shippingOptions.shippingCost.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

shippingOptions.shippingCost.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

shippingOptions.shippingCost.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.shippingCost.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

shippingOptions.shippingCostTypestring

Indicates the class of the shipping cost.

Valid Values: FIXED or CALCULATED

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

Occurrence: Always

shippingOptions.shippingServiceCodestring

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

Occurrence: Always

shippingOptions.shipToLocationUsedForEstimateShipToLocation

The container that returns the country and postal code of where the item is to be shipped. These values come from the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header. If the header is not submitted, marketplace is used.

Occurrence: Conditional

shippingOptions.shipToLocationUsedForEstimate.countryCountryCodeEnum

The two-letter ISO 3166 standard of the country for where the item is to be shipped.

Occurrence: Conditional

shippingOptions.shipToLocationUsedForEstimate.postalCodestring

The zip code (postal code) for where the item is to be shipped.

Occurrence: Conditional

shippingOptions.trademarkSymbolstring

Any trademark symbol, such as ™ or ®, that needs to be shown in superscript next to the shipping service name.

Occurrence: Conditional

shippingOptions.typestring

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

Occurrence: Always

shipToLocationsShipToLocations

The container that returns the geographic regions to be included and excluded that define where the item can be shipped.

Occurrence: Conditional

shipToLocations.regionExcludedarray of ShipToRegion

An array of containers that express the large geographical regions, countries, state/provinces, or special locations within a country where the seller is not willing to ship to.

Occurrence: Conditional

shipToLocations.regionExcluded.regionIdstring

The unique identifier of the shipping region. The value returned here is dependent on the corresponding regionType value. The regionId value for a region does not vary based on the eBay marketplace. However, the corresponding regionName value for a region is a localized, text-based description of the shipping region.

If the regionType value is WORLDWIDE, the regionId value will also be WORLDWIDE.

If the regionType value is WORLD_REGION, the regionId value will be one of the following: AFRICA, AMERICAS, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EUROPEAN_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, SOUTH_AMERICA, SOUTHEAST_ASIA or CHANNEL_ISLANDS.

If the regionType value is COUNTRY, the regionId value will be the two-letter code for the country, as defined in the ISO 3166 standard.

If the regionType value is STATE_OR_PROVINCE, the regionId value will either be the two-letter code for US states and DC (as defined on this Social Security Administration page), or the two-letter code for Canadian provinces (as defined by this Canada Post page).

If the regionType value is COUNTRY_REGION, the regionId value may be one of following: _AH (if a seller is not willing to ship to Alaska/Hawaii), _PR (if the seller is not willing to ship to US Protectorates), _AP (if seller is not willing to ship to a US Army or Fleet Post Office), and PO_BOX (if the seller is not willing to ship to a Post Office Box).

Occurrence: Conditional

shipToLocations.regionExcluded.regionNamestring

A localized text string that indicates the name of the shipping region. The value returned here is dependent on the corresponding regionType value.

If the regionType value is WORLDWIDE, the regionName value will show Worldwide.

If the regionType value is WORLD_REGION, the regionName value will be a localized text string for one of the following large geographical regions: Africa, Americas, Asia, Australia, Central America and Caribbean, Europe, European Union, Greater China, Middle East, North America, Oceania, South America, Southeast Asia, or Channel Islands.

If the regionType value is COUNTRY, the regionName value will be a localized text string for any country in the world.

If the regionType value is STATE_OR_PROVINCE, the regionName value will be a localized text string for any US state or Canadian province.

If the regionType value is COUNTRY_REGION, the regionName value may be a localized version of one of the following: Alaska/Hawaii, US Protectorates, APO/FPO (Army or Fleet Post Office), or PO BOX.

Occurrence: Conditional

shipToLocations.regionExcluded.regionTypeRegionTypeEnum

An enumeration value that indicates the level or type of shipping region.

Valid Values:

  • COUNTRY_REGION - Indicates the region is a domestic region or special location within a country.
  • STATE_OR_PROVINCE - Indicates the region is a state or province within a country, such as California or New York in the US, or Ontario or Alberta in Canada.
  • COUNTRY - Indicates the region is a single country.
  • WORLD_REGION - Indicates the region is a world region, such as Africa, the Middle East, or Southeast Asia.
  • WORLDWIDE - Indicates the region is the entire world. This value is only applicable for included shiping regions, and not excluded shipping regions.
For more detail on the actual regionName/regionId values that will be returned based on the regionType value, see the regionId and/or regionName field descriptions.

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

Occurrence: Conditional

shipToLocations.regionIncludedarray of ShipToRegion

An array of containers that express the large geographical regions, countries, or state/provinces within a country where the seller is willing to ship to. Prospective buyers must look at the shipping regions under this container, as well as the shipping regions that are under the regionExcluded to see where the seller is willing to ship items. Sellers can specify that they ship 'Worldwide', but then add several large geographical regions (e.g. Asia, Oceania, Middle East) to the exclusion list, or sellers can specify that they ship to Europe and Africa, but then add several individual countries to the exclusion list.

Occurrence: Conditional

shipToLocations.regionIncluded.regionIdstring

The unique identifier of the shipping region. The value returned here is dependent on the corresponding regionType value. The regionId value for a region does not vary based on the eBay marketplace. However, the corresponding regionName value for a region is a localized, text-based description of the shipping region.

If the regionType value is WORLDWIDE, the regionId value will also be WORLDWIDE.

If the regionType value is WORLD_REGION, the regionId value will be one of the following: AFRICA, AMERICAS, ASIA, AUSTRALIA, CENTRAL_AMERICA_AND_CARIBBEAN, EUROPE, EUROPEAN_UNION, GREATER_CHINA, MIDDLE_EAST, NORTH_AMERICA, OCEANIA, SOUTH_AMERICA, SOUTHEAST_ASIA or CHANNEL_ISLANDS.

If the regionType value is COUNTRY, the regionId value will be the two-letter code for the country, as defined in the ISO 3166 standard.

If the regionType value is STATE_OR_PROVINCE, the regionId value will either be the two-letter code for US states and DC (as defined on this Social Security Administration page), or the two-letter code for Canadian provinces (as defined by this Canada Post page).

If the regionType value is COUNTRY_REGION, the regionId value may be one of following: _AH (if a seller is not willing to ship to Alaska/Hawaii), _PR (if the seller is not willing to ship to US Protectorates), _AP (if seller is not willing to ship to a US Army or Fleet Post Office), and PO_BOX (if the seller is not willing to ship to a Post Office Box).

Occurrence: Conditional

shipToLocations.regionIncluded.regionNamestring

A localized text string that indicates the name of the shipping region. The value returned here is dependent on the corresponding regionType value.

If the regionType value is WORLDWIDE, the regionName value will show Worldwide.

If the regionType value is WORLD_REGION, the regionName value will be a localized text string for one of the following large geographical regions: Africa, Americas, Asia, Australia, Central America and Caribbean, Europe, European Union, Greater China, Middle East, North America, Oceania, South America, Southeast Asia, or Channel Islands.

If the regionType value is COUNTRY, the regionName value will be a localized text string for any country in the world.

If the regionType value is STATE_OR_PROVINCE, the regionName value will be a localized text string for any US state or Canadian province.

If the regionType value is COUNTRY_REGION, the regionName value may be a localized version of one of the following: Alaska/Hawaii, US Protectorates, APO/FPO (Army or Fleet Post Office), or PO BOX.

Occurrence: Conditional

shipToLocations.regionIncluded.regionTypeRegionTypeEnum

An enumeration value that indicates the level or type of shipping region.

Valid Values:

  • COUNTRY_REGION - Indicates the region is a domestic region or special location within a country.
  • STATE_OR_PROVINCE - Indicates the region is a state or province within a country, such as California or New York in the US, or Ontario or Alberta in Canada.
  • COUNTRY - Indicates the region is a single country.
  • WORLD_REGION - Indicates the region is a world region, such as Africa, the Middle East, or Southeast Asia.
  • WORLDWIDE - Indicates the region is the entire world. This value is only applicable for included shiping regions, and not excluded shipping regions.
For more detail on the actual regionName/regionId values that will be returned based on the regionType value, see the regionId and/or regionName field descriptions.

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

Occurrence: Conditional

shortDescriptionstring

This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.).

Occurrence: Conditional

sizestring

(Primary Item Aspect) The size of the item. For example, '7' for a size 7 shoe. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

sizeSystemstring

(Primary Item Aspect) The sizing system of the country. All the item aspects, including this aspect, are returned in the localizedAspects container.

Valid Values:
AU (Australia),
BR (Brazil),
CN (China),
DE (Germany),
EU (European Union),
FR (France),
IT (Italy),
JP (Japan),
MX (Mexico),
US (USA),
UK (United Kingdom)

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

Occurrence: Conditional

sizeTypestring

(Primary Item Aspect) Text describing a size group in which the item would be included, such as regular, petite, plus, big-and-tall or maternity. All the item aspects, including this aspect, are returned in the localizedAspects container.

Occurrence: Conditional

subtitlestring

A subtitle is optional and allows the seller to provide more information about the product, possibly including keywords that may assist with search results.

Occurrence: Conditional

taxesarray of Taxes

The container for the tax information for the item.

Occurrence: Conditional

taxes.ebayCollectAndRemitTaxboolean

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

Occurrence: Conditional

taxes.includedInPriceboolean

This indicates if tax was applied for the cost of the item.

Occurrence: Conditional

taxes.shippingAndHandlingTaxedboolean

This indicates if tax is applied for the shipping cost.

Occurrence: Conditional

taxes.taxJurisdictionTaxJurisdiction

The container that returns the tax jurisdiction.

Occurrence: Conditional

taxes.taxJurisdiction.regionRegion

The region of the tax jurisdiction.

Occurrence: Conditional

taxes.taxJurisdiction.region.regionNamestring

A localized text string that indicates the name of the region. Taxes are generally charged at the state/province level or at the country level in the case of VAT tax.

Occurrence: Conditional

taxes.taxJurisdiction.region.regionTypeRegionTypeEnum

An enumeration value that indicates the type of region for the tax jurisdiction.

Valid Values:

  • STATE_OR_PROVINCE - Indicates the region is a state or province within a country, such as California or New York in the US, or Ontario or Alberta in Canada.
  • COUNTRY - Indicates the region is a single country.
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

taxes.taxJurisdiction.taxJurisdictionIdstring

The identifier of the tax jurisdiction.

Occurrence: Conditional

taxes.taxPercentagestring

The percentage of tax.

Occurrence: Conditional

taxes.taxTypeTaxType

This field indicates the type of tax that may be collected for the item.

Occurrence: Conditional

titlestring

The seller-created title of the item.

Maximum Length: 80 characters

Occurrence: Always

topRatedBuyingExperienceboolean

This indicates if the item a top-rated plus item. There are three benefits of a top-rated plus item: a minimum 30-day money-back return policy, shipping the items in 1 business day with tracking provided, and the added comfort of knowing this item is from experienced sellers with the highest buyer ratings. See the Top Rated Plus Items and Becoming a Top Rated Seller and qualifying for Top Rated Plus help topics for more information.

Occurrence: Conditional

tyreLabelImageUrlstring

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

Occurrence: Conditional

uniqueBidderCountinteger

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

Occurrence: Conditional

unitPriceConvertedAmount

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

unitPrice.convertedFromCurrencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

unitPrice.convertedFromValuestring

The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

unitPrice.currencyCurrencyCodeEnum

The three-letter ISO 4217 code representing the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

unitPrice.valuestring

The monetary amount in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Occurrence: Conditional

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

warningsarray of ErrorDetailV3

An array of warning messages. These types of errors do not prevent the method from executing but should be checked.

Occurrence: Conditional

warnings.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Always

warnings.domainstring

The name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Always

warnings.errorIdinteger

A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Always

warnings.inputRefIdsarray of string

An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestring

A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestring

A description of the condition that caused the error or warning.

Occurrence: Always

warnings.outputRefIdsarray of string

An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestring

This is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstring

The name of the subdomain in which the error or warning occurred.

Occurrence: NA

watchCountinteger

The number of users that have added the item to their watch list.

Note: This field is restricted to applications that have been granted permission to access this feature. You must submit an App Check ticket to request this access. In the App Check form, add a note to the Application Title/Summary and/or Application Details fields that you want access to Watch Count data in the Browse API.

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
404Not Found
409Conflict
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
11000API_BROWSEAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
11001API_BROWSEREQUESTThe specified item ID was not found.
11002API_BROWSEREQUESTThe specified item group was not found.
11004API_BROWSEREQUESTThe item is not available for purchase. This can be for many reasons, such as when the listing is being updated by the seller. Wait a few minutes and try the call again.
11005API_BROWSEREQUESTThe item group ID is invalid. Use {itemHref} to get the item details.
11008API_BROWSEREQUESTThe item group is not available. This can be for many reasons, such as when the listing is being updated by the seller. Wait a few minutes and try the call again.
11011API_BROWSEREQUESTThe marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces}
11012API_BROWSEREQUESTThe specified item IDs are invalid, or the format of the specified values are invalid.
11013API_BROWSEREQUESTThe specified group IDs are invalid, or the format of the specified values are invalid.
11014API_BROWSEREQUESTAn item_ids and an item_group_ids list cannot be used at same time. Please use only one of these lists.
11015API_BROWSEREQUESTThe maximum number of item ids has been exceeded. Please reduce the number of item ids to {maxAllowedItemIds} or less.
11016API_BROWSEREQUESTThe maximum number of item group IDs has been exceeded. Please reduce the number of item group ids to {maxAllowedItemGroupIds} or less.
11018API_BROWSEREQUESTThe specified fieldgroups are invalid. The COMPACT fieldgroup cannot be combined with another fieldgroup.
11501API_BROWSEREQUESTThe 'fieldgroups' value(s) are invalid: {fieldgroups}. The supported fieldgroups are: {supportedFieldgroups}

Warnings

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

CodeDomainCategoryMeaning
11502API_BROWSEAPPLICATIONThere was a problem extracting product information for this Item. Please try again.
11508API_BROWSEAPPLICATIONThis seller is currently away. If you make a purchase, please allow additional time for your order to be processed.
11509API_BROWSEAPPLICATIONThis seller is currently away until {sellerReturnDate}. If you make a purchase, please allow additional time for your order to be processed.

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: Get Item Details

This sample returns the details of the specified item by passing in the ID of the item. The ID is returned by the search call in the itemId field. It is also returned, as a HATEOAS style reference, in itemHref field.

Input

The input is the item_id URI parameter, which specifies the ID of the item. There is no payload with this request.

The request header, which is required, is: X-EBAY-C-ENDUSERCTX: contextualLocation=country%3DUS%2Czip%3D19406. For details about this header see, Header for shipping information accuracy.

GEThttps://api.ebay.com/buy/browse/v1/item/v1|1**********0|0

Output

The details for the item are returned.

Sample 2: Determine if an Item has Been Changed

This sample returns only the itemId, bidCount, currentBidPrice, eligibleForInlineCheckout, estimatedAvailabilities, itemAffiliateWebURL, itemEndDate, itemWebURL, legacyItemId, minimumPriceToBid, price, priorityListing, reservePriceMet, sellerItemRevision (generated when a seller revises any item detail, except quantity), itemCreationDate, shippingOptions, taxes, topRatedBuyingExperience, and uniqueBidderCount fields. This lets you quickly check if the availability or price of the item has changed, if the item has been revised by the seller, or if an item's top-rated plus status has changed for items you have stored.

This sample uses the same item as the first sample; the Macbook Air.

Input

The input is the item_id URI parameter, which specifies the ID of the item and fieldgroups set to COMPACT.

GEThttps://api.ebay.com/buy/browse/v1/item/v1|2**********2|0?fieldgroups=COMPACT

Output

The fields for the compact response are returned. You can see that the item revision number is 6. So if you have stored this item and its revision number is less than 6, you need to update the price of the item. Since availability is not tracked by the revision number, you should also check and if needed update the estimatedAvalibilities container field values.

Sample 3: Get Item Details AND the Item Product Information

This sample returns the details of a specific item and the details of the item's product. It uses the same item as the first and second samples; the Macbook Air.

Input

The input is the item_id and fieldgroups set to PRODUCT. There is no payload with this request.

GEThttps://api.ebay.com/buy/browse/v1/item/v1|2**********2|0?fieldgroups=PRODUCT

Output

The output is the details of the item and the details of the product for this item, which is returned in the product container.

Sample 4: Get Item Details AND Seller Details

This sample returns the details of a specific item and the details of the seller.

Input

The input is the item_id , and the fieldgroups is set to ADDITIONAL_SELLER_DETAILS. There is no payload with this request.

GEThttps://api.ebay.com/buy/browse/v1/item/v1|1**********5|0?fieldgroups=ADDITIONAL_SELLER_DETAILS

Output

The output is the details of the item. Also returned is the seller's user ID, which is returned in the seller container.