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.
Request headers
This method uses the X-EBAY-C-ENDUSERCTX request header to support revenue sharing for eBay Partner Networks and to improve the accuracy of shipping and delivery time estimations. For details see, Request headers in the Buying Integration Guide.Restrictions
This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see API Restrictions.
eBay Partner Network: In order to receive a commission for your sales, you must use the URL returned in theitemAffiliateWebUrl
field to forward your buyer to the ebay.com site. Input
Resource URI (production)
URI parameters
Parameter | Type | Description |
---|---|---|
limit | string | The maximum number of items, from the current result set, returned on a single page. Default: 20 Occurrence: Optional |
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 Occurrence: Optional |
event_ids | string | The unique identifiers for the eBay events. Maximum Value: 1 Occurrence: Required |
category_ids | string | The unique identifier of the eBay category for the search. Maximum Value: 1 Occurrence: Optional |
delivery_country | string | A filter for items that can be shipped to the specified country. Occurrence: Optional |
HTTP request headers
This method has the additional request header requirements listed below. See HTTP request headers- opens rest request components page for details.
Header | Type | Description |
---|---|---|
X-EBAY-C-MARKETPLACE-ID | string | A header used to specify the eBay marketplace ID. Occurrence: Required |
OAuth scope
This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/buy.deal
See OAuth access tokens for more information.
Output
Output container/field | Type | Description |
---|---|---|
eventItems | array of EventItem | A list of event items that match the search criteria. Occurrence: Conditional |
eventItems.additionalImages | array of Image | The additional images for the event item. Occurrence: Conditional |
eventItems.additionalImages.height | string | The height of the image. Occurrence: Conditional |
eventItems.additionalImages.imageUrl | string | The relative path to the image location. Occurrence: Conditional |
eventItems.additionalImages.text | string | The text associated with the image. Occurrence: Conditional |
eventItems.additionalImages.width | string | The width of the image. Occurrence: Conditional |
eventItems.categoryAncestorIds | array of string | The IDs of the ancestors for the primary category. Occurrence: Conditional |
eventItems.categoryId | string | The ID of the leaf category for the event item. A leaf category is the lowest level in a category and has no children. Occurrence: Conditional |
eventItems.energyEfficiencyClass | string | A string value specifying the Energy Efficiency class. Occurrence: Conditional |
eventItems.eventId | string | The unique event identifier associated with the item. Occurrence: Conditional |
eventItems.image | Image | The image for the event item. Occurrence: Conditional |
eventItems.image.height | string | The height of the image. Occurrence: Conditional |
eventItems.image.imageUrl | string | The relative path to the image location. Occurrence: Conditional |
eventItems.image.text | string | The text associated with the image. Occurrence: Conditional |
eventItems.image.width | string | The width of the image. Occurrence: Conditional |
eventItems.itemAffiliateWebUrl | string | The item web URL with affiliate attribution. Occurrence: Conditional |
eventItems.itemGroupId | string | 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. Occurrence: Conditional |
eventItems.itemGroupType | ItemGroupTypeEnum | 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. Occurrence: Conditional |
eventItems.itemId | string | The unique identifier for the event item. Note: This field is only returned for single-SKU items. Occurrence: Conditional |
eventItems.itemWebUrl | string | The web URL for the event item. Occurrence: Conditional |
eventItems.legacyItemId | string | The legacy item ID associated with the event item. Occurrence: Always |
eventItems.marketingPrice | MarketingPrice | The original price for the event item, and the discount amount and percentage. Occurrence: Conditional |
eventItems.marketingPrice.discountAmount | Amount | The monetary value of the seller discount. Occurrence: Conditional |
eventItems.marketingPrice.discountAmount.currency | CurrencyCodeEnum | 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. Occurrence: Conditional |
eventItems.marketingPrice.discountAmount.value | string | The monetary value, in the currency specified by the currency field. Occurrence: Conditional |
eventItems.marketingPrice.discountPercentage | string | The percentage of the seller discount based on the value returned in the originalPrice field. Occurrence: Conditional |
eventItems.marketingPrice.originalPrice | Amount | The monetary value of the item prior to the discount. Occurrence: Conditional |
eventItems.marketingPrice.originalPrice.currency | CurrencyCodeEnum | 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. Occurrence: Conditional |
eventItems.marketingPrice.originalPrice.value | string | The monetary value, in the currency specified by the currency field. Occurrence: Conditional |
eventItems.marketingPrice.priceTreatment | PriceTreatmentEnum | 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. Occurrence: Conditional |
eventItems.price | Amount | The applicable price for the event item. Occurrence: Conditional |
eventItems.price.currency | CurrencyCodeEnum | 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. Occurrence: Conditional |
eventItems.price.value | string | The monetary value, in the currency specified by the currency field. Occurrence: Conditional |
eventItems.qualifiedPrograms | array of ProgramEnum | A list of programs applicable to the event item. Occurrence: Conditional |
eventItems.shippingOptions | array of ShippingOption | The cost required to ship the event item. Occurrence: Conditional |
eventItems.shippingOptions.shippingCost | Amount | 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. For more information on VAT, refer to VAT Obligations in the EU. Occurrence: Always |
eventItems.shippingOptions.shippingCost.currency | CurrencyCodeEnum | 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. Occurrence: Conditional |
eventItems.shippingOptions.shippingCost.value | string | The monetary value, in the currency specified by the currency field. Occurrence: Conditional |
eventItems.shippingOptions.shippingCostType | string | The class of the shipping cost. Valid Values: FIXED or CALCULATED Code so that your app gracefully handles any future changes to this list. Occurrence: Always |
eventItems.title | string | The title of the event item. Occurrence: Conditional |
eventItems.unitPrice | Amount | 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", Occurrence: Conditional |
eventItems.unitPrice.currency | CurrencyCodeEnum | 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. Occurrence: Conditional |
eventItems.unitPrice.value | string | The monetary value, in the currency specified by the currency field. Occurrence: Conditional |
eventItems.unitPricingMeasure | string | 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", Occurrence: Conditional |
href | string | The relative path to the current set of results. Occurrence: Conditional |
limit | integer | The maximum number of items, from the current result set, returned on a single page. Default: 20 Occurrence: Conditional |
next | string | The relative path to the next set of results. Occurrence: Conditional |
offset | integer | 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 Occurrence: Conditional |
prev | string | The relative path to the previous set of results. Occurrence: Conditional |
total | integer | The total number of matches for the specified search criteria. Occurrence: Conditional |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
200 | OK |
400 | Bad Request |
403 | Forbidden |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
180000 | API_DEAL | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
180001 | API_DEAL | REQUEST | Invalid, missing or unsupported marketplace. Please refer to documentation. |
180002 | API_DEAL | REQUEST | The specified limit is invalid. Maximum value supported is 100. |
180003 | API_DEAL | REQUEST | The specified offset is invalid. |
180004 | API_DEAL | REQUEST | The event Id is invalid. |
180004 | API_DEAL | REQUEST | The event Id is invalid. |
180005 | API_DEAL | REQUEST | category_ids length exceeded. Please check documentation for maximum values supported. |
180006 | API_DEAL | REQUEST | event_ids length exceeded. Maximum supported is one. |
180008 | API_DEAL | REQUEST | Missing eventId. Please provide a valid event Id for the marketplace. |
180009 | API_DEAL | REQUEST | Not authorized. Please contact developer support for assistance. |
180010 | API_DEAL | REQUEST | Invalid filter for 'delivery_country'. Please refer to the documentation for supported values. |
Warnings
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.