ebay.browse
Module ebay.browse
API
Definitions
ballerinax/ebay.browse Ballerina library
Overview
eBay is a global online marketplace where businesses and individuals buy and sell new and used goods. The Browse API lets buyers search for items and retrieve their details, so that applications can present eBay listings to shoppers.
The eBay Browse connector lets Ballerina applications search eBay listings by keyword, category, product identifier or image, retrieve the details of single items, multiple items and item groups, bridge legacy item IDs to Browse item IDs, and check whether an item is compatible with a given product. It supports version v1 of the Browse API.
Key features
- Search eBay listings by keyword, category, GTIN, ePID, charity or aspects, with filtering, sorting and pagination
- Search for listings that look like a supplied image
- Retrieve full item details, individually or in bulk, including pricing, shipping, seller and return terms
- Browse the variations of an item group, such as colors and sizes
- Convert legacy eBay item IDs to Browse item IDs
- Check whether a part or accessory is compatible with a specific product
Setup guide
To use the eBay Browse connector, you need an eBay developer account and an application keyset. If you do not have an eBay developer account, you can sign up through the eBay Developer Program signup.
Step 1: Create an application keyset
-
Sign in to the eBay Developer Program and open Application Keys from your account menu.
-
Create a keyset for the Production environment. The connector targets the Production endpoints (
https://api.ebay.com/buy/browse/v1and its token URL) by default, so the quickstart below uses Production credentials only. -
Note down the App ID (Client ID) and the Cert ID (Client Secret) of the keyset.
Step 2: Understand the authorization
The Browse API uses the OAuth 2.0 client credentials grant. The connector exchanges the client ID and client secret for an application access token and refreshes it automatically. The token is requested with the https://api.ebay.com/oauth/api_scope scope, which grants access to public eBay data.
Quickstart
To use the eBay Browse connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the module
Import the ebay.browse module.
import ballerinax/ebay.browse;
Step 2: Instantiate a new connector
- Create a
Config.tomlfile and configure the credentials obtained in the steps above:
clientId = "<Client ID>" clientSecret = "<Client Secret>"
- Create a
browse:ConnectionConfigwith the OAuth 2.0 client credentials and initialize the connector with it.
configurable string clientId = ?; configurable string clientSecret = ?; final browse:Client ebay = check new ({ auth: { clientId, clientSecret } });
Step 3: Invoke the connector operation
Now, utilize the available connector operations.
Search for items
public function main() returns error? { browse:SearchPagedCollection _ = check ebay->searchItems({}, {q: "leather wallet", 'limit: "10"}); }
Step 4: Run the Ballerina application
bal run
Examples
The eBay Browse connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
-
Price comparison report - Search for a product and print a price report of the cheapest listings.
-
Legacy item compatibility - Resolve a legacy item ID, list the variations of its item group and check its compatibility with a product.
Clients
ebay.browse: Client
The eBay Buy Browse API lets applications search for items by keyword, category, GTIN or image, retrieve item details, and check item compatibility.
Constructor
Gets invoked to initialize the connector.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.ebay.com/buy/browse/v1" - URL of the target service
searchItems
function searchItems(SearchItemsHeaders headers, *SearchItemsQueries queries) returns SearchPagedCollection|errorSearch items
Parameters
- headers SearchItemsHeaders (default {}) - Headers to be sent with the request
- queries *SearchItemsQueries - Queries to be sent with the request
Return Type
- SearchPagedCollection|error - Summaries of items matching the search criteria
searchItemsByImage
function searchItemsByImage(SearchItemsByImageHeaders headers, SearchByImageRequest payload, *SearchItemsByImageQueries queries) returns SearchPagedCollection|errorSearch items by image
Parameters
- headers SearchItemsByImageHeaders - Headers to be sent with the request
- payload SearchByImageRequest - The container for the image information fields
- queries *SearchItemsByImageQueries - Queries to be sent with the request
Return Type
- SearchPagedCollection|error - Summaries of items matching the image
getItem
function getItem(string itemId, GetItemHeaders headers, *GetItemQueries queries) returns Item|errorGet item
Parameters
- itemId 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|22|0 For a multi-SKU listing, pass in the identifier of the variation: v1|12|4**********2 For more information about item IDs for RESTful APIs, refer to Item ID legacy API compatibility overview in the Buying Integration Guide
- headers GetItemHeaders (default {}) - Headers to be sent with the request
- queries *GetItemQueries - Queries to be sent with the request
getItemByLegacyId
function getItemByLegacyId(GetItemByLegacyIdHeaders headers, *GetItemByLegacyIdQueries queries) returns Item|errorGet item by legacy ID
Parameters
- headers GetItemByLegacyIdHeaders (default {}) - Headers to be sent with the request
- queries *GetItemByLegacyIdQueries - Queries to be sent with the request
getItems
function getItems(GetItemsHeaders headers, *GetItemsQueries queries) returns Items|errorGet multiple items
Parameters
- headers GetItemsHeaders (default {}) - Headers to be sent with the request
- queries *GetItemsQueries - Queries to be sent with the request
getItemsByItemGroup
function getItemsByItemGroup(GetItemsByItemGroupHeaders headers, *GetItemsByItemGroupQueries queries) returns ItemGroup|errorGet items by item group
Parameters
- headers GetItemsByItemGroupHeaders (default {}) - Headers to be sent with the request
- queries *GetItemsByItemGroupQueries - Queries to be sent with the request
checkCompatibility
function checkCompatibility(string itemId, CheckCompatibilityHeaders headers, CompatibilityPayload payload) returns CompatibilityResponse|errorCheck item compatibility
Parameters
- itemId string - This path parameter specifies the unique RESTful identifier of an item (such as the park you want to check). RESTful Item ID Format: v1|#|# For a single SKU listing, pass in the item ID: v1|22|0 For a multi-SKU listing, pass in the identifier of the variation: v1|12|4**********2 For more information about item IDs for RESTful APIs, refer to Item ID legacy API compatibility overview in the Buying Integration Guide
- headers CheckCompatibilityHeaders - Headers to be sent with the request
- payload CompatibilityPayload - Product compatibility details to check against the item
Return Type
- CompatibilityResponse|error - Compatibility check result for the item and the given product
Records
ebay.browse: AdditionalProductIdentity
The type that defines the 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
Fields
- productIdentity? 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
ebay.browse: AddonService
This container describes an add-on service that may be selected for an item or that may apply automatically. A charge may be associated with the add-on service
Fields
- serviceFee? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- serviceType? string - The type of add-on service, such as AUTHENTICITY_GUARANTEE. For implementation help, refer to eBay API documentation
- selection? string - This field indicates whether the add-on service must be selected for the item. For implementation help, refer to eBay API documentation
- serviceId? string - The ID number of the add-on service
ebay.browse: Address
The type that defines the fields for an address
Fields
- country? string - The two-letter ISO 3166 standard code for the country of the address. For implementation help, refer to eBay API documentation
- stateOrProvince? string - The state or province of the address. Note: This is conditionally returned in the itemLocation field
- city? string - The city of the address
- 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 itemLocation.postalCode via the API
- county? string - The county of the address
- addressLine1? string - The first line of the street address. Note: This is conditionally returned in the itemLocation field
- 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"
ebay.browse: Amount
A monetary amount with its currency
Fields
- currency? string - 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. For implementation help, refer to eBay API documentation
- value? string - The value of the discounted amount
ebay.browse: Aspect
The type that defines the fields for the name/value pairs for the aspects of the product. For example: BRAND/Apple
Fields
- localizedName? string - The text representing the name of the aspect for the name/value pair, such as Brand
- localizedValues? string[] - The text representing the value of the aspect for the name/value pair, such as Apple
ebay.browse: AspectDistribution
The type that define the fields for the aspect information. Aspects are the variations of an item, such as color, size, etc
Fields
- aspectValueDistributions? AspectValueDistribution[] - An array of containers for the various values of the aspect and the match count, and a HATEOAS reference (refinementHref) for this aspect
- localizedAspectName? string - The name of an aspect, such as Brand, Color, etc
ebay.browse: AspectGroup
A group of related aspects, such as all aspects of one category
Fields
- localizedGroupName? string - 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
- aspects? Aspect[] - An array of the name/value pairs for the aspects of the product. For example: BRAND/Apple
ebay.browse: AspectValueDistribution
The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to ASPECT_REFINEMENTS or FULL in the request
Fields
- localizedAspectValue? string - The value of an aspect. For example, Red is a value for the aspect Color
- matchCount? Signed32 - The number of items with this aspect
- refinementHref? string - A HATEOAS reference for this aspect
ebay.browse: AttributeNameValue
The type the defines attribute name/value pair fields that specify a product. The type of data depends on the context. For example, if you were using this to specify a specific vehicle, the attribute names would be Make, Model, Year, etc
Fields
- name? string - The name of the product attribute, such as Make, Model, Year, etc
- value? string - The value for the name attribute, such as BMW, R1200GS, 2011, etc
ebay.browse: AuthenticityGuaranteeProgram
A type that identifies whether the item is qualified for the Authenticity Guarantee program
Fields
- termsWebUrl? string - The URL to the Authenticity Guarantee program terms of use
- description? string - An indication that the item is qualified for the Authenticity Guarantee program
ebay.browse: AuthenticityVerificationProgram
A type that identifies whether the item is from a verified seller
Fields
- termsWebUrl? string - The URL to the Authenticity Verification program terms of use
- description? string - An indication that the item is from a verified seller
ebay.browse: AutoCorrections
Spelling corrections applied to the search keyword
Fields
- q? string - The automatically spell-corrected keyword from the request
ebay.browse: AvailableCoupon
Details of a coupon available for an item
Fields
- redemptionCode? string - The coupon code
- termsWebUrl? string - 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
- discountAmount? Amount - A monetary amount with its currency
- constraint? CouponConstraint - This type is used to provide the expiration date of a coded coupon
- discountType? string - The type of discount that the coupon applies. For implementation help, refer to eBay API documentation
- message? string - 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
ebay.browse: BuyingOptionDistribution
The container that defines the fields for the buying options refinements. This container is returned when fieldgroups is set to BUYING_OPTION_REFINEMENTS or FULL in the request
Fields
- buyingOption? string - The container that returns the buying option type. This will be AUCTION, FIXED_PRICE, CLASSIFIED_AD, or a combination of these options. For details, see buyingOptions
- matchCount? Signed32 - The number of items having this buying option
- refinementHref? string - The HATEOAS reference for this buying option
ebay.browse: Category
This type is used by the categories container in the response of the search method, and contains the name and ID of the item category
Fields
- categoryName? string - The name of the category
- categoryId? string - The unique identifier of the category
ebay.browse: CategoryDistribution
The container that defines the fields for the category refinements. This container is returned when fieldgroups is set to CATEGORY_REFINEMENTS or FULL in the request
Fields
- matchCount? Signed32 - The number of items in this category
- categoryName? string - The name of the category, such as Baby & Toddler Clothing
- categoryId? string - The unique identifier of the category
- refinementHref? string - The HATEOAS reference of this category
ebay.browse: CheckCompatibilityHeaders
Represents the Headers record for the operation: checkCompatibility
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- contentType string - This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide
ebay.browse: CommonDescriptions
The type that defines the fields for the item_id values that all use a common description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container. If the description is unique, it is returned in the items.description field
Fields
- itemIds? string[] - A list of item ids that have this description
- description? string - The item description that is used by more than one of the item variations
ebay.browse: CompanyAddress
This type is used to provide contact information for the manufacturer of the product
Fields
- country? string - The two-letter ISO 3166 standard code for the country of the address. For implementation help, refer to eBay API documentation
- stateOrProvince? string - The state or province of the product manufacturer's street address
- city? string - The city of the product manufacturer's street address
- phone? string - The product manufacturer's business phone number
- companyName? string - The company name of the product manufacturer
- postalCode? string - The postal code of the product manufacturer's street address
- county? string - The county of the product manufacturer's street address
- addressLine1? string - The first line of the product manufacturer's street address
- contactUrl? string - The contact URL of the product 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'
- countryName? string - The country name of the product manufacturer's street address
- email? string - The product manufacturer's business email address
ebay.browse: CompatibilityPayload
An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be:
"name" : "Year", "value" : "2019"
For a list of the attributes required for cars and trucks and motorcycles refer to Check compatibility in the Buying Integration Guide
Fields
- compatibilityProperties? AttributeNameValue[] - An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be "name" : "Year", "value" : "2019" For a list of the attributes required for cars and trucks and motorcycles see Check compatibility in the Buy Integration Guide
ebay.browse: CompatibilityProperty
This container returns the product attribute name/value pairs that are compatible with the keyword. These attributes are submitted in the compatibility_filter request field
Fields
- localizedName? string - The name of the product attribute that as been translated to the language of the site
- name? string - The name of the product attribute, such as Make, Model, Year, etc
- value? string - The value for the name attribute, such as BMW, R1200GS, 2011, etc
ebay.browse: CompatibilityResponse
The type that defines the response fields for checkCompatibility
Fields
- compatibilityStatus? string - An enumeration value that tells you if the item is compatible with the product.
The values are:
- COMPATIBLE - Indicates the item is compatible with the product specified in the request.
- NOT_COMPATIBLE - Indicates the item is not compatible with the product specified in the request. Be sure to check all the value fields to ensure they are correct as errors in the value can also cause this response.
- UNDETERMINED - Indicates one or more attributes for the specified product are missing so compatibility cannot be determined. The response returns the attributes that are missing. Code so that your app gracefully handles any future changes to this list. For implementation help, refer to eBay API documentation
- warnings? Error[] - An array of warning messages. These types of errors do not prevent the method from executing but should be checked
ebay.browse: ConditionDescriptor
This type displays additional information about the condition of an item in a structured format
Fields
- values? 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
- name? string - The name of a condition descriptor. The value(s) for this condition descriptor is returned in the associated values array
ebay.browse: ConditionDescriptorValue
This type displays the value(s) associated with the specified condition descriptor name, as well as any additional information about a condition descriptor.
Fields
- additionalInfo? 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
- content? string - The value for the condition descriptor indicated in the associated name field
ebay.browse: ConditionDistribution
The container that defines the fields for the conditions refinements. This container is returned when fieldgroups is set to CONDITION_REFINEMENTS or FULL in the request
Fields
- condition? string - The text describing the condition of the item, such as New or Used. For a list of condition names, refer to Item Condition IDs and Names
- conditionId? string - The identifier of the condition. For example, 1000 is the identifier for NEW
- matchCount? Signed32 - The number of items having the condition
- refinementHref? string - The HATEOAS reference of this condition
ebay.browse: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth OAuth2ClientCredentialsGrantConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
ebay.browse: ConvertedAmount
This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
Fields
- convertedFromCurrency? string - 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. For implementation help, refer to eBay API documentation
- currency? string - 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. For implementation help, refer to eBay API documentation
- convertedFromValue? string - 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
- value? string - 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
ebay.browse: CoreItem
An array of containers with the details for all of the items returned
Fields
- seller? SellerDetail - The type that defines the fields for basic and detailed information about the seller of the item returned by the item resource
- primaryProductReviewRating? ReviewRating - The type that defines the fields for the rating of a product review
- 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. 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
- 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
- quantityLimitPerBuyer? Signed32 - The maximum number for a specific item that one buyer can purchase
- priceDisplayCondition? string - 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. For implementation help, refer to eBay API documentation
- taxes? Taxes[] - The container for the tax information for the item
- 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. Code so that your app gracefully handles any future changes to this list
- price? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- authenticityGuarantee? AuthenticityGuaranteeProgram - A type that identifies whether the item is qualified for the Authenticity Guarantee program
- sellerItemRevision? string - 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
- 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
- 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
- estimatedAvailabilities? 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
- shippingOptions? 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
- 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
- unitPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- image? Image - Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
- 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
- eligibleForInlineCheckout? boolean - 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
- sizeSystem? string - (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
- categoryPath? string - Text that shows the category hierarchy of the item. For example: Computers/Tablets & Networking, Laptops & Netbooks, PC Laptops & Netbooks
- marketingPrice? MarketingPrice - The type that defines the fields that describe a seller discount
- 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
- 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
- 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
- shortDescription? string - This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.)
- itemLocation? Address - The type that defines the fields for an address
- charityTerms? ItemCharityTerms - This type defines the fields for any applicable charity information associated with an item
- itemId? string - The unique RESTful identifier of the item
- buyingOptions? 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
- 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. Code so that your app gracefully handles any future changes to this list
- 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
- itemCreationDate? string - 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
- 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
- bidCount? Signed32 - 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
- qualifiedPrograms? string[] - An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION. 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 only available as a listing feature on the eBay Australia marketplace. The eBay Authenticity Guarantee program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers
- priorityListing? boolean - 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
- 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. 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
- 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
- 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
- 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
- tyreLabelImageUrl? string - The URL to the image that shows the information on the tyre label
- 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
- immediatePay? boolean - A value of true indicates that the seller requires immediate payment from the buyer when purchasing an item. Note: It is possible for this field to be set to true, but not apply in some scenarios. For example, immediate payment is not applicable for auction listings that have a winning bidder, for buyers' purchases that involve the Best Offer feature, or for offline transactions
- title? string - The seller-created title of the item. Maximum Length: 80 characters
- itemAffiliateWebUrl? string - 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.
- The seller enables affiliate tracking for the item by including the X-EBAY-C-ENDUSERCTX request header in the method
- itemEndDate? string - 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
- currentBidPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- authenticityVerification? AuthenticityVerificationProgram - A type that identifies whether the item is from a verified seller
- paymentMethods? PaymentMethod[] - The payment methods for the item, including the payment method types, brands, and instructions for the buyer
- minimumPriceToBid? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- 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
- shipToLocations? ShipToLocations - The type that defines the fields that include and exclude geographic regions affecting where the item can be shipped. The seller defines these regions when listing the item
- 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
- uniqueBidderCount? Signed32 - 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
- 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
- product? Product - The type that defines the fields for the product information of the item
- additionalImages? 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
- lotSize? Signed32 - 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
- availableCoupons? AvailableCoupon[] - A list of available coupons for the item
- 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
- primaryItemGroup? ItemGroupSummary - The type that defines the fields for the details of each item in 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 an item group (parent ID of an item with variations)
- returnTerms? ItemReturnTerms - The type that defines the fields for the seller's return policy
- 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
- 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
- localizedAspects? TypedNameValue[] - An array of containers that show the complete list of the aspect name/value pairs that describe the variation of the item
- 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. For example, the following tells the buyer that the item is 7.99 per 100 grams. "unitPricingMeasure": "100g", "unitPrice": { "value": "7.99", "currency": "GBP"
- 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
- 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
ebay.browse: CouponConstraint
This type is used to provide the expiration date of a coded coupon
Fields
- expirationDate? string - This timestamp provides the expiration date of the coded coupon
ebay.browse: EconomicOperator
The type that provides required Economic Operator information about the manufacturer and/or supplier of the item
Fields
- country? string - The two-letter ISO 3166 standard abbreviation of the country of the registered Economic Operator's address
- stateOrProvince? string - The state or province of the registered Economic Operator's street address
- city? string - The city of the registered Economic Operator's street address
- phone? string - The registered Economic Operator's business phone number
- companyName? string - The company name of the registered Economic Operator
- postalCode? string - The postal code of the registered Economic Operator's street address
- addressLine1? string - The first line of the registered Economic Operator's street address
- 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'
- email? string - The registered Economic Operator's business email address
ebay.browse: Error
The type that defines the fields that can be returned in an error
Fields
- domain? string - The name of the primary system where the error occurred. This is relevant for application errors
- subdomain? string - The name of the subdomain in which the error or warning occurred
- outputRefIds? string[] - An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any
- errorId? Signed32 - 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
- inputRefIds? string[] - An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any
- category? string - This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors
- longMessage? string - A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem
- message? string - A description of the condition that caused the error or warning
- parameters? ErrorParameter[] - 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
ebay.browse: ErrorParameter
An array of name/value pairs that provide details regarding the error
Fields
- name? string - This is the name of input field that caused an issue with the call request
- value? string - This is the actual value that was passed in for the element specified in the name field
ebay.browse: EstimatedAvailability
The type that defines the fields for the estimated item availability information
Fields
- availabilityThresholdType? string - 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.
- estimatedAvailabilityStatus? string - 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. For implementation help, refer to eBay API documentation
- estimatedRemainingQuantity? Signed32 - 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
- availabilityThreshold? Signed32 - 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
- estimatedSoldQuantity? Signed32 - The estimated number of this item that have been sold
- deliveryOptions? string[] - 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
- estimatedAvailableQuantity? Signed32 - 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
ebay.browse: GetItemByLegacyIdHeaders
Represents the Headers record for the operation: getItemByLegacyId
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- xEBAYCENDUSERCTX? string - This header is can be used in following two situations:
- To retrieve the itemAffiliateWebUrl field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see Header for affiliate information.
- If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the shippingOption container, which includes shipping costs and delivery estimates, to be returned. For more information, see Header for shipping information accuracy
ebay.browse: GetItemByLegacyIdQueries
Represents the Queries record for the operation: getItemByLegacyId
Fields
- fieldgroups? string - This field controls what is returned in the response. If this field is not set, the method returns all details about the item. Multiple fieldgroups can be set.
Valid Values:
- PRODUCT This field group adds the product container to the response.
- ADDITIONAL_SELLER_DETAILS This field group adds the userId field to the response.
- CHARITY_DETAILS This field group adds the the charityTerms container to the response, if applicable
- legacyItemId string - This query parameter is the unique identifier that specifies the item being retrieved. Note: When passing in the ID for a multi-variation listing, you must also use the legacy_variation_id field and pass in the ID of the specific item variation. If not, all variation within the multi-SKU listing will be retrieved. The following is an example of using the value of the ItemID field for a specific item to get the RESTful itemId value. browse/v1/item/get_item_by_legacy_id?legacy_item_id=1**********9
- legacyVariationSku? string - This query parameter specifies the legacy SKU of an item. SKUs are the unique identifiers of an item created by the seller. The following is an example of using the value of the ItemID and SKU fields to get the RESTful itemId value. browse/v1/item/get_item_by_legacy_id?legacy_item_id=19&legacy_variation_sku=VM Important! A legacy_item_id value must always be passed in when specifying a legacy_variation_sku value
- legacyVariationId? string - This query parameter specifies the legacy item ID of a specific item in a multi-variation listing, such as that for the red shirt size L item. Important! A legacy_item_id value must always be passed in when specifying a legacy_variation_id value
- quantityForShippingEstimate? string - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the shippingOptions container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1
ebay.browse: GetItemHeaders
Represents the Headers record for the operation: getItem
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- xEBAYCENDUSERCTX? string - This header is can be used in following two situations:
- To retrieve the itemAffiliateWebUrl field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see Header for affiliate information.
- If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the shippingOption container, which includes shipping costs and delivery estimates, to be returned. For more information, see Header for shipping information accuracy
ebay.browse: GetItemQueries
Represents the Queries record for the operation: getItem
Fields
- fieldgroups? 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:
- PRODUCT This field group adds the product container to the response.
- COMPACTThis 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
- immediatePay
- 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:
- Pass in the item ID and set fieldgroups to COMPACT. item/v1|4**********8|0?fieldgroups=COMPACT
- 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.
- CHARITY_DETAILS This adds the the charityTerms container to the response, if applicable
- quantityForShippingEstimate? string - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the shippingOptions container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1
ebay.browse: GetItemsByItemGroupHeaders
Represents the Headers record for the operation: getItemsByItemGroup
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- xEBAYCENDUSERCTX? string - This header is can be used in following two situations:
- To retrieve the itemAffiliateWebUrl field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see Header for affiliate information.
- If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the shippingOption container, which includes shipping costs and delivery estimates, to be returned. For more information, see Header for shipping information accuracy
ebay.browse: GetItemsByItemGroupQueries
Represents the Queries record for the operation: getItemsByItemGroup
Fields
- fieldgroups? string - This field controls what is returned in the response. If this field is not set, the method returns all details about the item. Valid Values: ADDITIONAL_SELLER_DETAILS - This field group adds the userId field to the response. CHARITY_DETAILS - This field group adds the the charityTerms container to the response, if applicable
- itemGroupId string - This query parameter specifies the unique identifier of an item group for which information is to be returned. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. This ID is returned in the itemGroupHref field of the search and getItem methods. For Example: https://api.ebay.com/buy/browse/v1/item/get_items_by_item_group?item_group_id=3**********6
- quantityForShippingEstimate? string - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the shippingOptions container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1
ebay.browse: GetItemsHeaders
Represents the Headers record for the operation: getItems
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- xEBAYCENDUSERCTX? string - This header is can be used in following two situations:
- To retrieve the itemAffiliateWebUrl field in the response, the ePN affiliate can pass in their affiliate credentials using this header. For more information, see Header for affiliate information.
- If the listing is using calculated or flat-rate shipping with shipping rate tables, the user can use this header to provide country and postal code in order for the shippingOption container, which includes shipping costs and delivery estimates, to be returned. For more information, see Header for shipping information accuracy
ebay.browse: GetItemsQueries
Represents the Queries record for the operation: getItems
Fields
- itemGroupIds? string - A comma separated list of the unique identifiers of the item groups being retrieved (maximum 10). Note: In any given request, either item_ids or item_group_ids can be retrieved. Attempting to retrieve both will result in an error. RESTful Group Item ID Format: ############ For example: 3**********9
- itemIds? string - A comma separated list of the unique identifiers of the items to retrieve (maximum 20). Note: In any given request, either item_ids or item_group_ids can be retrieved. Attempting to retrieve both will result in an error. RESTful Item ID Format: v1|#|# For a single SKU listing, pass in the item ID: v1|22|0 For a multi-SKU listing, pass in the identifier of the variation: v1|12|4**********2 For more information about item IDs for RESTful APIs, refer to Item ID legacy API compatibility overview in the Buying Integration Guide
- quantityForShippingEstimate? string - This query parameter sets the item quantity to be used when calculating the shipping estimate information returned in the shippingOptions container of the response. This value must be a positive integer value and should not exceed the quantity available in the listing. This field is not recommended for auction listings, as they will always have a quantity of 1
ebay.browse: HazardousMaterialsLabels
A type that defines the hazardous materials labels for an item
Fields
- additionalInformation? string - Additional information about the hazardous materials labels
- pictograms? HazardPictogram[] - An array of hazard pictograms that apply to the item
- signalWord? string - The signal word for the hazardous materials label (such as Danger or Warning)
- signalWordId? string - The ID of the signal word for the hazardous materials label
- statements? HazardStatement[] - An array of hazard statements for the item
ebay.browse: HazardPictogram
A type that defines the pictogram for the type of hazard that a hazardous material represents
Fields
- pictogramId? string - The ID of the hazard pictogram
- pictogramDescription? string - The description of the hazard pictogram, such as Flammable
- pictogramUrl? string - The URL of the hazard pictogram
ebay.browse: HazardStatement
A type that defines the hazard statement for a hazardous material
Fields
- statementDescription? string - A description of the nature of the hazard, such as whether the material is toxic if swallowed
- statementId? string - The ID of the hazard statement
ebay.browse: Image
Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
Fields
- imageUrl? string - The URL of the image
- width? Signed32 - Reserved for future use
- height? Signed32 - Reserved for future use
ebay.browse: Item
The details of an item that can be purchased
Fields
- seller? SellerDetail - The type that defines the fields for basic and detailed information about the seller of the item returned by the item resource
- primaryProductReviewRating? ReviewRating - The type that defines the fields for the rating of a product review
- 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. 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
- 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
- quantityLimitPerBuyer? Signed32 - The maximum number for a specific item that one buyer can purchase
- priceDisplayCondition? string - 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. For implementation help, refer to eBay API documentation
- taxes? Taxes[] - The container for the tax information for the item
- addonServices? AddonService[] - A list of add-on services that may be selected for the item or that may apply automatically
- ecoParticipationFee? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- 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. Code so that your app gracefully handles any future changes to this list
- price? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- authenticityGuarantee? AuthenticityGuaranteeProgram - A type that identifies whether the item is qualified for the Authenticity Guarantee program
- sellerItemRevision? string - 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
- 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
- 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
- estimatedAvailabilities? 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
- shippingOptions? 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
- 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
- unitPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- image? Image - Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
- productSafetyLabels? ProductSafetyLabels - This type contains seller provided product safety pictograms and statements for the listing
- 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
- eligibleForInlineCheckout? boolean - 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
- sizeSystem? string - (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
- categoryPath? string - Text that shows the category hierarchy of the item. For example: Computers/Tablets & Networking, Laptops & Netbooks, PC Laptops & Netbooks
- marketingPrice? MarketingPrice - The type that defines the fields that describe a seller discount
- 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
- 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
- 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
- shortDescription? string - This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.)
- itemLocation? Address - The type that defines the fields for an address
- charityTerms? ItemCharityTerms - This type defines the fields for any applicable charity information associated with an item
- itemId? string - The unique RESTful identifier of the item
- buyingOptions? 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
- 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. Code so that your app gracefully handles any future changes to this list
- 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
- conditionDescriptors? 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
- itemCreationDate? string - 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
- 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
- bidCount? Signed32 - 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
- qualifiedPrograms? 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 only available as a listing feature on the eBay Australia marketplace. The eBay Authenticity Guarantee program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers
- priorityListing? boolean - 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
- 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. 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
- 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
- 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
- responsiblePersons? ResponsiblePerson[] - This array provides information about one or more EU-based Responsible Persons or entities associated with the listing
- 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
- tyreLabelImageUrl? string - The URL to the image that shows the information on the tyre label
- 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
- immediatePay? boolean - A value of true indicates that the seller requires immediate payment from the buyer when purchasing an item. Note: It is possible for this field to be set to true, but not apply in some scenarios. For example, immediate payment is not applicable for auction listings that have a winning bidder, for buyers purchases that involve the Best Offer feature, or for offline transactions
- title? string - The seller-created title of the item. Maximum Length: 80 characters
- itemAffiliateWebUrl? string - 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.
- The seller enables affiliate tracking for the item by including the X-EBAY-C-ENDUSERCTX request header in the method
- itemEndDate? string - 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
- manufacturer? CompanyAddress - This type is used to provide contact information for the manufacturer of the product
- 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
- currentBidPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- categoryIdPath? string - 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
- authenticityVerification? AuthenticityVerificationProgram - A type that identifies whether the item is from a verified seller
- paymentMethods? PaymentMethod[] - The payment methods for the item, including the payment method types, brands, and instructions for the buyer
- minimumPriceToBid? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- 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
- shipToLocations? ShipToLocations - The type that defines the fields that include and exclude geographic regions affecting where the item can be shipped. The seller defines these regions when listing the item
- 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
- uniqueBidderCount? Signed32 - 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
- 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
- product? Product - The type that defines the fields for the product information of the item
- additionalImages? 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
- lotSize? Signed32 - 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
- warnings? Error[] - An array of warning messages. These types of errors do not prevent the method from executing but should be checked
- availableCoupons? 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
- 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
- sellerCustomPolicies? SellerCustomPolicy[] - A list of the custom policies that are applied to a listing
- primaryItemGroup? ItemGroupSummary - The type that defines the fields for the details of each item in 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 an item group (parent ID of an item with variations)
- returnTerms? ItemReturnTerms - The type that defines the fields for the seller's return policy
- listingMarketplaceId? string - The ID of the eBay marketplace where the item is listed. For implementation help, refer to eBay API documentation
- 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
- 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
- localizedAspects? TypedNameValue[] - An array of containers that show the complete list of the aspect name/value pairs that describe the variation of the item
- hazardousMaterialsLabels? HazardousMaterialsLabels - A type that defines the hazardous materials labels for an item
- 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. For example, the following tells the buyer that the item is 7.99 per 100 grams. "unitPricingMeasure": "100g", "unitPrice": { "value": "7.99", "currency": "GBP"
- 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
- 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
- watchCount? Signed32 - 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
ebay.browse: ItemCharityTerms
This type defines the fields for any applicable charity information associated with an item
Fields
- donationPercentage? decimal - The percentage of the purchase price of the item that the charitable organization (identified in the charityOrgId field) will receive for each sale
- website? string - The URL to the charity's eBay page
- logoImage? Image -
- charityOrgId? string - The eBay-assigned unique identifier of the charitable organization that will receive a percentage of the sales proceeds from the item
- name? string - The name of the charity organization
ebay.browse: ItemGroup
The type that defines the fields for the item details
Fields
- commonDescriptions? CommonDescriptions[] - An array of containers for a description and the item IDs of all the items that have this exact description. Often the item variations within an item group all have the same description. Instead of repeating this description in the item details of each item, a description that is shared by at least one other item is returned in this container. If the description is unique, it is returned in the items.description field
- warnings? Error[] - An array of warning messages. These types of errors do not prevent the method from executing but should be checked
- items? Item[] - An array of containers for all the item variation details, excluding the description
ebay.browse: ItemGroupSummary
The type that defines the fields for the details of each item in 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 an item group (parent ID of an item with variations)
Fields
- 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.
- itemGroupAdditionalImages? 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
- itemGroupImage? Image - Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
- 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.
- itemGroupType? string - 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. For implementation help, refer to eBay API documentation
- 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.
ebay.browse: ItemLocation
The type that defines the fields for the location of an item, such as information typically used for an address, including postal code, county, state/province, street address, city, and country (2-digit ISO code)
Fields
- country? string - The two-letter ISO 3166 standard code that indicates the country in which the item is located. For implementation help, refer to eBay API documentation
- stateOrProvince? string - The state or province in which the item is located
- city? string - The city in which the item is located. Restriction: This field is populated in the search method response only when fieldgroups = EXTENDED
- postalCode? string - The postal code (or zip code in US) where the item is located. Sellers set a postal code 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
- county? string - The county in which the item is located
- addressLine1? string - The first line of the street address
- addressLine2? string - The second line of the street address. This field may contain such values as an apartment or suite number
ebay.browse: ItemReturnTerms
The type that defines the fields for the seller's return policy
Fields
- returnShippingCostPayer? string - 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. For implementation help, refer to eBay API documentation
- refundMethod? string - 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. For implementation help, refer to eBay API documentation
- returnMethod? string - 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. For implementation help, refer to eBay API documentation
- returnsAccepted? boolean - Indicates whether the seller accepts returns for the item
- 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
- 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
- returnInstructions? string - Text written by the seller describing what the buyer needs to do in order to return the item
- returnPeriod? TimeDuration - The type that defines the fields for a period of time in the time-measurement units supplied
ebay.browse: Items
Container for a list of items
Fields
- total? Signed32 - The total number of items retrieved
- warnings? Error[] - An array of warning messages. These types of errors do not prevent the method from executing but should be checked
- items? CoreItem[] - An arraylist of all the items
ebay.browse: ItemSummary
The type that defines the fields for the details of a specific item
Fields
- energyEfficiencyClass? string - This indicates the European energy efficiency rating (EEK) of the item. Energy efficiency ratings apply to products listed by commercial vendors in electronics categories only. Currently, this field is only applicable for the Germany site, and is returned only if the seller specifies the energy efficiency rating through item specifics at listing time. Rating values include A+++, A++, A+, A, B, C, D, E, F, and G
- seller? Seller - The type that defines the fields for basic information about the seller of the item returned by the item_summary resource
- 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
- tyreLabelImageUrl? string - The URL to the image that shows the information on the tyre label
- priceDisplayCondition? string - 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. For implementation help, refer to eBay API documentation
- compatibilityProperties? CompatibilityProperty[] - This container returns only the product attributes that are compatible with the item. These attributes were specified in the compatibility_filter in the request. This means that if you passed in 5 attributes and only 4 are compatible, only those 4 are returned. If none of the attributes are compatible, this container is not returned
- itemGroupType? string - The indicates the item group type. An item group is an item that has various aspect differences, such as color, size, storage capacity, etc. Currently only the SELLER_DEFINED_VARIATIONS is supported and indicates this is an item group created by the seller. Note: This field is returned only for item groups
- leafCategoryIds? string[] - The leaf category IDs of the item. When the item belongs to two leaf categories, the ID values are returned in the order primary, secondary
- title? string - The seller-created title of the item. Maximum Length: 80 characters
- itemAffiliateWebUrl? string - 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 returned only if:
- The marketplace through which the item is being viewed is part of the eBay Partner Network. Currently Singapore (EBAY_SG) is not supported.
- The seller enables affiliate tracking for the item by including the X-EBAY-C-ENDUSERCTX request header in the method
- itemEndDate? string - A timestamp that indicates the date and time a listing is scheduled to end. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which can be converted into the local time of the buyer
- currentBidPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- 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, refer to Item Condition IDs and Names
- thumbnailImages? Image[] - An array of thumbnail images for the item
- price? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- categories? Category[] - This array returns the name and ID of each category associated with the item, including top level, branch, and leaf categories
- itemWebUrl? string - The URL to the View Item page of the item. This enables you to include a "Report Item on eBay" hyperlink that takes the buyer to the View Item page on eBay. From there they can report any issues regarding this item to eBay
- pickupOptions? PickupOptionSummary[] - This container returns the local pickup options available to the buyer. This container is returned only if the user is searching for local pickup items and set the local pickup filters in the method request
- shippingOptions? ShippingOptionSummary[] - This container returns the shipping options available to ship the item
- topRatedBuyingExperience? boolean - This indicates if the item is 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 item in 1 business day with tracking provided; and the added comfort of knowing that this item is from an experienced seller with the highest buyer ratings. For more information, refer to Look for Top Rated Plus Items and Seller performance overview
- unitPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- image? Image - Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
- additionalImages? 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
- availableCoupons? boolean - This boolean attribute indicates if coupons are available for the item. Note: The Browse API only acknowledges item-level coupons. This field will only be returned as true if a coupon is linked with an item. It does not recognize store-level coupons offered by sellers across their entire store
- marketingPrice? MarketingPrice - The type that defines the fields that describe a seller discount
- 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
- shortDescription? string - This text string is derived from the item condition and the item aspects (such as size, color, capacity, model, brand, etc.) Sometimes the title does not provide enough information but the description is too big. Surfacing the shortDescription can often provide buyers with the additional information that could help them make a buying decision. For example: "title": "Petrel U42W FPV Drone RC Quadcopter w/HD Camera Live Video One Key Off / Landing", "shortDescription": "1 U42W Quadcopter. Syma X5SW-V3 Wifi FPV RC Drone Quadcopter 2.4Ghz 6-Axis Gyro with Headless Mode. Syma X20 Pocket Drone 2.4Ghz Mini RC Quadcopter Headless Mode Altitude Hold. One Key Take Off / Landing function: allow beginner to easy to fly the drone without any skill.", Restriction: This field is returned by the search method only when fieldgroups = EXTENDED
- itemLocation? ItemLocation - The type that defines the fields for the location of an item, such as information typically used for an address, including postal code, county, state/province, street address, city, and country (2-digit ISO code)
- itemOriginDate? string - The date and time when the listing was first made available. This date will be retained if an item is relisted. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. This timestamp is used to sort the response when the sort=newlyListed parameter is used. This field is always returned with itemSummaries
- itemId? string - The unique RESTful identifier of the item
- buyingOptions? string[] - A comma separated list of all the purchase options available for the item.
Values Returned:
- 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 Items where the buyer can send the seller a price they are willing to pay for the item. The seller can accept, reject, or send a counter offer. For additional information about Best Offer, refer to Adding Best Offer to your listing and sending offers to buyers.
- CLASSIFIED_AD Indicates that the final sales transaction is to be completed outside of the eBay environment
- condition? string - The text describing the condition of the item, such as New or Used. For a list of condition names, refer to Item Condition IDs and Names
- 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. Note: This field is returned only for item groups
- itemHref? string - The URI for the Browse API getItem method, which can be used to retrieve more details about items in the search results
- listingMarketplaceId? string - The ID of the eBay marketplace on which the seller listed the item. For implementation help, refer to eBay API documentation
- adultOnly? boolean - This indicates if the item is for adults only. For more information about adult-only items on eBay, refer to the Adult items policy
- itemCreationDate? string - The date and time when the item listing was created. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer. This field is always returned with itemSummaries
- bidCount? Signed32 - This integer value indicates the total number of bids that have been placed for an auction item. This field is only returned for auction items
- compatibilityMatch? string - This indicates how well an item matches the compatibility_filter product attributes.
Valid Values:
- EXACT
- POSSIBLE For implementation help, refer to eBay API documentation
- distanceFromPickupLocation? TargetLocation - The type that defines the fields for the distance between the item location and the buyer's location.
- 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. For example, the following tells the buyer that the item is 7.99 per 100 grams. "unitPricingMeasure": "100g", "unitPrice": { "value": "7.99", "currency": "GBP"
- qualifiedPrograms? string[] - An array of the qualified programs available for the item, such as EBAY_PLUS, AUTHENTICITY_GUARANTEE, and AUTHENTICITY_VERIFICATION. 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 only available as a listing feature on the eBay Australia marketplace. The eBay Authenticity Guarantee program enables third-party authenticators to perform authentication verification inspections on items such as watches and sneakers
- priorityListing? boolean - 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. Note: Priority Listing is returned only with a Best Match sort and will not be returned for other sort options
- watchCount? Signed32 - 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 indicating that you want access to Watch Count data in the Browse API
ebay.browse: LegalAddress
Type that defines the fields for the seller's address
Fields
- country? string - The two-letter ISO 3166 standard code for the country of the address. For implementation help, refer to eBay API documentation
- stateOrProvince? string - The state or province of the address
- city? string - The city of the address
- postalCode? string - The postal code of the address
- county? string - The name of the county of the address
- addressLine1? string - The first line of the street address
- 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'
- countryName? string - The name of the country of the address
ebay.browse: MarketingPrice
The type that defines the fields that describe a seller discount
Fields
- discountPercentage? string - This field expresses the percentage of the seller discount based on the value in the originalPrice container
- originalPrice? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- discountAmount? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- priceTreatment? string - 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. For implementation help, refer to eBay API documentation
ebay.browse: OAuth2ClientCredentialsGrantConfig
OAuth2 Client Credentials Grant Configs
Fields
- Fields Included from *OAuth2ClientCredentialsGrantConfig
- tokenUrl string(default "https://api.ebay.com/identity/v1/oauth2/token") - Token URL
ebay.browse: PaymentMethod
Details of a payment method accepted for an item
Fields
- paymentMethodBrands? PaymentMethodBrand[] - The payment method brands, including the payment method brand type and logo image
- sellerInstructions? string[] - The seller instructions to the buyer, such as accepts credit cards or see description
- paymentInstructions? string[] - The payment instructions for the buyer, such as cash in person or contact seller
- paymentMethodType? string - The payment method type, such as credit card or cash. For implementation help, refer to eBay API documentation
ebay.browse: PaymentMethodBrand
Details of a payment method brand accepted for an item
Fields
- logoImage? Image - Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
- paymentMethodBrandType? string - The payment method brand, such as Visa or PayPal. For implementation help, refer to eBay API documentation
ebay.browse: PickupOptionSummary
The type that defines the fields for the local pickup options that are available for the item. It is used by the pickupOptions container
Fields
- pickupLocationType? string - This container returns the local pickup options available to the buyer. Possible values are ARRANGED_LOCATION and STORE
ebay.browse: Product
The type that defines the fields for the product information of the item
Fields
- gtins? 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
- image? Image - Type that defines the details of an image, such as size and image URL. Currently, only imageUrl is populated. The height and width are reserved for future use
- additionalImages? Image[] - An array of containers with the URLs for the product images that are in addition to the primary image.
- description? string - The rich description of an eBay product, which might contain HTML
- additionalProductIdentities? 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
- aspectGroups? AspectGroup[] - An array of containers for the product aspects. Each group contains the aspect group name and the aspect name/value pairs
- mpns? 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
- title? string - The title of the product
- brand? string - The brand associated with product. To identify the product, this is always used along with MPN (manufacturer part number)
ebay.browse: ProductIdentity
The type that defines the fields for the product identifier type/value pairs of product associated with an item
Fields
- identifierValue? string - The product identifier value
- identifierType? string - The type of product identifier, such as UPC and EAN
ebay.browse: ProductSafetyLabelPictogram
This type is used to provide product safety pictogram(s) for the listing
Fields
- pictogramId? string - The identifier of the safety label pictogram
- pictogramDescription? string - The description of the safety label pictogram
- pictogramUrl? string - The URL of the safety label pictogram
ebay.browse: ProductSafetyLabels
This type contains seller provided product safety pictograms and statements for the listing
Fields
- pictograms? 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
- statements? 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
ebay.browse: ProductSafetyLabelStatement
This type is used to describe the seller provided product safety label statement
Fields
- statementDescription? string - A description of the nature of the product safety label statement
- statementId? string - The identifier of the product safety label statement
ebay.browse: RatingHistogram
The type that defines the fields for product ratings. Only products that are in the eBay product catalog can be reviewed and rated
Fields
- count? Signed32 - The total number of user ratings that the product has received
- 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 4.5, and this is the value that would appear in this field
ebay.browse: Refinement
This type defines the fields for the various refinements of an item. You can use the information in this container to create histograms, which help shoppers choose exactly what they want
Fields
- conditionDistributions? ConditionDistribution[] - An array of containers for the all the condition refinements
- dominantCategoryId? string - The identifier of the category that most of the items are part of.
- buyingOptionDistributions? BuyingOptionDistribution[] - An array of containers for the all the buying option refinements
- aspectDistributions? AspectDistribution[] - An array of containers for the all the aspect refinements
- categoryDistributions? CategoryDistribution[] - An array of containers for the all the category refinements
ebay.browse: Region
This type is used to provide region details for a tax jurisdiction
Fields
- regionType? string - 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. For implementation help, refer to eBay API documentation
- 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.
ebay.browse: ResponsiblePerson
This type provides information, such as name and contact details, for an EU-based Responsible Person or entity, associated with the product
Fields
- country? string - The two-letter ISO 3166 standard of the country of the address. For implementation help, refer to eBay API documentation
- types? string[] - The type(s) associated with the Responsible Person or entity
- city? string - The city of the Responsible Person's street address
- companyName? string - The name of the Responsible Person or entity
- postalCode? string - The postal code of the Responsible Person's street address
- county? string - The county of the Responsible Person's street address
- stateOrProvince? string - The state or province of the Responsible Person's street address
- phone? string - The phone number of the Responsible Person's street address
- addressLine1? string - The first line of the Responsible Person's street address
- contactUrl? string - The contact URL of the Responsible Person or entity
- 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'
- countryName? string - The country name of the Responsible Person's street address
- email? string - The email of the Responsible Person's street address
ebay.browse: ReviewRating
The type that defines the fields for the rating of a product review
Fields
- ratingHistograms? RatingHistogram[] - An array of containers for the product rating histograms that shows the review counts and the product rating
- reviewCount? Signed32 - The total number of reviews for the item
- averageRating? string - The average rating given to a product based on customer reviews
ebay.browse: SearchByImageRequest
The type that defines the fields for the image information
Fields
- image? string - The Base64 string of the image. To get the Base64 image string, you can use sites such as https://codebeautify.org/image-to-base64-converter
ebay.browse: SearchItemsByImageHeaders
Represents the Headers record for the operation: searchItemsByImage
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- xEBAYCENDUSERCTX? 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
- contentType string - This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers
ebay.browse: SearchItemsByImageQueries
Represents the Queries record for the operation: searchItemsByImage
Fields
- charityIds? string - The charity ID filters results to return only those items associated with the specified charity.
Note: charity_ids is only supported by the US and UK marketplaces.
Charity ID is a charity's unique identification number:
- In the US, this is the Employer Identification Number (EIN).
- In the UK, this is the Charity Registration Number (CRN), commonly called Charity Number.
- Search for a supported charity using the Charity API's getCharityOrgs method.
- Search for a supported charity by visiting Charity Search. Click on the charity's name to display its information. The EIN number is included in the charity's information block at the top of the page.
- filter? string - An array of field filters that can be used to limit/customize the result set. Refer to Buy API Field Filters for the information about available filters. For example, to filter shirts based on a specific range of prices, include the filter illustrated here: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50] Filters may also be combined within a single request as illustrated in the sample below which further refines results to return only those shirts available from specific sellers: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal} Note: Refer to Buy API Field Filters for additional information and examples of all supported filters. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField
- fieldgroups? string - A comma-separated list of values that controls what is returned in the response. The default is MATCHING_ITEMS, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.
Valid Values:
- ASPECT_REFINEMENTS This field group adds the aspectDistributions container to the response.
- BUYING_OPTION_REFINEMENTS This field group adds the buyingOptionDistributions container to the response.
- CATEGORY_REFINEMENTS This field group adds the categoryDistributions container to the response.
- CONDITION_REFINEMENTS This field group adds the conditionDistributions containers, such as NEW, USED, etc., to the response. Within these groups are multiple states of the condition.
- EXTENDED This field group adds the following fields to the response:
- shortDescription
- itemLocation.city
- MATCHING_ITEMS (default value) This field group is intended to be used with one or more of the refinement values listed above. This is used to return the specified refinements and all matching items.
- FULL This field group returns all refinement containers and all matching items. Default: MATCHING_ITEMS
- offset? string - Specifies the number of items to skip in the result set. This is used with the limit field to control the pagination of the output.
For example:
- If offset is 0 and limit is 10, the method will retrieve items 1-10 from the list of items returned
- If offset is 10 and limit is 10, the method will retrieve items 11-20 from the list of items returned. Note: The value of offset must be either zero or a multiple of the value set in the limit field. An error is returned for invalid offset values. Note: This method can return a maximum of 10,000 items in one results set. Min: 0
- 'limit? string - The number of items from the result set returned in a single page. Note: If a value is set in the limit field, the value of offset must be either zero or a multiple of the limit value. An error is returned for invalid offset values. Note: This method can return a maximum of 10,000 items in one results set. Min: 1 Max: 200 Default: 50
- categoryIds? string - The category ID is used to limit the results that are returned. This field may pass in one category ID or a comma separated list of IDs as illustrated in the following examples:
/buy/browse/v1/item_summary/searchByImage?category_ids=29792
/buy/browse/v1/item_summary/searchByImage?category_ids=267,29792
Note: Currently, you can pass in only one category ID per request.
To refine the set of information that is returned, category_ids may be combined with other available filters.
Because the list of eBay category IDs is not published and category IDs are not the same across all eBay marketplaces, category IDs may be determined by:
- Visiting the Category Changes page
- Using the Taxonomy API. Refer to Get Categories for Buy APIs for complete information.
- Issuing the following call to retrieve the dominantCategoryId for an item: /buy/browse/v1/item_summary/searchByImage?q= keyword&fieldgroups=ASPECT_REFINEMENTS
- sort? string - Note: This call currently returns results in a best-match order. This query parameter presently has no practical use. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:SortField
- aspectFilter? string - This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red.
Note: The category ID must be specified twice:
- Once as a URI parameter in the category_ids field
- Once as part of the aspect_filter field These two values must be the same. For example, to return items for a woman's red shirt, issue the following request:
ebay.browse: SearchItemsHeaders
Represents the Headers record for the operation: searchItems
Fields
- xEBAYCMARKETPLACEID? string - This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: EBAY_US
- acceptLanguage? 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:
- 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
- xEBAYCENDUSERCTX? 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
ebay.browse: SearchItemsQueries
Represents the Queries record for the operation: searchItems
Fields
- charityIds? string - The charity ID filters results to return only those items associated with the specified charity.
Note: charity_ids is only supported by the US and UK marketplaces.
Charity ID is a charity's unique identification number:
- In the US, this is the Employer Identification Number (EIN).
- In the UK, this is the Charity Registration Number (CRN), commonly called Charity Number.
- Search for a supported charity using the Charity API's getCharityOrgs method.
- Search for a supported charity by visiting Charity Search. Click on the charity's name to display its information. The EIN number is included in the charity's information block at the top of the page.
- gtin? string - This field lets you search for a product by specifying a Global Trade Item Number (GTIN) of the product. Supported GTIN types are UPC, EAN, and ISBN. For example: /buy/browse/v1/item_summary/search?gtin=099482432621 Note: When constructing a query, gtin value may be combined with an epid value, but neither an epid or gtin value should be combined with a keywords search through the q parameter
- fieldgroups? string - A comma-separated list of values that controls what is returned in the response. The default is MATCHING_ITEMS, which returns the items that match the keyword or category specified. The other values return data that can be used to create histograms or provide additional information.
Valid Values:
- ASPECT_REFINEMENTS This field group adds the aspectDistributions container to the response.
- BUYING_OPTION_REFINEMENTS This field group adds the buyingOptionDistributions container to the response.
- CATEGORY_REFINEMENTS This field group adds the categoryDistributions container to the response.
- CONDITION_REFINEMENTS This field group adds the conditionDistributions containers, such as NEW, USED, etc., to the response. Within these groups are multiple states of the condition.
- EXTENDED This field group adds the following fields to the response:
- shortDescription
- itemLocation.city
- MATCHING_ITEMS (default value) This field group is intended to be used with one or more of the refinement values listed above. This is used to return the specified refinements and all matching items.
- FULL This field group returns all refinement containers and all matching items. Default: MATCHING_ITEMS
- offset? string - Specifies the number of items to skip in the result set. This is used with the limit field to control the pagination of the output.
For example:
- If offset is 0 and limit is 10, the method will retrieve items 1-10 from the list of items returned
- If offset is 10 and limit is 10, the method will retrieve items 11-20 from the list of items returned. Note: The value of offset must be either zero or a multiple of the value set in the limit field. An error is returned for invalid offset values. Note: This method can return a maximum of 10,000 items in one results set. Min: 0
- epid? string - The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits the results to only items in the specified ePID. Use the product_summary/search method in the Catalog API to search for the ePID of the product. For example: /buy/browse/v1/item_summary/search?epid=15032 Note: When constructing a query, epid may be combined with a gtin value. However, do not specify keywords using the q parameter — keywords cannot be used in conjunction with an epid
- sort? string - Specifies the criteria on which returned items are to be sorted.
Items can be sorted in ascending order based on:
- Price (sort=price) Returned items are sorted based on their total cost (i.e., price + shipping cost).
- The X-EBAY-C-ENDUSERCTX request header is used, and
- The contextualLocation parameter specifies the delivery country and postal code.
- Distance (sort=distance) Returned items are sorted based on their distance from the buyer's location.
- Date Items can be sorted by date based on:
- Listing date (sort=newlyListed) Returned items are sorted based on their itemOriginDate.
- End date (sort=endingSoonest) Returned items are sorted based on the date/time on which their listing is scheduled to end.
- aspectFilter? string - This field lets you filter by item aspects. The aspect name/value pairs and category, which is required, is used to limit the results to specific aspects of the item. For example, in a clothing category one aspect pair would be Color/Red.
Note: The category ID must be specified twice:
- Once as a URI parameter in the category_ids field
- Once as part of the aspect_filter field These two values must be the same. For example, to return items for a woman's red shirt, issue the following request:
- compatibilityFilter? string - This field specifies the attributes used to define a specific product. The service searches for items matching the keyword, or matching the keyword and a product attribute value in the title of the item.
Note: The only products supported are cars, trucks, and motorcycles.
For example, if the keyword is brakes and compatibility-filter=Year:2018;Make:BMW, the items returned are items with brakes, 2018, or BMW in the title.
The service uses the product attributes to determine whether the item is compatible. The service returns the attributes that are compatible and the CompatibilityMatchEnum value that indicates how well the item matches the attributes.
Tip: Refer to the Samples section for a detailed example.
Best Practice: Submit all of the product attributes for the specific product.
To find the attributes and values for a specific marketplace, use the getCompatibilityProperties method in the Taxonomy API.
For more information, refer to Check compatibility in the Buying Integration Guide.
Note: Testing in Sandbox is only supported using mock data. Refer to Testing search in the Sandbox for details.
Required:
- q (keyword)
- One parts-compatibility-supported category ID (such as 33559 Brakes)
- At least one vehicle attribute name/value pair For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/gct:CompatibilityFilter
- filter? string - An array of field filters that can be used to limit/customize the result set. Refer to Buy API Field Filters for additional information and examples of all supported filters. For example, to filter shirts based on a specific range of prices, include the filter illustrated here: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50] Filters may also be combined within a single request as illustrated in the sample below which further refines results to return only those shirts available from specific sellers: /buy/browse/v1/item_summary/search?q=shirt&filter=price:[10..50],sellers:{rpseller|bigSal} For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/buy/browse/types/cos:FilterField
- q? string - A string consisting of one or more keywords used to search for items on eBay.
Note: The * wildcard character is not allowed in this field.
When providing two or more keywords in a single query, the string is processed as follows:
- When successive keywords are separated by a space, the list of keywords is processed as an AND request. For example, to retrieve items that include both of the keywords iphone AND ipad, submit the following query:
- When successive keywords are comma-separated and surrounded by a single pair of parentheses, OR if the keywords are each URL-encoded, the list of keywords is processed as an OR request. For example, to retrieve items that include iphone OR ipad, submit one of the following queries:
- Do not include an epid or gtin parameter value as neither can be used in conjunction with a keyword search.
- Strings longer than 100-characters are truncated.
- 'limit? string - The number of items from the result set returned in a single page. Note: If a value is set in the limit field, the value of offset must be either zero or a multiple of the limit value. An error is returned for invalid offset values. Note: This method can return a maximum of 10,000 items in one results set. Min: 1 Max: 200 Default: 50
- categoryIds? string - The category ID is used to limit the results that are returned. This field may pass in one category ID or a comma separated list of IDs as illustrated in the following examples:
/buy/browse/v1/item_summary/search?category_ids=29792
/buy/browse/v1/item_summary/search?category_ids=267,29792
Note: Currently, you can pass in only one category ID per request.
To refine the set of information that is returned, category_ids may be combined with EITHER:
- epid and/or gtin values
- q keywords For example, when looking of a toy phone, simply searching for "phone" will return mobile phones because that is the "Best Match" for the search. To further refine the request to include toy phones, include the Toys & Hobbies category ID as illustrated here: /buy/browse/v1/item_summary/search?q=phone&category_ids=220 Because the list of eBay category IDs is not published and category IDs are not the same across all eBay marketplaces, category IDs may be determined by:
- Visiting the Category Changes page
- Using the Taxonomy API. Refer to Get Categories for Buy APIs for complete information.
- Issuing the following call to retrieve the dominantCategoryId for an item: /buy/browse/v1/item_summary/search?q= keyword&fieldgroups=ASPECT_REFINEMENTS
- autoCorrect? string - A query parameter that enables auto correction.
A sample is shown below:
/buy/browse/v1/item_summary/search?auto_correct=KEYWORD
Note: Auto correction is currently supported in the following marketplaces:
- United States
- Austria
- Australia
- Canada
- Switzerland
- Germany
- Spain
- France
- United Kingdom
- Ireland
- Italy
ebay.browse: SearchPagedCollection
The type that defines the fields for a paginated result set. The response consists of 0 or more sequenced pages where each page has 0 or more items
Fields
- next? string - The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set. The following example of the search method returns items 5 thru 10 from the list of items found. https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=10
- total? Signed32 - The total number of items that match the input criteria. Note: total is just an indicator of the number of listings for a given query. It could vary based on the number of listings with variations included in the result. It is strongly recommended that total not be used in pagination use cases. Instead, use next to determine the results on the next page
- offset? Signed32 - This value indicates the offset used for current page of items being returned. Assume the initial request used an offset of 0 and a limit of 3. Then in the first page of results, this value would be 0, and items 1-3 are returned. For the second page, this value is 3 and so on
- autoCorrections? AutoCorrections - Spelling corrections applied to the search keyword
- prev? string - The URI for the previous page of results. This is returned if there is a previous page of results from the result set. The following example of the search method returns items 1 thru 5 from the list of items found, which would be the first set of items returned. https://api.ebay.com/buy/v1/item_summary/search?query=t-shirts&limit=5&offset=0
- warnings? Error[] - The container with all the warnings for the request
- itemSummaries? ItemSummary[] - An array of the items on this page. The items are sorted according to the sorting method specified in the request
- 'limit? Signed32 - The value of the limit parameter submitted in the request, which is the maximum number of items to return on a page, from the result set. A result set is the complete set of items returned by the method
- refinement? Refinement - This type defines the fields for the various refinements of an item. You can use the information in this container to create histograms, which help shoppers choose exactly what they want
- href? string - The URI of the current page of results. The following example of the search method returns items 1 thru 5 from the list of items found. https://api.ebay.com/buy/v1/item_summary/search?q=shirt&limit=5&offset=0
ebay.browse: Seller
The type that defines the fields for basic information about the seller of the item returned by the item_summary resource
Fields
- feedbackPercentage? string - The percentage of the total positive feedback
- feedbackScore? Signed32 - The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller
- sellerAccountType? string - Indicates if the seller is a business or an individual. This is determined when the seller registers with eBay:
- If they register for a business account, this value will be BUSINESS.
- If they register for a private account, this value will be INDIVIDUAL. This designation is required by the tax laws in some countries.
- username? string - The user name created by the seller for use on eBay. Note: Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance
ebay.browse: SellerCustomPolicy
The container for custom policies that apply to a listed item
Fields
- description? string - The seller-defined description of the policy
- label? string - The seller-defined label for an individual custom policy
- 'type? string - The type of custom policy, such as PRODUCT_COMPLIANCE or TAKE_BACK. For implementation help, refer to eBay API documentation
ebay.browse: SellerDetail
The type that defines the fields for basic and detailed information about the seller of the item returned by the item resource
Fields
- feedbackPercentage? string - The percentage of the total positive feedback
- feedbackScore? Signed32 - The feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller
- sellerLegalInfo? SellerLegalInfo - The type that defines the fields for the contact information for a 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:
This field is applicable only on the following marketplaces:
- EBAY_AT
- EBAY_BE
- EBAY_CH
- EBAY_DE
- EBAY_ES
- EBAY_FR
- EBAY_GB
- EBAY_IE
- EBAY_IT
- EBAY_PL Note: This field will be returned empty on unsupported marketplaces. Valid Values: BUSINESS or INDIVIDUAL
- 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
- username? string - The user name created by the seller for use on eBay. Note: Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance
ebay.browse: SellerLegalInfo
The type that defines the fields for the contact information for a seller
Fields
- sellerProvidedLegalAddress? LegalAddress - Type that defines the fields for the seller's address
- economicOperator? EconomicOperator - The type that provides required Economic Operator information about the manufacturer and/or supplier of the item
- 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
- legalContactFirstName? string - The seller's first name
- 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
- legalContactLastName? string - The seller's last name
- phone? string - The seller's business phone number
- registrationNumber? string - The seller's registration number. This is information used by some countries
- name? string - The name of the seller's business
- 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”)
- vatDetails? 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
- fax? string - The seller' business fax number
- email? string - The seller's business email address
ebay.browse: ShippingOption
The type that defines the fields for the details of a shipping provider
Fields
- 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. 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
- 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. 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
- shippingCost? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- quantityUsedForEstimate? Signed32 - The number of items used when calculating the estimation information. This field will reflect the value input in the quantity_for_shipping_estimate query parameter
- shipToLocationUsedForEstimate? ShipToLocation - The type that defines the fields for the country and postal code of where an item is to be shipped
- shippingServiceCode? string - The type of shipping service. For example, USPS First Class
- 'type? string - The type of a shipping option, such as EXPEDITED, ONE_DAY, STANDARD, ECONOMY, PICKUP, etc
- 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. This value is returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ), which you can convert into the local time of the buyer
- shippingCostType? string - 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
- trademarkSymbol? string - Any trademark symbol, such as ™ or ®, that needs to be shown in superscript next to the shipping service name
- 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
- importCharges? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- shippingCarrierCode? string - The name of the shipping provider, such as FedEx, or USPS
- fulfilledThrough? string - 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. For implementation help, refer to eBay API documentation
- additionalShippingCostPerUnit? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
ebay.browse: ShippingOptionSummary
The type that defines the fields for the shipping information
Fields
- 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. Note: For the best accuracy, always include the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header. Note: Estimated delivery dates are not returned for CBT items
- 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
- 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. Note: For the best accuracy, always include the contextualLocation values in the X-EBAY-C-ENDUSERCTX request header. Note: Estimated delivery dates are not returned for CBT items
- shippingCost? ConvertedAmount - This type defines the monetary value of an amount. It can provide the amount in both the currency used on the eBay site where an item is being offered and the conversion of that value into another currency, if applicable
- shippingCostType? string - Indicates the type of shipping used to ship the item. Possible values are FIXED (flat-rate shipping) and CALCULATED (shipping cost calculated based on item and buyer location)
ebay.browse: ShipToLocation
The type that defines the fields for the country and postal code of where an item is to be shipped
Fields
- country? string - The two-letter ISO 3166 standard of the country for where the item is to be shipped. For implementation help, refer to eBay API documentation
- postalCode? string - The zip code (postal code) for where the item is to be shipped
ebay.browse: ShipToLocations
The type that defines the fields that include and exclude geographic regions affecting where the item can be shipped. The seller defines these regions when listing the item
Fields
- regionIncluded? 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
- regionExcluded? 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
ebay.browse: ShipToRegion
This type is used provide details about included and excluded shipping regions
Fields
- 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. 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)
- regionType? string - 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.
- 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. 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
ebay.browse: TargetLocation
The type that defines the fields for the distance between the item location and the buyer's location.
Fields
- unitOfMeasure? string - This value shows the unit of measurement used to measure the distance between the location of the item and the buyer's location. This value is typically mi or km
- value? string - This value indicates the distance (measured in the measurement unit in the unitOfMeasure field) between the item location and the buyer's location
ebay.browse: Taxes
The type that defines the tax fields
Fields
- includedInPrice? boolean - This indicates if tax was applied for the cost of the item
- taxPercentage? string - The percentage of tax
- ebayCollectAndRemitTax? boolean - 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
- shippingAndHandlingTaxed? boolean - This indicates if tax is applied for the shipping cost
- taxJurisdiction? TaxJurisdiction - The type that defines the fields for the tax jurisdiction details
- taxType? string - This field indicates the type of tax that may be collected for the item. For implementation help, refer to eBay API documentation
ebay.browse: TaxJurisdiction
The type that defines the fields for the tax jurisdiction details
Fields
- region? Region - This type is used to provide region details for a tax jurisdiction
- taxJurisdictionId? string - The identifier of the tax jurisdiction
ebay.browse: TimeDuration
The type that defines the fields for a period of time in the time-measurement units supplied
Fields
- unit? string - 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. For implementation help, refer to eBay API documentation
- value? Signed32 - 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
ebay.browse: TypedNameValue
The type that defines the fields for the name/value pairs for item aspects
Fields
- name? string - The text representing the name of the aspect for the name/value pair, such as Color
- 'type? string - 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. For implementation help, refer to eBay API documentation
- value? string - The value of the aspect for the name/value pair, such as Red
ebay.browse: VatDetail
The type the defines the fields for the VAT (value add tax) information
Fields
- issuingCountry? string - 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. For implementation help, refer to eBay API documentation
- vatId? string - The seller's VAT (value added tax) ID. VAT is a tax added by some European countries
Import
import ballerinax/ebay.browse;Metadata
Released date: about 19 hours ago
Version: 2.0.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-20 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 57
Current verison: 1
Weekly downloads
Keywords
Vendor/eBay
Area/E-Commerce
Type/Connector
Contributors