Deal API — client.buy.deal¶
Version v1.3.0 · base path /buy/deal/v1 · async twin: the same methods on
AsyncEbayClient, awaited.
Operations¶
Bases: BaseResource
get_deal_items ¶
get_deal_items(*, category_ids: str | None = None, commissionable: str | None = None, delivery_country: str | None = None, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[False] = False) -> buy_deal_models.DealItemSearchResponse
get_deal_items(*, category_ids: str | None = None, commissionable: str | None = None, delivery_country: str | None = None, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_deal_items(*, category_ids: str | None = None, commissionable: str | None = None, delivery_country: str | None = None, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: bool = False) -> buy_deal_models.DealItemSearchResponse | httpx.Response
This method retrieves a paginated set of deal items. The result set contains all deal items associated with the specified search criteria and marketplace ID. This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see Buy API Requirements .
get_event ¶
get_event(event_id: str, *, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[False] = False) -> buy_deal_models.Event
get_event(event_id: str, *, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_event(event_id: str, *, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: bool = False) -> buy_deal_models.Event | httpx.Response
This method retrieves the details for an eBay event. The result set contains detailed information associated with the specified event ID, such as applicable coupons, start and end dates, and event terms. This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see Buy API Requirements .
get_events ¶
get_events(*, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[False] = False) -> buy_deal_models.EventSearchResponse
get_events(*, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_events(*, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: bool = False) -> buy_deal_models.EventSearchResponse | httpx.Response
This method returns paginated results containing all eBay events for the specified marketplace. This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see Buy API Requirements .
get_event_items ¶
get_event_items(*, event_ids: str, category_ids: str | None = None, delivery_country: str | None = None, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[False] = False) -> buy_deal_models.EventItemSearchResponse
get_event_items(*, event_ids: str, category_ids: str | None = None, delivery_country: str | None = None, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: Literal[True]) -> httpx.Response
get_event_items(*, event_ids: str, category_ids: str | None = None, delivery_country: str | None = None, limit: int | str | None = None, offset: int | str | None = None, x_ebay_c_marketplace_id: str | None = None, x_ebay_c_enduserctx: str | None = None, raw_response: bool = False) -> buy_deal_models.EventItemSearchResponse | httpx.Response
This method returns a paginated set of event items. The result set contains all event items associated with the specified search criteria and marketplace ID. This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see Buy API Requirements .
Models¶
CurrencyCodeEnum ¶
Bases: OpenStrEnum
ErrorParameter ¶
Image ¶
Bases: EbayModel
height
class-attribute
instance-attribute
¶
height = Field(None, description='The height of the image.')
image_url
class-attribute
instance-attribute
¶
image_url = Field(None, alias='imageUrl', description='The relative path to the image location.')
text
class-attribute
instance-attribute
¶
text = Field(None, description='The text associated with the image.')
width
class-attribute
instance-attribute
¶
width = Field(None, description='The width of the image.')
ItemGroupTypeEnum ¶
Bases: OpenStrEnum
seller_defined_variations
class-attribute
instance-attribute
¶
seller_defined_variations = 'SELLER_DEFINED_VARIATIONS'
PriceTreatmentEnum ¶
ProgramEnum ¶
Bases: OpenStrEnum
Terms ¶
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. Default: The currency of the authenticated user's country.")
value
class-attribute
instance-attribute
¶
value = Field(None, description='The monetary value, in the currency specified by the currency field.')
Coupon ¶
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.')
Event ¶
Bases: EbayModel
applicable_coupons
class-attribute
instance-attribute
¶
applicable_coupons = Field(None, alias='applicableCoupons', description='A list of coupons associated with the event.')
description
class-attribute
instance-attribute
¶
description = Field(None, description='The event description.')
end_date
class-attribute
instance-attribute
¶
end_date = Field(None, alias='endDate', description='The end date for the event.')
event_affiliate_web_url
class-attribute
instance-attribute
¶
event_affiliate_web_url = Field(None, alias='eventAffiliateWebUrl', description='The URL of the View Event page for the event, which includes the affiliate tracking ID.')
event_id
class-attribute
instance-attribute
¶
event_id = Field(None, alias='eventId', description='The unique identifier for the event.')
event_web_url
class-attribute
instance-attribute
¶
event_web_url = Field(None, alias='eventWebUrl', description='The web URL for the event.')
images
class-attribute
instance-attribute
¶
images = Field(None, description='The images for the event.')
start_date
class-attribute
instance-attribute
¶
start_date = Field(None, alias='startDate', description='The start date for the event.')
terms
class-attribute
instance-attribute
¶
terms = Field(None, description='The terms associated with the event.')
title
class-attribute
instance-attribute
¶
title = Field(None, description='The title of the event.')
EventSearchResponse ¶
Bases: EbayModel
events
class-attribute
instance-attribute
¶
events = Field(None, description='A list of results that match the search criteria.')
href
class-attribute
instance-attribute
¶
href = Field(None, description='The relative path to the current set of results.')
limit
class-attribute
instance-attribute
¶
limit = Field(None, description='The maximum number of items, from the current result set, returned on a single page. Default: 20')
next
class-attribute
instance-attribute
¶
next = Field(None, description='The relative path to the next set of results.')
offset
class-attribute
instance-attribute
¶
offset = Field(None, description='The number of items that will be skipped in the result set. This is used with the limit field to control the pagination of the output. For example, if the offset is set to 0 and the limit is set to 10 , the method will retrieve items 1 through 10 from the list of items returned.')
prev
class-attribute
instance-attribute
¶
prev = Field(None, description='The relative path to the previous set of results.')
total
class-attribute
instance-attribute
¶
total = Field(None, description='The total number of matches for the specified search criteria.')
MarketingPrice ¶
Bases: EbayModel
discount_amount
class-attribute
instance-attribute
¶
discount_amount = Field(None, alias='discountAmount', description='The monetary value of the seller discount.')
discount_percentage
class-attribute
instance-attribute
¶
discount_percentage = Field(None, alias='discountPercentage', description='The percentage of the seller discount based on the value returned in the originalPrice field.')
original_price
class-attribute
instance-attribute
¶
original_price = Field(None, alias='originalPrice', description='The monetary value of the item prior to the discount.')
price_treatment
class-attribute
instance-attribute
¶
price_treatment = Field(None, alias='priceTreatment', description='The pricing treatment (discount) that was applied to the price of the item. Note: The pricing treatment affects how and where the discounted price can be displayed.')
ShippingOption ¶
Bases: EbayModel
shipping_cost
class-attribute
instance-attribute
¶
shipping_cost = Field(None, alias='shippingCost', description='The final shipping cost for all items after all discounts are applied. Note: The price does include the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB ) to see the VAT-inclusive pricing.')
shipping_cost_type
class-attribute
instance-attribute
¶
shipping_cost_type = Field(None, alias='shippingCostType', description='The class of the shipping cost. Valid Values: FIXED or CALCULATED Code so that your app gracefully handles any future changes to this list.')
DealItem ¶
Bases: EbayModel
additional_images
class-attribute
instance-attribute
¶
additional_images = Field(None, alias='additionalImages', description='The additional images for the deal item.')
category_ancestor_ids
class-attribute
instance-attribute
¶
category_ancestor_ids = Field(None, alias='categoryAncestorIds', description='The IDs of the ancestors for the primary category.')
category_id
class-attribute
instance-attribute
¶
category_id = Field(None, alias='categoryId', description='The ID of the leaf category for the deal item. A leaf category is the lowest level in a category and has no children.')
commissionable
class-attribute
instance-attribute
¶
commissionable = Field(None, description='A boolean value specifying whether the listing has commission.')
deal_affiliate_web_url
class-attribute
instance-attribute
¶
deal_affiliate_web_url = Field(None, alias='dealAffiliateWebUrl', description='The deal associated with the item with affiliate attribution.')
deal_end_date
class-attribute
instance-attribute
¶
deal_end_date = Field(None, alias='dealEndDate', description='The date after which the deal ends.')
deal_start_date
class-attribute
instance-attribute
¶
deal_start_date = Field(None, alias='dealStartDate', description='The date on which the deal starts.')
deal_web_url
class-attribute
instance-attribute
¶
deal_web_url = Field(None, alias='dealWebUrl', description='The web URL for the deal associated with the item.')
energy_efficiency_class
class-attribute
instance-attribute
¶
energy_efficiency_class = Field(None, alias='energyEfficiencyClass', description='A string value specifying the Energy Efficiency class.')
image
class-attribute
instance-attribute
¶
image = Field(None, description='The primary image for the deal item.')
item_affiliate_web_url
class-attribute
instance-attribute
¶
item_affiliate_web_url = Field(None, alias='itemAffiliateWebUrl', description='The item web URL with affiliate attribution.')
item_group_id
class-attribute
instance-attribute
¶
item_group_id = Field(None, alias='itemGroupId', description='The unique identifier for the deal item group. This is the parent item ID for the seller-defined variations. Note: This field is returned for multiple-SKU items.')
item_group_type
class-attribute
instance-attribute
¶
item_group_type = Field(None, alias='itemGroupType', description='An enumeration value that indicates the type of item group. An item group contains items that have various aspect differences, such as color, size, or storage capacity.')
item_id
class-attribute
instance-attribute
¶
item_id = Field(None, alias='itemId', description='The unique identifier for the deal item. Note: This field is only returned for single-SKU items.')
item_web_url
class-attribute
instance-attribute
¶
item_web_url = Field(None, alias='itemWebUrl', description='The web URL for the deal item.')
legacy_item_id
class-attribute
instance-attribute
¶
legacy_item_id = Field(None, alias='legacyItemId', description='The legacy item ID associated with the deal item.')
marketing_price
class-attribute
instance-attribute
¶
marketing_price = Field(None, alias='marketingPrice', description='The original price for the deal item, and the discount amount and percentage.')
price
class-attribute
instance-attribute
¶
price = Field(None, description='The price for the deal item. Note: The price does include the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB ) to see the VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU .')
qualified_programs
class-attribute
instance-attribute
¶
qualified_programs = Field(None, alias='qualifiedPrograms', description='A list of programs applicable to the item.')
shipping_options
class-attribute
instance-attribute
¶
shipping_options = Field(None, alias='shippingOptions', description='The cost required to ship the deal item. Note: For items with calculated shipping, this array is only returned if the X-EBAY-C-ENDUSERCTX header is supplied.')
title
class-attribute
instance-attribute
¶
title = Field(None, description='The title of the deal item.')
unit_price
class-attribute
instance-attribute
¶
unit_price = Field(None, alias='unitPrice', description='The price per unit for the deal item. Some European countries require listings for certain types of products to include the price per unit so that buyers can accurately compare prices. For example: "unitPricingMeasure": "100g", "unitPrice": { "value": "7.99", "currency": "GBP"')
unit_pricing_measure
class-attribute
instance-attribute
¶
unit_pricing_measure = Field(None, alias='unitPricingMeasure', description='The designation used to specify the quantity of the deal item, such as size, weight, volume, and count. 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"')
DealItemSearchResponse ¶
Bases: EbayModel
deal_items
class-attribute
instance-attribute
¶
deal_items = Field(None, alias='dealItems', description='A list of deal items that match the search criteria.')
href
class-attribute
instance-attribute
¶
href = Field(None, description='The relative path to the current set of results.')
limit
class-attribute
instance-attribute
¶
limit = Field(None, description='The maximum number of items, from the current result set, returned on a single page. Default: 20')
next
class-attribute
instance-attribute
¶
next = Field(None, description='The relative path to the next set of results.')
offset
class-attribute
instance-attribute
¶
offset = Field(None, description='The number of items that will be skipped in the result set. This is used with the limit field to control the pagination of the output. For example, if the offset is set to 0 and the limit is set to 10 , the method will retrieve items 1 through 10 from the list of items returned.')
prev
class-attribute
instance-attribute
¶
prev = Field(None, description='The relative path to the previous set of results.')
total
class-attribute
instance-attribute
¶
total = Field(None, description='The total number of matches for the search criteria.')
EventItem ¶
Bases: EbayModel
additional_images
class-attribute
instance-attribute
¶
additional_images = Field(None, alias='additionalImages', description='The additional images for the event item.')
category_ancestor_ids
class-attribute
instance-attribute
¶
category_ancestor_ids = Field(None, alias='categoryAncestorIds', description='The IDs of the ancestors for the primary category.')
category_id
class-attribute
instance-attribute
¶
category_id = Field(None, alias='categoryId', description='The ID of the leaf category for the event item. A leaf category is the lowest level in a category and has no children.')
energy_efficiency_class
class-attribute
instance-attribute
¶
energy_efficiency_class = Field(None, alias='energyEfficiencyClass', description='A string value specifying the Energy Efficiency class.')
event_id
class-attribute
instance-attribute
¶
event_id = Field(None, alias='eventId', description='The unique event identifier associated with the item.')
image
class-attribute
instance-attribute
¶
image = Field(None, description='The image for the event item.')
item_affiliate_web_url
class-attribute
instance-attribute
¶
item_affiliate_web_url = Field(None, alias='itemAffiliateWebUrl', description='The item web URL with affiliate attribution.')
item_group_id
class-attribute
instance-attribute
¶
item_group_id = Field(None, alias='itemGroupId', description='The unique identifier for the event item group. This is the parent item ID for the seller-defined variations. Note: This field is returned for multiple-SKU items.')
item_group_type
class-attribute
instance-attribute
¶
item_group_type = Field(None, alias='itemGroupType', description='An enumeration value that indicates the type of item group. An item group contains items that have various aspect differences, such as color, size, or storage capacity.')
item_id
class-attribute
instance-attribute
¶
item_id = Field(None, alias='itemId', description='The unique identifier for the event item. Note: This field is only returned for single-SKU items.')
item_web_url
class-attribute
instance-attribute
¶
item_web_url = Field(None, alias='itemWebUrl', description='The web URL for the event item.')
legacy_item_id
class-attribute
instance-attribute
¶
legacy_item_id = Field(None, alias='legacyItemId', description='The legacy item ID associated with the event item.')
marketing_price
class-attribute
instance-attribute
¶
marketing_price = Field(None, alias='marketingPrice', description='The original price for the event item, and the discount amount and percentage.')
price
class-attribute
instance-attribute
¶
price = Field(None, description='The applicable price for the event item.')
qualified_programs
class-attribute
instance-attribute
¶
qualified_programs = Field(None, alias='qualifiedPrograms', description='A list of programs applicable to the event item.')
shipping_options
class-attribute
instance-attribute
¶
shipping_options = Field(None, alias='shippingOptions', description='The cost required to ship the event item. Note: For items with calculated shipping, this array is only returned if the X-EBAY-C-ENDUSERCTX header is supplied.')
title
class-attribute
instance-attribute
¶
title = Field(None, description='The title of the event item.')
unit_price
class-attribute
instance-attribute
¶
unit_price = Field(None, alias='unitPrice', description='The price per unit for the event item. Some European countries require listings for certain types of products to include the price per unit so that buyers can accurately compare prices. For example: "unitPricingMeasure": "100g", "unitPrice": { "value": "7.99", "currency": "GBP"')
unit_pricing_measure
class-attribute
instance-attribute
¶
unit_pricing_measure = Field(None, alias='unitPricingMeasure', description='The designation used to specify the quantity of the event item, such as size, weight, volume, and count. 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"')
EventItemSearchResponse ¶
Bases: EbayModel
event_items
class-attribute
instance-attribute
¶
event_items = Field(None, alias='eventItems', description='A list of event items that match the search criteria.')
href
class-attribute
instance-attribute
¶
href = Field(None, description='The relative path to the current set of results.')
limit
class-attribute
instance-attribute
¶
limit = Field(None, description='The maximum number of items, from the current result set, returned on a single page. Default: 20')
next
class-attribute
instance-attribute
¶
next = Field(None, description='The relative path to the next set of results.')
offset
class-attribute
instance-attribute
¶
offset = Field(None, description='The number of items that will be skipped in the result set. This is used with the limit field to control the pagination of the output. For example, if the offset is set to 0 and the limit is set to 10 , the method will retrieve items 1 through 10 from the list of items returned.')
prev
class-attribute
instance-attribute
¶
prev = Field(None, description='The relative path to the previous set of results.')
total
class-attribute
instance-attribute
¶
total = Field(None, description='The total number of matches for the specified search criteria.')