deal APIv1.3.0

getEvents

GET
/event

This method returns paginated results containing all eBay events for the specified marketplace.

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 the itemAffiliateWebUrl field to forward your buyer to the ebay.com site.

Input

Resource URI (production)

GET https://api.ebay.com/buy/deal/v1/event?

URI parameters

ParameterTypeDescription
limitstringThe maximum number of items, from the current result set, returned on a single page.

Default: 20

Maximum Value: 100

Occurrence: Optional

offsetstringThe 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

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

HeaderTypeDescription
X-EBAY-C-MARKETPLACE-IDstringA 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

HTTP response headers

{ /* EventSearchResponse */
"events" : [
{ /* Event */
"applicableCoupons" : [
{ /* Coupon */
"terms" :
{ /* Terms */ }
}
],
"images" : [
{ /* Image */
"height" : "string",
"text" : "string",
}
],
"terms" :
{ /* Terms */ },
}
],
"href" : "string",
"limit" : "integer",
"next" : "string",
"prev" : "string",
}
Output container/fieldTypeDescription
eventsarray of EventA list of results that match the search criteria.

Occurrence: Conditional

events.applicableCouponsarray of CouponA list of coupons associated with the event.

Occurrence: Conditional

events.applicableCoupons.redemptionCodestringThe coupon code.

Occurrence: Conditional

events.applicableCoupons.termsTermsThe terms of use associated with the coupon.

Occurrence: Conditional

events.applicableCoupons.terms.fullTextstringA full-text description of the terms.

Occurrence: Conditional

events.applicableCoupons.terms.summarystringA summarized description of the terms.

Occurrence: Conditional

events.descriptionstringThe event description.

Occurrence: Conditional

events.endDatestringThe end date for the event.

Occurrence: Conditional

events.eventAffiliateWebUrlstringThe URL of the View Event page for the event, which includes the affiliate tracking ID.

Occurrence: Conditional

events.eventIdstringThe unique identifier for the event.

Occurrence: Conditional

events.eventWebUrlstringThe web URL for the event.

Occurrence: Conditional

events.imagesarray of ImageThe images for the event.

Occurrence: Conditional

events.images.heightstringThe height of the image.

Occurrence: Conditional

events.images.imageUrlstringThe relative path to the image location.

Occurrence: Conditional

events.images.textstringThe text associated with the image.

Occurrence: Conditional

events.images.widthstringThe width of the image.

Occurrence: Conditional

events.startDatestringThe start date for the event.

Occurrence: Conditional

events.termsTermsThe terms associated with the event.

Occurrence: Conditional

events.terms.fullTextstringA full-text description of the terms.

Occurrence: Conditional

events.terms.summarystringA summarized description of the terms.

Occurrence: Conditional

events.titlestringThe title of the event.

Occurrence: Conditional

hrefstringThe relative path to the current set of results.

Occurrence: Conditional

limitintegerThe maximum number of items, from the current result set, returned on a single page.

Default: 20

Occurrence: Conditional

nextstringThe relative path to the next set of results.

Occurrence: Conditional

offsetintegerThe 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

prevstringThe relative path to the previous set of results.

Occurrence: Conditional

totalintegerThe 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.

StatusMeaning
200OK
400Bad Request
403Forbidden
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
180000API_DEALAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
180001API_DEALREQUESTInvalid, missing or unsupported marketplace. Please refer to documentation.
180002API_DEALREQUESTThe specified limit is invalid. Maximum value supported is 100.
180003API_DEALREQUESTThe specified offset is invalid.
180009API_DEALREQUESTNot authorized. Please contact developer support for assistance.

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.

Sample 1: Retrieve Events for a Specified Marketplace

This sample retrieves a paginated set of events associated with the specified marketplace ID.

Input

The input is the limit URI parameter. There is no payload with this request.
GET
https://api.ebay.com/buy/deal/v1/event?limit=1

Output

If the call is successful, one event matching the specified marketplace will be returned.