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 withADDITIONAL_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 withPRODUCT
.
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
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
Parameter | Type | Description |
---|---|---|
item_id | string | This 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|0For 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 |
fieldgroups | array of string | This 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:
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.
Header | Type | Description |
---|---|---|
Accept-Language | string | This 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:
Occurrence: Conditional |
X-EBAY-C-ENDUSERCTX | string | This 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-ID | string | This 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
Response fields
Output container/field | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
additionalImages | array 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.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
additionalImages.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
additionalImages.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
addonServices | array of AddonService | A list of add-on services that may be selected for the item or that may apply automatically. Occurrence: Conditional | |||||||||||||||
addonServices.selection | AddonServiceSelectionEnum | This field indicates whether the add-on service must be selected for the item. Occurrence: Conditional | |||||||||||||||
addonServices.serviceFee | ConvertedAmount | The amount charged for the add-on service. Occurrence: Conditional | |||||||||||||||
addonServices.serviceFee.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
addonServices.serviceFee.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
addonServices.serviceFee.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
addonServices.serviceFee.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
addonServices.serviceId | string | The ID number of the add-on service. Occurrence: Conditional | |||||||||||||||
addonServices.serviceType | AddonServiceTypeEnum | The type of add-on service, such as Occurrence: Conditional | |||||||||||||||
adultOnly | boolean | 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 | |||||||||||||||
ageGroup | string | (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 | |||||||||||||||
authenticityGuarantee | AuthenticityGuaranteeProgram | 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. Occurrence: Conditional | |||||||||||||||
authenticityGuarantee.description | string | An indication that the item is qualified for the Authenticity Guarantee program. Occurrence: Conditional | |||||||||||||||
authenticityGuarantee.termsWebUrl | string | The URL to the Authenticity Guarantee program terms of use. Occurrence: Conditional | |||||||||||||||
authenticityVerification | AuthenticityVerificationProgram | A container for information about whether an item is from a verified seller. Occurrence: Conditional | |||||||||||||||
authenticityVerification.description | string | An indication that the item is from a verified seller. Occurrence: Conditional | |||||||||||||||
authenticityVerification.termsWebUrl | string | The URL to the Authenticity Verification program terms of use. Occurrence: Conditional | |||||||||||||||
availableCoupons | array of AvailableCoupon | A list of available coupons for the item. Occurrence: Conditional | |||||||||||||||
availableCoupons.constraint | CouponConstraint | The limitations or restrictions of the coupon. Occurrence: Conditional | |||||||||||||||
availableCoupons.constraint.expirationDate | string | This timestamp provides the expiration date of the coded coupon. Occurrence: Conditional | |||||||||||||||
availableCoupons.discountAmount | Amount | The discount amount after the coupon is applied. Occurrence: Conditional | |||||||||||||||
availableCoupons.discountAmount.currency | CurrencyCodeEnum | The list of valid currencies. Each ISO 4217 currency code includes the currency name followed by the numeric value. Occurrence: Conditional | |||||||||||||||
availableCoupons.discountAmount.value | string | The value of the discounted amount. Occurrence: Conditional | |||||||||||||||
availableCoupons.discountType | CouponDiscountType | The type of discount that the coupon applies. Occurrence: Conditional | |||||||||||||||
availableCoupons.message | string | A description of the coupon. Occurrence: Conditional | |||||||||||||||
availableCoupons.redemptionCode | string | The coupon code. Occurrence: Conditional | |||||||||||||||
availableCoupons.termsWebUrl | string | The URL to the coupon terms of use. Occurrence: Conditional | |||||||||||||||
bidCount | integer | 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 | |||||||||||||||
brand | string | (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 | |||||||||||||||
buyingOptions | array of string | A comma separated list of all the purchase options available for the item. The values returned are:
Occurrence: Conditional | |||||||||||||||
categoryId | string | 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 | |||||||||||||||
categoryIdPath | string | The IDs of every category in the item path, separated by pipe characters, starting with the top level parent category. Occurrence: Always | |||||||||||||||
categoryPath | string | Text that shows the category hierarchy of the item. For example: Computers/Tablets & Networking, Laptops & Netbooks, PC Laptops & Netbooks Occurrence: Always | |||||||||||||||
color | string | (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 | |||||||||||||||
condition | string | 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. Occurrence: Conditional | |||||||||||||||
conditionDescription | string | 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 | |||||||||||||||
conditionDescriptors | array 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. Occurrence: Conditional | |||||||||||||||
conditionDescriptors.name | string | The name of a condition descriptor. The value(s) for this condition descriptor is returned in the associated values array. Occurrence: Conditional | |||||||||||||||
conditionDescriptors.values | array 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.additionalInfo | array 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.content | string | The value for the condition descriptor indicated in the associated name field. Occurrence: Conditional | |||||||||||||||
conditionId | string | 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. Occurrence: Conditional | |||||||||||||||
currentBidPrice | ConvertedAmount | 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.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
currentBidPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
currentBidPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
currentBidPrice.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
description | string | 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 | |||||||||||||||
ecoParticipationFee | ConvertedAmount | 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. Occurrence: Conditional | |||||||||||||||
ecoParticipationFee.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
ecoParticipationFee.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
ecoParticipationFee.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
ecoParticipationFee.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
eligibleForInlineCheckout | boolean | This field indicates if the item can be purchased using the Buy Order API.
Occurrence: Always | |||||||||||||||
enabledForGuestCheckout | boolean | 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 | |||||||||||||||
energyEfficiencyClass | string | This indicates the European energy efficiency rating (EEK) of the item. This field is returned only if the seller specified the energy efficiency rating. Occurrence: Conditional | |||||||||||||||
epid | string | 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 | |||||||||||||||
estimatedAvailabilities | array 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.availabilityThreshold | integer | 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. Occurrence: Conditional | |||||||||||||||
estimatedAvailabilities.availabilityThresholdType | AvailabilityThresholdEnum | 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
Code so that your app gracefully handles any future changes to these preferences. Occurrence: Conditional | |||||||||||||||
estimatedAvailabilities.deliveryOptions | array of DeliveryOptionsEnum | An array of available delivery options. Occurrence: Conditional | |||||||||||||||
estimatedAvailabilities.estimatedAvailabilityStatus | AvailabilityStatusEnum | An enumeration value representing the inventory status of this item. Occurrence: Conditional | |||||||||||||||
estimatedAvailabilities.estimatedAvailableQuantity | integer | 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.estimatedRemainingQuantity | integer | 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.estimatedSoldQuantity | integer | The estimated number of this item that have been sold. Occurrence: Conditional | |||||||||||||||
gender | string | (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 | |||||||||||||||
gtin | string | 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 | |||||||||||||||
hazardousMaterialsLabels | HazardousMaterialsLabels | Hazardous materials labels for the item. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.additionalInformation | string | Additional information about the hazardous materials labels. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.pictograms | array of HazardPictogram | An array of hazard pictograms that apply to the item. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.pictograms.pictogramDescription | string | The description of the hazard pictogram, such as Flammable. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.pictograms.pictogramId | string | The ID of the hazard pictogram. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.pictograms.pictogramUrl | string | The URL of the hazard pictogram. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.signalWord | string | The signal word for the hazardous materials label (such as Danger or Warning). Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.signalWordId | string | The ID of the signal word for the hazardous materials label. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.statements | array of HazardStatement | An array of hazard statements for the item. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.statements.statementDescription | string | A description of the nature of the hazard, such as whether the material is toxic if swallowed. Occurrence: Conditional | |||||||||||||||
hazardousMaterialsLabels.statements.statementId | string | The ID of the hazard statement. Occurrence: Conditional | |||||||||||||||
image | Image | The URL of the primary image of the item. The other images of the item are returned in the additionalImages container. Occurrence: Always | |||||||||||||||
image.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
image.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
image.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
inferredEpid | string | 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. Occurrence: Conditional | |||||||||||||||
itemAffiliateWebUrl | string | The URL to the View Item page of the item which includes the affiliate tracking ID.
Occurrence: Conditional | |||||||||||||||
itemCreationDate | string | A timestamp that indicates the date and time an item listing was created. Occurrence: Conditional | |||||||||||||||
itemEndDate | string | This timestamp indicates the date and time up to which the item can be purchased. 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 | |||||||||||||||
itemId | string | The unique RESTful identifier of the item. Occurrence: Always | |||||||||||||||
itemLocation | Address | The physical location of the item. Occurrence: Conditional | |||||||||||||||
itemLocation.addressLine1 | string | The first line of the street address. Occurrence: Conditional | |||||||||||||||
itemLocation.addressLine2 | string | 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.city | string | The city of the address. Occurrence: Always | |||||||||||||||
itemLocation.country | CountryCodeEnum | The two-letter ISO 3166 standard code for the country of the address. Occurrence: Always | |||||||||||||||
itemLocation.county | string | The county of the address. Occurrence: Conditional | |||||||||||||||
itemLocation.postalCode | string | 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 Occurrence: Conditional | |||||||||||||||
itemLocation.stateOrProvince | string | The state or province of the address. Occurrence: Conditional | |||||||||||||||
itemWebUrl | string | 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 | |||||||||||||||
legacyItemId | string | 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 | |||||||||||||||
listingMarketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace where the item is listed. Occurrence: Always | |||||||||||||||
localizedAspects | array 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.name | string | The text representing the name of the aspect for the name/value pair, such as Color. Occurrence: Conditional | |||||||||||||||
localizedAspects.type | ValueTypeEnum | This indicates if the value being returned is a string or an array of values.
Occurrence: Conditional | |||||||||||||||
localizedAspects.value | string | The value of the aspect for the name/value pair, such as Red. Occurrence: Conditional | |||||||||||||||
lotSize | integer | The number of items in a lot. In other words, a lot size is the number of items that are being sold together.
Note: Lots are not supported in all categories. Occurrence: Conditional | |||||||||||||||
manufacturer | CompanyAddress | Contact information for the manufacturer of the product. Occurrence: Conditional | |||||||||||||||
manufacturer.addressLine1 | string | The first line of the product manufacturer's street address. Occurrence: Conditional | |||||||||||||||
manufacturer.addressLine2 | string | 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.city | string | The city of the product manufacturer's street address. Occurrence: Conditional | |||||||||||||||
manufacturer.companyName | string | The company name of the the product manufacturer. Occurrence: Conditional | |||||||||||||||
manufacturer.country | CountryCodeEnum | The two-letter ISO 3166 standard code for the country of the address. Occurrence: Conditional | |||||||||||||||
manufacturer.countryName | string | The country name of the product manufacturer's street address. Occurrence: Conditional | |||||||||||||||
manufacturer.county | string | The county of the product manufacturer's street address. Occurrence: Conditional | |||||||||||||||
manufacturer.email | string | The product manufacturer's business email address. Occurrence: Conditional | |||||||||||||||
manufacturer.phone | string | The product manufacturer's business phone number. Occurrence: Conditional | |||||||||||||||
manufacturer.postalCode | string | The postal code of the product manufacturer's street address. Occurrence: Conditional | |||||||||||||||
manufacturer.stateOrProvince | string | The state or province of the product manufacturer's street address. Occurrence: Conditional | |||||||||||||||
marketingPrice | MarketingPrice | The original price and the discount amount and percentage. Occurrence: Conditional | |||||||||||||||
marketingPrice.discountAmount | ConvertedAmount | This container returns the monetary amount of the seller discount. Occurrence: Conditional | |||||||||||||||
marketingPrice.discountAmount.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
marketingPrice.discountAmount.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
marketingPrice.discountAmount.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
marketingPrice.discountAmount.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
marketingPrice.discountPercentage | string | This field expresses the percentage of the seller discount based on the value in the Occurrence: Conditional | |||||||||||||||
marketingPrice.originalPrice | ConvertedAmount | This container returns the monetary amount of the item without the discount. Occurrence: Conditional | |||||||||||||||
marketingPrice.originalPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
marketingPrice.originalPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
marketingPrice.originalPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
marketingPrice.originalPrice.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
marketingPrice.priceTreatment | PriceTreatmentEnum | Indicates the pricing treatment (discount) that was applied to the price of the item. Occurrence: Conditional | |||||||||||||||
material | string | (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 | |||||||||||||||
minimumPriceToBid | ConvertedAmount | 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.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
minimumPriceToBid.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
minimumPriceToBid.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
minimumPriceToBid.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
mpn | string | 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 | |||||||||||||||
pattern | string | (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 | |||||||||||||||
paymentMethods | array of PaymentMethod | The payment methods for the item, including the payment method types, brands, and instructions for the buyer. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentMethodType | PaymentMethodTypeEnum | The payment method type, such as credit card or cash. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentMethodBrands | array of PaymentMethodBrand | The payment method brands, including the payment method brand type and logo image. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentMethodBrands.paymentMethodBrandType | PaymentMethodBrandEnum | The payment method brand, such as Visa or PayPal. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentMethodBrands.logoImage | Image | The details of the logo image, such as the size and URL. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentMethodBrands.logoImage.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentMethodBrands.logoImage.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
paymentMethods.paymentMethodBrands.logoImage.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
paymentMethods.paymentInstructions | array of PaymentInstructionEnum | The payment instructions for the buyer, such as cash in person or contact seller. Occurrence: Conditional | |||||||||||||||
paymentMethods.sellerInstructions | array of SellerInstructionEnum | The seller instructions to the buyer, such as accepts credit cards or see description. Occurrence: Conditional | |||||||||||||||
price | ConvertedAmount | The cost of just the item. This amount does not include any adjustments such as discounts or shipping costs. Occurrence: Always | |||||||||||||||
price.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
price.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
price.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
price.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
priceDisplayCondition | PriceDisplayConditionEnum | 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 | |||||||||||||||
primaryItemGroup | ItemGroupSummary | 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. Occurrence: Conditional | |||||||||||||||
primaryItemGroup.itemGroupAdditionalImages | array 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.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
primaryItemGroup.itemGroupAdditionalImages.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
primaryItemGroup.itemGroupAdditionalImages.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
primaryItemGroup.itemGroupHref | string | 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.itemGroupId | string | 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.itemGroupImage | Image | 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.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
primaryItemGroup.itemGroupImage.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
primaryItemGroup.itemGroupImage.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
primaryItemGroup.itemGroupTitle | string | 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.itemGroupType | ItemGroupTypeEnum | 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 | |||||||||||||||
primaryProductReviewRating | ReviewRating | The container that returns the product rating details, such as review count, rating histogram, and average rating. Occurrence: Conditional | |||||||||||||||
primaryProductReviewRating.averageRating | string | The average rating given to a product based on customer reviews. Occurrence: Conditional | |||||||||||||||
primaryProductReviewRating.ratingHistograms | array of RatingHistogram | An array of containers for the product rating histograms that shows the review counts and the product rating. Occurrence: Conditional | |||||||||||||||
primaryProductReviewRating.ratingHistograms.count | integer | The total number of user ratings that the product has received. Occurrence: Conditional | |||||||||||||||
primaryProductReviewRating.ratingHistograms.rating | string | 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 Occurrence: Conditional | |||||||||||||||
primaryProductReviewRating.reviewCount | integer | The total number of reviews for the item. Occurrence: Conditional | |||||||||||||||
priorityListing | boolean | This field is returned as Occurrence: Always | |||||||||||||||
product | Product | The container that returns the product information of the item. Occurrence: Conditional | |||||||||||||||
product.additionalImages | array 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.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
product.additionalImages.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
product.additionalImages.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
product.additionalProductIdentities | array 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 Occurrence: Conditional | |||||||||||||||
product.additionalProductIdentities.productIdentity | array 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
Occurrence: Conditional | |||||||||||||||
product.additionalProductIdentities.productIdentity.identifierType | string | The type of product identifier, such as UPC and EAN. Occurrence: Conditional | |||||||||||||||
product.additionalProductIdentities.productIdentity.identifierValue | string | The product identifier value. Occurrence: Conditional | |||||||||||||||
product.aspectGroups | array 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.aspects | array of Aspect | An array of the name/value pairs for the aspects of the product. For example: BRAND/Apple Occurrence: Conditional | |||||||||||||||
product.aspectGroups.aspects.localizedName | string | The text representing the name of the aspect for the name/value pair, such as Brand. Occurrence: Conditional | |||||||||||||||
product.aspectGroups.aspects.localizedValues | array of string | The text representing the value of the aspect for the name/value pair, such as Apple. Occurrence: Conditional | |||||||||||||||
product.aspectGroups.localizedGroupName | string | The name of a group of aspects. Occurrence: Conditional | |||||||||||||||
product.brand | string | The brand associated with product. To identify the product, this is always used along with MPN (manufacturer part number). Occurrence: Conditional | |||||||||||||||
product.description | string | The rich description of an eBay product, which might contain HTML. Occurrence: Conditional | |||||||||||||||
product.gtins | array 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.image | Image | The primary image of the product. This is often a stock photo. Occurrence: Conditional | |||||||||||||||
product.image.height | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
product.image.imageUrl | string | The URL of the image. Occurrence: Always | |||||||||||||||
product.image.width | integer | Reserved for future use. Occurrence: Conditional | |||||||||||||||
product.mpns | array 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.title | string | The title of the product. Occurrence: Conditional | |||||||||||||||
productFicheWebUrl | string | 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 | |||||||||||||||
productSafetyLabels | ProductSafetyLabels | This container provides product safety labels which were provided by the seller, for the listing. Occurrence: Conditional | |||||||||||||||
productSafetyLabels.pictograms | array 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.pictogramDescription | string | The description of the safety label pictogram. Occurrence: Conditional | |||||||||||||||
productSafetyLabels.pictograms.pictogramId | string | The identifier of the safety label pictogram. Occurrence: Conditional | |||||||||||||||
productSafetyLabels.pictograms.pictogramUrl | string | The URL of the safety label pictogram. Occurrence: Conditional | |||||||||||||||
productSafetyLabels.statements | array 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.statementDescription | string | A description of the nature of the product safety label statement. Occurrence: Conditional | |||||||||||||||
productSafetyLabels.statements.statementId | string | The identifier of the product safety label statement. Occurrence: Conditional | |||||||||||||||
qualifiedPrograms | array 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. Occurrence: Conditional | |||||||||||||||
quantityLimitPerBuyer | integer | The maximum number for a specific item that one buyer can purchase. Occurrence: Conditional | |||||||||||||||
repairScore | string | 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 | |||||||||||||||
reservePriceMet | boolean | 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 | |||||||||||||||
responsiblePersons | array of ResponsiblePerson | This array provides information about one or more EU-based Responsible Persons or entities associated with the listing. Occurrence: Conditional | |||||||||||||||
responsiblePersons.addressLine1 | string | The first line of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.addressLine2 | string | 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.city | string | The city of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.companyName | string | The name of the the Responsible Person or entity. Occurrence: Conditional | |||||||||||||||
responsiblePersons.country | CountryCodeEnum | The two-letter ISO 3166 standard of the country of the address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.countryName | string | The country name of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.county | string | The county of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.email | string | The email of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.phone | string | The phone number of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.postalCode | string | The postal code of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.stateOrProvince | string | The state or province of the Responsible Person's street address. Occurrence: Conditional | |||||||||||||||
responsiblePersons.types | array of ResponsiblePersonTypeEnum | The type(s) associated with the Responsible Person or entity. Occurrence: Conditional | |||||||||||||||
returnTerms | ItemReturnTerms | The container that returns an overview of the seller's return policy. Occurrence: Conditional | |||||||||||||||
returnTerms.extendedHolidayReturnsOffered | boolean | 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.refundMethod | RefundMethodEnum | An enumeration value that indicates how a buyer is refunded when an item is returned. Occurrence: Conditional | |||||||||||||||
returnTerms.restockingFeePercentage | string | 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.returnInstructions | string | Text written by the seller describing what the buyer needs to do in order to return the item. Occurrence: Conditional | |||||||||||||||
returnTerms.returnMethod | ReturnMethodEnum | 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.
Occurrence: Conditional | |||||||||||||||
returnTerms.returnPeriod | TimeDuration | The amount of time the buyer has to return the item after the purchase date. Occurrence: Conditional | |||||||||||||||
returnTerms.returnPeriod.unit | TimeDurationUnitEnum | An enumeration value that indicates the units of the time span (e.g., Occurrence: Conditional | |||||||||||||||
returnTerms.returnPeriod.value | integer | 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.returnsAccepted | boolean | Indicates whether the seller accepts returns for the item. Occurrence: Conditional | |||||||||||||||
returnTerms.returnShippingCostPayer | ReturnShippingCostPayerEnum | This enumeration value indicates whether the buyer or seller is responsible for return shipping costs when an item is returned.
Occurrence: Conditional | |||||||||||||||
seller | SellerDetail | The container that returns basic and detailed about the seller of the item, such as name, feedback score, and contact information. Occurrence: Always | |||||||||||||||
seller.feedbackPercentage | string | The percentage of the total positive feedback. Occurrence: Always | |||||||||||||||
seller.feedbackScore | integer | 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.sellerAccountType | string | 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: Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo | SellerLegalInfo | The container with the seller's contact info and fields that are required by law. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.email | string | The seller's business email address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.fax | string | The seller' business fax number. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.imprint | string | 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.legalContactFirstName | string | The seller's first name. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.legalContactLastName | string | The seller's last name. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.name | string | The name of the seller's business. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.phone | string | The seller's business phone number. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.registrationNumber | string | The seller's registration number. This is information used by some countries. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress | LegalAddress | The container that returns the seller's address to be used to contact them. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.addressLine1 | string | The first line of the street address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.addressLine2 | string | 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.city | string | The city of the address. Occurrence: Always | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.country | CountryCodeEnum | The two-letter ISO 3166 standard code for the country of the address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.countryName | string | The name of the country of the address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.county | string | The name of the county of the address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.postalCode | string | The postal code of the address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.sellerProvidedLegalAddress.stateOrProvince | string | The state or province of the address. Occurrence: Always | |||||||||||||||
seller.sellerLegalInfo.termsOfService | string | 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.vatDetails | array 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.issuingCountry | CountryCodeEnum | 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.vatId | string | The seller's VAT (value added tax) ID. VAT is a tax added by some European countries. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator | EconomicOperator | Provides required information about the manufacturer and/or supplier of the item. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.companyName | string | The company name of the registered Economic Operator. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.addressLine1 | string | The first line of the registered Economic Operator's street address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.addressLine2 | string | 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.city | string | The city of the registered Economic Operator's street address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.stateOrProvince | string | The state or province of the registered Economic Operator's street address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.postalCode | string | The postal code of the registered Economic Operator's street address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.country | string | The two-letter ISO 3166 standard abbreviation of the country of the registered Economic Operator's address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.phone | string | The registered Economic Operator's business phone number. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.economicOperator.email | string | The registered Economic Operator's business email address. Occurrence: Conditional | |||||||||||||||
seller.sellerLegalInfo.weeeNumber | string | 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.userId | string | 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.username | string | The user name created by the seller for use on eBay. Occurrence: Always | |||||||||||||||
sellerCustomPolicies | array of SellerCustomPolicy | A list of the custom policies that are applied to a listing. Occurrence: Conditional | |||||||||||||||
sellerCustomPolicies.description | string | The seller-defined description of the policy. Occurrence: Conditional | |||||||||||||||
sellerCustomPolicies.label | string | The seller-defined label for an individual custom policy. Occurrence: Conditional | |||||||||||||||
sellerCustomPolicies.type | SellerCustomPolicyTypeEnum | The type of custom policy, such as PRODUCT_COMPLIANCE or TAKE_BACK. Occurrence: Conditional | |||||||||||||||
sellerItemRevision | string | An identifier generated/incremented when a seller revises the item. There are two types of item revisions:
Occurrence: Conditional | |||||||||||||||
shippingOptions | array of ShippingOption | An array of shipping options containers that have the details about cost, carrier, etc. of one shipping option. Occurrence: Always | |||||||||||||||
shippingOptions.additionalShippingCostPerUnit | ConvertedAmount | 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.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
shippingOptions.additionalShippingCostPerUnit.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
shippingOptions.additionalShippingCostPerUnit.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
shippingOptions.additionalShippingCostPerUnit.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
shippingOptions.cutOffDateUsedForEstimate | string | 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. Occurrence: Conditional | |||||||||||||||
shippingOptions.fulfilledThrough | FulfilledThroughEnum | If the item is being shipped by the eBay Global Shipping program, this field returns Occurrence: Conditional | |||||||||||||||
shippingOptions.guaranteedDelivery | boolean | 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.importCharges | ConvertedAmount | The Global Shipping Program import charges for this item. Occurrence: Conditional | |||||||||||||||
shippingOptions.importCharges.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
shippingOptions.importCharges.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
shippingOptions.importCharges.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
shippingOptions.importCharges.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
shippingOptions.maxEstimatedDeliveryDate | string | 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. Occurrence: Conditional | |||||||||||||||
shippingOptions.minEstimatedDeliveryDate | string | 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. Occurrence: Conditional | |||||||||||||||
shippingOptions.quantityUsedForEstimate | integer | The number of items used when calculating the estimation information. Occurrence: Conditional | |||||||||||||||
shippingOptions.shippingCarrierCode | string | The name of the shipping provider, such as FedEx, or USPS. Occurrence: Always | |||||||||||||||
shippingOptions.shippingCost | ConvertedAmount | The final shipping cost for all the items after all discounts are applied. Occurrence: Always | |||||||||||||||
shippingOptions.shippingCost.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
shippingOptions.shippingCost.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
shippingOptions.shippingCost.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
shippingOptions.shippingCost.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
shippingOptions.shippingCostType | string | Indicates the class of the shipping cost. Occurrence: Always | |||||||||||||||
shippingOptions.shippingServiceCode | string | The type of shipping service. For example, USPS First Class. Occurrence: Always | |||||||||||||||
shippingOptions.shipToLocationUsedForEstimate | ShipToLocation | The container that returns the country and postal code of where the item is to be shipped. These values come from the Occurrence: Conditional | |||||||||||||||
shippingOptions.shipToLocationUsedForEstimate.country | CountryCodeEnum | The two-letter ISO 3166 standard of the country for where the item is to be shipped. Occurrence: Conditional | |||||||||||||||
shippingOptions.shipToLocationUsedForEstimate.postalCode | string | The zip code (postal code) for where the item is to be shipped. Occurrence: Conditional | |||||||||||||||
shippingOptions.trademarkSymbol | string | Any trademark symbol, such as ™ or ®, that needs to be shown in superscript next to the shipping service name. Occurrence: Conditional | |||||||||||||||
shippingOptions.type | string | The type of a shipping option, such as EXPEDITED, ONE_DAY, STANDARD, ECONOMY, PICKUP, etc. Occurrence: Always | |||||||||||||||
shipToLocations | ShipToLocations | The container that returns the geographic regions to be included and excluded that define where the item can be shipped. Occurrence: Conditional | |||||||||||||||
shipToLocations.regionExcluded | array 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.regionId | string | 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. Occurrence: Conditional | |||||||||||||||
shipToLocations.regionExcluded.regionName | string | A localized text string that indicates the name of the shipping region. The value returned here is dependent on the corresponding regionType value. Occurrence: Conditional | |||||||||||||||
shipToLocations.regionExcluded.regionType | RegionTypeEnum | An enumeration value that indicates the level or type of shipping region.
Code so that your app gracefully handles any future changes to this list. Occurrence: Conditional | |||||||||||||||
shipToLocations.regionIncluded | array 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.regionId | string | 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. Occurrence: Conditional | |||||||||||||||
shipToLocations.regionIncluded.regionName | string | A localized text string that indicates the name of the shipping region. The value returned here is dependent on the corresponding regionType value. Occurrence: Conditional | |||||||||||||||
shipToLocations.regionIncluded.regionType | RegionTypeEnum | An enumeration value that indicates the level or type of shipping region.
Code so that your app gracefully handles any future changes to this list. Occurrence: Conditional | |||||||||||||||
shortDescription | string | This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.). Occurrence: Conditional | |||||||||||||||
size | string | (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 | |||||||||||||||
sizeSystem | string | (Primary Item Aspect) The sizing system of the country. All the item aspects, including this aspect, are returned in the localizedAspects container. Occurrence: Conditional | |||||||||||||||
sizeType | string | (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 | |||||||||||||||
subtitle | string | 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 | |||||||||||||||
taxes | array of Taxes | The container for the tax information for the item. Occurrence: Conditional | |||||||||||||||
taxes.ebayCollectAndRemitTax | boolean | This field is only returned if Occurrence: Conditional | |||||||||||||||
taxes.includedInPrice | boolean | This indicates if tax was applied for the cost of the item. Occurrence: Conditional | |||||||||||||||
taxes.shippingAndHandlingTaxed | boolean | This indicates if tax is applied for the shipping cost. Occurrence: Conditional | |||||||||||||||
taxes.taxJurisdiction | TaxJurisdiction | The container that returns the tax jurisdiction. Occurrence: Conditional | |||||||||||||||
taxes.taxJurisdiction.region | Region | The region of the tax jurisdiction. Occurrence: Conditional | |||||||||||||||
taxes.taxJurisdiction.region.regionName | string | 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.regionType | RegionTypeEnum | An enumeration value that indicates the type of region for the tax jurisdiction.
Occurrence: Conditional | |||||||||||||||
taxes.taxJurisdiction.taxJurisdictionId | string | The identifier of the tax jurisdiction. Occurrence: Conditional | |||||||||||||||
taxes.taxPercentage | string | The percentage of tax. Occurrence: Conditional | |||||||||||||||
taxes.taxType | TaxType | This field indicates the type of tax that may be collected for the item. Occurrence: Conditional | |||||||||||||||
title | string | The seller-created title of the item. Occurrence: Always | |||||||||||||||
topRatedBuyingExperience | boolean | 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 | |||||||||||||||
tyreLabelImageUrl | string | The URL to the image that shows the information on the tyre label. Occurrence: Conditional | |||||||||||||||
uniqueBidderCount | integer | 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 | |||||||||||||||
unitPrice | ConvertedAmount | 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. Occurrence: Conditional | |||||||||||||||
unitPrice.convertedFromCurrency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
unitPrice.convertedFromValue | string | The monetary amount before any conversion is performed, in the currency specified by the Occurrence: Conditional | |||||||||||||||
unitPrice.currency | CurrencyCodeEnum | The three-letter ISO 4217 code representing the currency of the amount in the Occurrence: Conditional | |||||||||||||||
unitPrice.value | string | The monetary amount in the currency specified by the Occurrence: Conditional | |||||||||||||||
unitPricingMeasure | string | The designation, such as size, weight, volume, count, etc., that was used to specify the quantity of the item. This helps buyers compare prices. Occurrence: Conditional | |||||||||||||||
warnings | array 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.category | string | This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Always | |||||||||||||||
warnings.domain | string | The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Always | |||||||||||||||
warnings.errorId | integer | 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.inputRefIds | array 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.longMessage | string | 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.message | string | A description of the condition that caused the error or warning. Occurrence: Always | |||||||||||||||
warnings.outputRefIds | array 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.parameters | array 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.name | string | This is the name of input field that caused an issue with the call request. Occurrence: Conditional | |||||||||||||||
warnings.parameters.value | string | This is the actual value that was passed in for the element specified in the Occurrence: Conditional | |||||||||||||||
warnings.subdomain | string | The name of the subdomain in which the error or warning occurred. Occurrence: NA | |||||||||||||||
watchCount | integer | The number of users that have added the item to their watch list. 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.
Status | Meaning |
---|---|
200 | Success |
404 | Not Found |
409 | Conflict |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
11000 | API_BROWSE | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
11001 | API_BROWSE | REQUEST | The specified item ID was not found. |
11002 | API_BROWSE | REQUEST | The specified item group was not found. |
11004 | API_BROWSE | REQUEST | The 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. |
11005 | API_BROWSE | REQUEST | The item group ID is invalid. Use {itemHref} to get the item details. |
11008 | API_BROWSE | REQUEST | The 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. |
11011 | API_BROWSE | REQUEST | The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces} |
11012 | API_BROWSE | REQUEST | The specified item IDs are invalid, or the format of the specified values are invalid. |
11013 | API_BROWSE | REQUEST | The specified group IDs are invalid, or the format of the specified values are invalid. |
11014 | API_BROWSE | REQUEST | An item_ids and an item_group_ids list cannot be used at same time. Please use only one of these lists. |
11015 | API_BROWSE | REQUEST | The maximum number of item ids has been exceeded. Please reduce the number of item ids to {maxAllowedItemIds} or less. |
11016 | API_BROWSE | REQUEST | The maximum number of item group IDs has been exceeded. Please reduce the number of item group ids to {maxAllowedItemGroupIds} or less. |
11018 | API_BROWSE | REQUEST | The specified fieldgroups are invalid. The COMPACT fieldgroup cannot be combined with another fieldgroup. |
11501 | API_BROWSE | REQUEST | The '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.
Code | Domain | Category | Meaning |
---|---|---|---|
11502 | API_BROWSE | APPLICATION | There was a problem extracting product information for this Item. Please try again. |
11508 | API_BROWSE | APPLICATION | This seller is currently away. If you make a purchase, please allow additional time for your order to be processed. |
11509 | API_BROWSE | APPLICATION | This 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.