Skip to main content

The Deal API allows third-party developers to search for and retrieve details about eBay deals and events, as well as the items associated with those deals and events.

Note: This is a (Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.

Technical overview

The Deal API leverages the following resources in order to facilitate event discovery, as well as deal and item retrievals by marketplace:

  • deal_item – The getDealItem method returns a paginated set of deal items. The result set contains all deal items associated with the specified search criteria and marketplace ID.
  • event – The getEvent method retrieves the details for an eBay event, such as applicable coupons, start and end dates, and event terms. The getEvents method returns paginated results containing all eBay events for the specified marketplace.
  • event_item – The getEventItems method returns a paginated set of event items. The result set contains all event items associated with the specified search criteria and marketplace ID.

Note: For information about using RESTful APIs, see Using eBay Restful APIs.

Business use cases

This section outlines the high-level use cases using the Deal API.

Retrieve deal items

You can retrieve a set of items associated with eBay deals using the getDealItem method. The result set contains the deal items available in the specified marketplace.

Note: The marketplace ID is required when using this method. Filtering by category IDs is also supported.

Retrieve events for a marketplace

You can retrieve all eBay events for a specified marketplace using the getEvents method. The result set contains details such as: 

  • Applicable coupons
  • Event description
  • Start and end dates
  • Event terms

Note: The marketplace ID is required when using this method.

Retrieve event items

You can retrieve a set of items associated with eBay events using the getEventItems method. The result set contains the event items available in the specified marketplace.

Note: The marketplace ID is required when using this method. Filtering by category IDs and/or event IDs is also supported.

API restrictions

Please note the following constraints for the Deal API.

Item identifier incompatibility

The Buy APIs identifiers of items do not match the identifiers used on the eBay site. So you cannot use the Buy APIs RESTful item identifiers with any of the eBay legacy APIs, such as Finding. But if you have the legacy item identifier, you can find the RESTful item identifier using the Browse API getItemByLegacyId method.

Regional/site constraints

For a list of the supported eBay sites for all the Buy APIs, see Buy API Support by Marketplace.

To specify the site, set the X-EBAY-C-MARKETPLACE-ID request header to the site. For example:

X-EBAY-C-MARKETPLACE-ID = EBAY_GB

eBay Buy API requirements

Although the eBay Buy APIs are available for anyone to use in eBay's sandbox environment, use of the APIs in production is restricted. Users must meet standard eligibility requirements, get approvals from eBay support organizations, and sign contracts with eBay to access the Buy APIs in production. See Production eligibility requirements for information about production access.

Rate limits

The Deal API limits the number of calls that can be made per day on behalf of your application. For the current application rate limits, see the eBay API Call Limits page.