Overview

The Buy Marketing and Discounts APIs allow users to discover deals, sales events, and top-selling products on their eBay marketplace. 

Use Case

Retrieve deal items 

The Deal API allows developers to search for and retrieve details about eBay deals. 

Use getDealItems to retrieve a list of deal items on a specified marketplace. The following query parameters are available to use for this method to refine your deal search: 

  • commissionable: Retrieve deals for commissionable items. Commissionable items are items that ePN partners can promote to earn commission. 
  • delivery_country: Retrieve deals for items that can be shipped to a specific country (specified by its 2-letter country code).

The limit and offset query parameters are also available for pagination. 

A successful call will return a list of items that match the input criteria. Information about a deal item, such as the discount amount or percentage, will be returned for each item. eBay Partner Network affiliates can use the URLs returned through the dealAffiliateWebUrl and itemAffiliateWebUrl fields to drive traffic to the deal or to the specific eBay listing in order to receive commissions.

Retreive events for a marketplace

In addition to searching for deals, the Deal API allows users to search for and retrieve information about eBay sales events and the items associated with those events. An ‘sales event’ is generally a discount on a select group or category of items, and allows sellers to attract more customers. 

The following flow will allow you to retrieve events and event items on a specific marketplace:

Banner image

  1. Use getEvents or getEvent to retrieve one or more eBay events on a specified marketplace. The following information about each event will be returned: 
    • eventId: The unique identifier of the event. 
    • applicableCoupons:  A list of coupons associated with an event, including the coupon code and terms. 
    • startDateand endDate: The start and end date of the event. 
    • terms: The terms and conditions of the event. 
  2. Referencing the retrieved event_id for a specific event, use getEventItems to retrieve information about the items associated with the event. The following query parameters are available to use for this method to refine your event item search: 
    • category_ids: Retrieve event items in a specified category.
    • delivery_country: Retrieve event items that can be shipped to a specific country (specified by its 2-letter ISO 3166 country code). 

The limit and offset query parameters are also available for pagination. 

A successful call will return a list of items in the specified event that match the input criteria. Information about each event item, such as the discount amount or percentage, will be returned for each item. 

Retrieve best-selling items in a category

The Buy Marketing API allows users to retrieve eBay items based on a specific metric, such as Best selling items. This API can empower buyers to search for and compare best-selling items on eBay…

Use getMerchandisedProducts to retrieve a list of Best-Selling products in a specified category. 

The following query parameters are available to use for this method to refine your search: 

  • metric_name (required): Filter the result set by the specified metric. Currently, only BEST_SELLING is supported.
  • category_id (required): Filter the result set by a specific category. 
  • aspect_filter: Filter the result set by aspect name/value pairs. For example, using aspect_filter=Brand:Canon will only return deals on items that are Canon brand. Use the Browse API search method with fieldgroups=APSECT_REFINEMENT  to retrieve product aspects.
  • limit: The maximum number of products to return in the result set.

A successful call will return a list of products that match the input criteria. This includes the product’s epid, title, user reviews, and ratings for the product.

Note: Use the epid returned by this method with the Browse APs search method to retrieve more details about a returned product.

Retrieve items with the highest watch counts

Use getMostWatchedItems method of the Marketing API to retrieve data for items with the highest watch counts in the entire site, or for a specific category (specified by the categoryId parameter). The maxResults parameter can be used to limit the result set. 

A successful call returns details about the most watched items in the specified category. The current price and shipping costs are returned for each item, as well as basic information about the listing, such as its itemId, title, and time left on the listing. Returned items are ranked in descending order by the latest watch count information.

Note: Users can also retrieve most watched items using the getMostwatchedItems method of the legacy Merchandising API. This call, however, has been deprecated and will be decommissioned at a later date. Users are recommended to migrate to the Marketing API to retrieve most watched items. 

Retrieve similar items for a specific item

Use the getSimilarItems method of the Marketing API to retrieve recommendations for similar items to a specific item (specified by its item_Id value). 

The following parameters can be used to filter the result set:

  • buying_option: Limit the result set to only listings of a specific type, such as only fixed priced listings. 
  • filter: Limit the result set by a variety of filters, such as by itemEndDate.

A successful call returns similar items matching the search criteria. The current price and shipping costs are returned for each item, as well as basic information about the listing, such as its itemId, title, and time left on the listing.

Note: Users can also retrieve most watched items using the getSimilarItems method of the legacy Merchandising API. This call, however, has been deprecated and will be decommissioned at a later date. Users are recommended to migrate to the Browse API to retrieve similar items. 

Code Samples

Retrieve deal items on a specific marketplace 

curl -X GET "https://api.ebay.com/buy/deal/v1/deal_item?category_ids=257818"
-H "Authorization: Bearer OAUTH_token"
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

Retrieve events on a specific marketplace 

curl -X GET "https://api.ebay.com/buy/deal/v1/event?limit=1"
-H "Authorization:Bearer OAUTH_token"
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

Error Handling

  • If you receive an invalid metric name error when using getMerchandisedProducts, ensure the metric_name value is BEST_SELLING. This is currently the only supported metric.
  • If you receive an “Invalid filter for delivery_country” error when using the Deal API, ensure the deliver_country query parameter was input as a 2-letter ISO 3166 country code.

Best Practices

  • After using the Deal API to retrieve eBay deals and events, buyers can leverage the Order API to update existing orders or create new orders. For example,  a buyer can use getEvent to retrieve the redemption code for available coupons associated with an event (applicableCoupon.redemptionCode), and can then apply the redemption code to an existing order using the applyCoupon method of the Order API.
  • To test the buy Marketing API in the Sandbox, the category ID 9355 must be used, and the response will be mock data.