Buy Marketing API — client.buy.marketing¶
Version 1.1.0 · base path /buy/marketing/v1 · async twin: the same methods on
AsyncEbayClient, awaited.
Operations¶
Bases: BaseResource
get_merchandised_products ¶
get_merchandised_products(*, category_id: str, metric_name: str, aspect_filter: str | None = None, limit: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> buy_marketing_models.BestSellingProductResponse
get_merchandised_products(*, category_id: str, metric_name: str, aspect_filter: str | None = None, limit: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_merchandised_products(*, category_id: str, metric_name: str, aspect_filter: str | None = None, limit: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> buy_marketing_models.BestSellingProductResponse | httpx.Response
This method returns an array of products based on the category and metric specified. This includes details of the product, such as the eBay product ID (EPID), title, and user reviews and ratings for the product. You can use the epid returned by this method in the Browse API search method to retrieve items for this product.
get_most_watched_items ¶
get_most_watched_items(*, category_id: str, accept_language: str | None = None, max_results: str | None = None, x_ebay_c_enduserctx: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> buy_marketing_models.MostWatchedItemsResponse
get_most_watched_items(*, category_id: str, accept_language: str | None = None, max_results: str | None = None, x_ebay_c_enduserctx: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_most_watched_items(*, category_id: str, accept_language: str | None = None, max_results: str | None = None, x_ebay_c_enduserctx: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> buy_marketing_models.MostWatchedItemsResponse | httpx.Response
This method retrieves items with the highest watch counts in a specific category. The leaf category for which to retrieve items with the highest watch counts is specified by its category_id value. Up to 50 items can be returned for a specific category using this method. The number of items to return using this method can be specified through the max_result query parameter.
get_similar_items ¶
get_similar_items(*, item_id: str, accept_language: str | None = None, buying_option: str | None = None, excluded_category_ids: str | None = None, filter: str | None = None, max_results: str | None = None, x_ebay_c_enduserctx: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[False] = False) -> buy_marketing_models.SimilarItemsResponse
get_similar_items(*, item_id: str, accept_language: str | None = None, buying_option: str | None = None, excluded_category_ids: str | None = None, filter: str | None = None, max_results: str | None = None, x_ebay_c_enduserctx: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_similar_items(*, item_id: str, accept_language: str | None = None, buying_option: str | None = None, excluded_category_ids: str | None = None, filter: str | None = None, max_results: str | None = None, x_ebay_c_enduserctx: str | None = None, x_ebay_c_marketplace_id: str | None = None, raw_response: bool = False) -> buy_marketing_models.SimilarItemsResponse | httpx.Response
This method retrieves items that are similar to the specified item. Items are considered similar if they can serve as a replacement or alternative for the specified item. Similar items from a catalog are associated with the same product. For items not associated with a product, similarity is determined by keywords in the title and attribute value matches.
Models¶
Category ¶
Bases: EbayModel
category_id
class-attribute
instance-attribute
¶
category_id = Field(None, alias='categoryId', description='The unique identifier of the leaf category for this item. A leaf category is the lowest level in that category and has no children.')
category_name
class-attribute
instance-attribute
¶
category_name = Field(None, alias='categoryName', description='The name of the category the item is listed in.')
CountryCodeEnum ¶
Bases: OpenStrEnum
CurrencyCodeEnum ¶
Bases: OpenStrEnum
ErrorParameter ¶
ErrorParameterV3 ¶
Bases: EbayModel
name
class-attribute
instance-attribute
¶
name = Field(None, description='This is the name of input field that caused an issue with the call request.')
value
class-attribute
instance-attribute
¶
value = Field(None, description='This is the actual value that was passed in for the element specified in the name field.')
Image ¶
Bases: EbayModel
height
class-attribute
instance-attribute
¶
height = Field(None, description='Reserved for future use.')
image_url
class-attribute
instance-attribute
¶
image_url = Field(None, alias='imageUrl', description='The URL of the image.')
width
class-attribute
instance-attribute
¶
width = Field(None, description='Reserved for future use.')
ItemLocation ¶
Bases: EbayModel
country
class-attribute
instance-attribute
¶
country = Field(None, description='The two-letter ISO 3166 standard code that indicates the country in which the item is located.')
MarketplaceIdEnum ¶
Bases: OpenStrEnum
RangeValue ¶
Bases: EbayModel
end
class-attribute
instance-attribute
¶
end = Field(None, description='Specifies the end or upper limit of the range. This can be empty which equates to greater than or equal to the start or lower limit.')
exclusive_end
class-attribute
instance-attribute
¶
exclusive_end = Field(None, alias='exclusiveEnd', description='Specifies whether the end value is to be included in the range. For example, if end was 100, and exclusiveEnd was true, the end range would be < 100. But if it was set to false, it would be <= 100.')
exclusive_start
class-attribute
instance-attribute
¶
exclusive_start = Field(None, alias='exclusiveStart', description='Specifies whether the start value is to be included in the range. For example, if start was 60, and exclusiveStart was true, the start range would be > 60. But if it was set to false, it would be >= 60.')
start
class-attribute
instance-attribute
¶
start = Field(None, description='Specifies the start or lower limit of the range. This can be empty which equates to lesser than or equal to the end or upper limit.')
RatingAspectDistribution ¶
Bases: EbayModel
count
class-attribute
instance-attribute
¶
count = Field(None, description='The number of eBay users that choose this rating aspect value.')
percentage
class-attribute
instance-attribute
¶
percentage = Field(None, description='The percentage of the aspect rating value. ratingAspectDistributions.percentage = ratingAspectDistributions.count / ratingAspects.count')
value
class-attribute
instance-attribute
¶
value = Field(None, description='The rating aspect. For example: TRUE or FALSE')
Amount ¶
Bases: EbayModel
currency
class-attribute
instance-attribute
¶
currency = Field(None, description='The three-letter ISO 4217 code representing the currency of the amount in the value field.')
value
class-attribute
instance-attribute
¶
value = Field(None, description='The monetary amount, in the currency specified by the currency field.')
Error ¶
Bases: EbayModel
category
class-attribute
instance-attribute
¶
category = Field(None, description='Identifies the type of error.')
domain
class-attribute
instance-attribute
¶
domain = Field(None, description='Name for the primary system where the error occurred. This is relevant for application errors.')
error_id
class-attribute
instance-attribute
¶
error_id = Field(None, alias='errorId', description='A unique number to identify the error.')
input_ref_ids
class-attribute
instance-attribute
¶
input_ref_ids = Field(None, alias='inputRefIds', description='An array of request elements most closely associated to the error.')
long_message
class-attribute
instance-attribute
¶
long_message = Field(None, alias='longMessage', description='A more detailed explanation of the error.')
message
class-attribute
instance-attribute
¶
message = Field(None, description="Information on how to correct the problem, in the end user's terms and language where applicable.")
output_ref_ids
class-attribute
instance-attribute
¶
output_ref_ids = Field(None, alias='outputRefIds', description='An array of request elements most closely associated to the error.')
parameters
class-attribute
instance-attribute
¶
parameters = Field(None, description='An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.')
subdomain
class-attribute
instance-attribute
¶
subdomain = Field(None, description='Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.')
ErrorDetailV3 ¶
Bases: EbayModel
category
class-attribute
instance-attribute
¶
category = Field(None, description='This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.')
domain
class-attribute
instance-attribute
¶
domain = Field(None, description='The name of the primary system where the error occurred. This is relevant for application errors.')
error_id
class-attribute
instance-attribute
¶
error_id = Field(None, alias='errorId', description='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.')
input_ref_ids
class-attribute
instance-attribute
¶
input_ref_ids = Field(None, alias='inputRefIds', description='An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.')
long_message
class-attribute
instance-attribute
¶
long_message = Field(None, alias='longMessage', description='A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.')
message
class-attribute
instance-attribute
¶
message = Field(None, description='A description of the condition that caused the error or warning.')
output_ref_ids
class-attribute
instance-attribute
¶
output_ref_ids = Field(None, alias='outputRefIds', description='An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.')
parameters
class-attribute
instance-attribute
¶
parameters = Field(None, description='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.')
subdomain
class-attribute
instance-attribute
¶
subdomain = Field(None, description='The name of the subdomain in which the error or warning occurred.')
FilterField ¶
Bases: EbayModel
field
class-attribute
instance-attribute
¶
field = Field(None, description='Provides a way to specify a field in a filter.')
negated
class-attribute
instance-attribute
¶
negated = Field(None, description='Note: Currently this filter is not supported.')
range
class-attribute
instance-attribute
¶
range = Field(None, description='Provides a way to specify a range of values in a filter.')
value
class-attribute
instance-attribute
¶
value = Field(None, description='Provides a way a value in a filter.')
MarketPriceDetail ¶
Bases: EbayModel
condition_group
class-attribute
instance-attribute
¶
condition_group = Field(None, alias='conditionGroup', description='The type that defines the fields for details about the product, such as condition and estimated start price.')
condition_ids
class-attribute
instance-attribute
¶
condition_ids = Field(None, alias='conditionIds', description='An array of condition identifiers for the product.')
estimated_start_price
class-attribute
instance-attribute
¶
estimated_start_price = Field(None, alias='estimatedStartPrice', description='The lowest priced active item for this product on eBay.')
MarketingAspectFilter ¶
Bases: EbayModel
filters
class-attribute
instance-attribute
¶
filters = Field(None, description='This field supports field filters that can be used to use to limit/customize the result set.')
MostWatchedItem ¶
Bases: EbayModel
bid_count
class-attribute
instance-attribute
¶
bid_count = Field(None, alias='bidCount', description='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.')
category
class-attribute
instance-attribute
¶
category = Field(None, description='The ID of the leaf category for this item.')
current_bid_price
class-attribute
instance-attribute
¶
current_bid_price = Field(None, alias='currentBidPrice', description='The container that returns the current highest bid for an auction item. The value field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This container will only be returned for auction items.')
gallery_image_url
class-attribute
instance-attribute
¶
gallery_image_url = Field(None, alias='galleryImageUrl', description='The URL for the image used as the Gallery thumbnail.')
item_end_date
class-attribute
instance-attribute
¶
item_end_date = Field(None, alias='itemEndDate', description='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.')
item_id
class-attribute
instance-attribute
¶
item_id = Field(None, alias='itemId', description='The unique RESTful identifier of the item.')
item_location
class-attribute
instance-attribute
¶
item_location = Field(None, alias='itemLocation', description='This container returns the 2-digit ISO code of the country in which the item is location.')
item_web_url
class-attribute
instance-attribute
¶
item_web_url = Field(None, alias='itemWebUrl', description='The URL to the View Item page of the item.')
listing_marketplace_id
class-attribute
instance-attribute
¶
listing_marketplace_id = Field(None, alias='listingMarketplaceId', description='The unique identifier of the eBay marketplace of the listing.')
price
class-attribute
instance-attribute
¶
price = Field(None, description='The price of the item. This field will only be returned for fixed-price listings and auction listings that are enabled with the Buy it Now feature.')
shipping_cost
class-attribute
instance-attribute
¶
shipping_cost = Field(None, alias='shippingCost', description='The final shipping cost of the item.')
shipping_cost_type
class-attribute
instance-attribute
¶
shipping_cost_type = Field(None, alias='shippingCostType', description='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).')
subtitle
class-attribute
instance-attribute
¶
subtitle = Field(None, description='A subtitle is optional and allows the seller to provide more information about the item, possibly including keywords that may assist with search results.')
title
class-attribute
instance-attribute
¶
title = Field(None, description='The title of the item as its appears on the listing.')
watch_count
class-attribute
instance-attribute
¶
watch_count = Field(None, alias='watchCount', description='The number of users that have added the item to their watch list.')
MostWatchedItemsResponse ¶
Bases: EbayModel
most_watched_items
class-attribute
instance-attribute
¶
most_watched_items = Field(None, alias='mostWatchedItems', description='This array returns a list of most watched items matching the input criteria.')
RatingAspect ¶
Bases: EbayModel
count
class-attribute
instance-attribute
¶
count = Field(None, description='The number of eBay users that rated the product on this aspect.')
description
class-attribute
instance-attribute
¶
description = Field(None, description='The name of the rating aspect. Camping tent examples: Is it lightweight? or Is it easy to set up?')
name
class-attribute
instance-attribute
¶
name = Field(None, description='The answer or value of the rating aspect. Camping tent examples: Lightweight or Easy to set up')
rating_aspect_distributions
class-attribute
instance-attribute
¶
rating_aspect_distributions = Field(None, alias='ratingAspectDistributions', description='The container for the details of the aspect rating. The details show the aspect rating value, usually TRUE or FALSE and the user count and percentage.')
SimilarItem ¶
Bases: EbayModel
bid_count
class-attribute
instance-attribute
¶
bid_count = Field(None, alias='bidCount', description='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.')
current_bid_price
class-attribute
instance-attribute
¶
current_bid_price = Field(None, alias='currentBidPrice', description='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.')
gallery_image_url
class-attribute
instance-attribute
¶
gallery_image_url = Field(None, alias='galleryImageUrl', description='The container that returns the current highest bid for an auction item. The value field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This container will only be returned for auction items.')
item_end_date
class-attribute
instance-attribute
¶
item_end_date = Field(None, alias='itemEndDate', description='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.')
item_id
class-attribute
instance-attribute
¶
item_id = Field(None, alias='itemId', description='The unique RESTful identifier of the item.')
item_location
class-attribute
instance-attribute
¶
item_location = Field(None, alias='itemLocation', description='This container returns the 2-digit ISO code of the country in which the item is location.')
item_web_url
class-attribute
instance-attribute
¶
item_web_url = Field(None, alias='itemWebUrl', description='The URL to the View Item page of the listing.')
listing_marketplace_id
class-attribute
instance-attribute
¶
listing_marketplace_id = Field(None, alias='listingMarketplaceId', description='The unique identifier of the eBay marketplace of the listing.')
price
class-attribute
instance-attribute
¶
price = Field(None, description='The price of the item. This field will only be returned for fixed-price listings and auction listings that are enabled with the Buy it Now feature.')
primary_category
class-attribute
instance-attribute
¶
primary_category = Field(None, alias='primaryCategory', description='This container returns the category name and ID of the primary listing category.')
shipping_cost
class-attribute
instance-attribute
¶
shipping_cost = Field(None, alias='shippingCost', description='The final shipping cost for all the item.')
shipping_cost_type
class-attribute
instance-attribute
¶
shipping_cost_type = Field(None, alias='shippingCostType', description='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).')
subtitle
class-attribute
instance-attribute
¶
subtitle = Field(None, description='A subtitle is optional and allows the seller to provide more information about the item, possibly including keywords that may assist with search results.')
title
class-attribute
instance-attribute
¶
title = Field(None, description='The title of the item as its appears on the listing.')
SimilarItemsResponse ¶
Bases: EbayModel
similar_items
class-attribute
instance-attribute
¶
similar_items = Field(None, alias='similarItems', description='This array returns a list of similar items matching the input criteria.')
MerchandisedProduct ¶
Bases: EbayModel
average_rating
class-attribute
instance-attribute
¶
average_rating = Field(None, alias='averageRating', description='The average rating for the product based on eBay user ratings.')
epid
class-attribute
instance-attribute
¶
epid = Field(None, description='The eBay product identifier of a product from the eBay product catalog. You can use this value in the Browse API search method to retrieve items for this product.')
market_price_details
class-attribute
instance-attribute
¶
market_price_details = Field(None, alias='marketPriceDetails', description='An array of containers for the product market price details, such as condition and market price.')
rating_aspects
class-attribute
instance-attribute
¶
rating_aspects = Field(None, alias='ratingAspects', description='An array of containers for ratings of the product aspects, such as "Is it a good value".')
rating_count
class-attribute
instance-attribute
¶
rating_count = Field(None, alias='ratingCount', description='The total number of eBay users that rated the product.')
review_count
class-attribute
instance-attribute
¶
review_count = Field(None, alias='reviewCount', description='The total number of eBay users that wrote a review for the product.')
title
class-attribute
instance-attribute
¶
title = Field(None, description='The title of the product.')
BestSellingProductResponse ¶
Bases: EbayModel
merchandised_products
class-attribute
instance-attribute
¶
merchandised_products = Field(None, alias='merchandisedProducts', description='An array of containers for the products.')
warnings
class-attribute
instance-attribute
¶
warnings = Field(None, description='The container with all the warnings for the input request.')