--- title: Deal API description: "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 [![](https://developer.ebay.com/cms/img/docs/partners-api.svg \"Limited Release\")(Limited Release)](/api-docs/static/versioning.html#limited) 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](/api-docs/buy/static/buy-requirements.html)." api_version: 1.0 api_name: deal_api api_type: REST api_group: buy/deal_api source_url: html: https://developer.ebay.com/develop/api/buy/deal_api md: https://developer.ebay.com/develop/api/buy/deal_api.md --- # Deal API API 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 [![](https://developer.ebay.com/cms/img/docs/partners-api.svg "Limited Release")(Limited Release)](/api-docs/static/versioning.html#limited) 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](/api-docs/buy/static/buy-requirements.html). ## API Methods The following API methods are available: ### getDealItems #### GET /deal_item **Description:** 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](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to receive a commission for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **category_ids** (string) - This query parameter specifies the unique identifier of the eBay category for the search. For details see [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html). - **commissionable** (string) - This query parameter allows the response to filter by commissionable items. If set to `true`, only commissionable items will be returned in the response. If set to `false`, commissionable items will **not** be returned in the response. **Note:** This filter is currently only supported for the US marketplace. - **delivery_country** (string) - This query parameter allows the response to only return items that can be shipped to the specified country (2-digit ISO code). - **limit** (string) - The maximum number of items, from the current result set, returned on a single page. - **offset** (string) - 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. If the **offset** is set to `10` and the **limit** is set to `10`, the method will retrieve items 11 through 20 from the list of items returned. **Default:** `0` - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This header identifies the eBay marketplace. See [HTTP request headers]() for supported marketplace ID values. - **X-EBAY-C-ENDUSERCTX** (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](/api-docs/buy/static/api-browse.html#Headers) section of the Buying Integration Guide. ### getEvent #### GET /event/{event_id} **Description:** 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](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to receive a commission for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This header identifies the eBay marketplace. See [HTTP request headers]() for supported marketplace ID values. - **X-EBAY-C-ENDUSERCTX** (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](/api-docs/buy/static/api-browse.html#Headers) section of the Buying Integration Guide. - **event_id** (string) *required* - This path parameters specifies the unique identifier for the eBay event being retrieved. Use the [getEvents](/api-docs/buy/deal/resources/event/methods/getEvents) method to retrieve event IDs. ### getEvents #### GET /event **Description:** 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](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to receive a commission for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **limit** (string) - The maximum number of items, from the current result set, returned on a single page. **Default:** `20` **Maximum Value:** `100` - **offset** (string) - 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. If the **offset** is set to `10` and the **limit** is set to `10`, the method will retrieve items 11 through 20 from the list of items returned. **Default:** `0` - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This header identifies the eBay marketplace. See [HTTP request headers]() for supported marketplace ID values. - **X-EBAY-C-ENDUSERCTX** (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](/api-docs/buy/static/api-browse.html#Headers) section of the Buying Integration Guide. ### getEventItems #### GET /event_item **Description:** 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](/api-docs/buy/static/buy-requirements.html). **eBay Partner Network:** In order to receive a commission for your sales, you must use the URL returned in the `itemAffiliateWebUrl` field to forward your buyer to the ebay.com site. **Parameters:** - **category_ids** (string) - This query parameter specifies the unique identifiers of the eBay categories for the search. For details see [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html). **Maximum Value:** `1` - **delivery_country** (string) - This query parameter allows the response to only return items that can be shipped to the specified country (2-digit ISO code). - **event_ids** (string) *required* - This query parameter specifies the unique identifiers for the eBay event items being retrieved. Use the [getEvents](/api-docs/buy/deal/resources/event/methods/getEvents) method to retrieve event IDs. **Maximum Value:** `1` - **limit** (string) - The maximum number of items, from the current result set, returned on a single page. **Default:** `20` - **offset** (string) - 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. If the **offset** is set to `10` and the **limit** is set to `10`, the method will retrieve items 11 through 20 from the list of items returned. **Default:** `0` - **X-EBAY-C-MARKETPLACE-ID** (string) *required* - This header identifies the eBay marketplace. See [HTTP request headers]() for supported marketplace ID values. - **X-EBAY-C-ENDUSERCTX** (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](/api-docs/buy/static/api-browse.html#Headers) section of the Buying Integration Guide. ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 180001 - API_DEAL **Description:** Invalid, missing or unsupported marketplace. Please refer to documentation. #### 180002 - API_DEAL **Description:** The specified limit is invalid. Maximum value supported is 100. #### 180003 - API_DEAL **Description:** The specified offset is invalid. #### 180005 - API_DEAL **Description:** category\_ids length exceeded. Please check documentation for maximum values supported. #### 180007 - API_DEAL **Description:** Invalid or unsupported filter 'commissionable' for the requested marketplace. Please refer to documentation. #### 180010 - API_DEAL **Description:** Invalid filter for 'delivery\_country'. Please refer to the documentation for supported values. #### 180009 - API_DEAL **Description:** Not authorized to access requested marketplace. Please contact technical support. #### 180004 - API_DEAL **Description:** The eventId is invalid for the requested marketplace. #### 180006 - API_DEAL **Description:** event\_ids length exceeded. Maximum supported is one. #### 180008 - API_DEAL **Description:** Missing eventId. Please provide a valid event Id for the marketplace. ### APPLICATION Errors #### 180000 - API_DEAL **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-07-08T05:48:52.918Z*