Deal API (v1.3.0)

Download OpenAPI specification:Download

Note: This is a (Limited Release) API available only to select developers approved by business units. This 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.

deal_item

getDealItems

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

Authorizations:

Client_Credentials

query Parameters

category_ids	string The unique identifier of the eBay category for the search.
commissionable	string A filter for commissionable deals. Restriction: This filter is currently only supported for the US marketplace.
delivery_country	string A filter for items that can be shipped to the specified country.
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

header Parameters

X-EBAY-C-MARKETPLACE-ID

required

string

A header used to specify the eBay marketplace ID.

Responses

Response samples

Content type

application/json

{"dealItems": [{"additionalImages": [{"height": "string",
"imageUrl": "string",
"text": "string",
"width": "string"
}
],
"categoryAncestorIds": ["string"
],
"categoryId": "string",
"commissionable": true,
"dealAffiliateWebUrl": "string",
"dealEndDate": "string",
"dealStartDate": "string",
"dealWebUrl": "string",
"energyEfficiencyClass": "string",
"image": {"height": "string",
"imageUrl": "string",
"text": "string",
"width": "string"
},
"itemAffiliateWebUrl": "string",
"itemGroupId": "string",
"itemGroupType": "string",
"itemId": "string",
"itemWebUrl": "string",
"legacyItemId": "string",
"marketingPrice": {"discountAmount": {"currency": "string",
"value": "string"
},
"discountPercentage": "string",
"originalPrice": {"currency": "string",
"value": "string"
},
"priceTreatment": "string"
},
"price": {"currency": "string",
"value": "string"
},
"qualifiedPrograms": ["string"
],
"shippingOptions": [{"shippingCost": {"currency": "string",
"value": "string"
},
"shippingCostType": "string"
}
],
"title": "string",
"unitPrice": {"currency": "string",
"value": "string"
},
"unitPricingMeasure": "string"
}
],
"href": "string",
"limit": 0,
"next": "string",
"offset": 0,
"prev": "string",
"total": 0
}

event

getEvent

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

Authorizations:

Client_Credentials

path Parameters

event_id

required

string

The unique identifier for the eBay event.

header Parameters

X-EBAY-C-MARKETPLACE-ID

required

string

A header used to specify the eBay marketplace ID.

Responses

Response samples

Content type

application/json

{"applicableCoupons": [{"redemptionCode": "string",
"terms": {"fullText": "string",
"summary": "string"
}
}
],
"description": "string",
"endDate": "string",
"eventAffiliateWebUrl": "string",
"eventId": "string",
"eventWebUrl": "string",
"images": [{"height": "string",
"imageUrl": "string",
"text": "string",
"width": "string"
}
],
"startDate": "string",
"terms": {"fullText": "string",
"summary": "string"
},
"title": "string"
}

getEvents

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.

Authorizations:

Client_Credentials

query 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

header Parameters

X-EBAY-C-MARKETPLACE-ID

required

string

A header used to specify the eBay marketplace ID.

Responses

Response samples

Content type

application/json

{"events": [{"applicableCoupons": [{"redemptionCode": "string",
"terms": {"fullText": "string",
"summary": "string"
}
}
],
"description": "string",
"endDate": "string",
"eventAffiliateWebUrl": "string",
"eventId": "string",
"eventWebUrl": "string",
"images": [{"height": "string",
"imageUrl": "string",
"text": "string",
"width": "string"
}
],
"startDate": "string",
"terms": {"fullText": "string",
"summary": "string"
},
"title": "string"
}
],
"href": "string",
"limit": 0,
"next": "string",
"offset": 0,
"prev": "string",
"total": 0
}

event_item

getEventItems

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

Authorizations:

Client_Credentials

query Parameters

category_ids	string The unique identifier of the eBay category for the search. Maximum Value: 1
delivery_country	string A filter for items that can be shipped to the specified country.
event_ids required	string The unique identifiers for the eBay events. 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

header Parameters

X-EBAY-C-MARKETPLACE-ID

required

string

A header used to specify the eBay marketplace ID.

Responses

Response samples

Content type

application/json

{"eventItems": [{"additionalImages": [{"height": "string",
"imageUrl": "string",
"text": "string",
"width": "string"
}
],
"categoryAncestorIds": ["string"
],
"categoryId": "string",
"energyEfficiencyClass": "string",
"eventId": "string",
"image": {"height": "string",
"imageUrl": "string",
"text": "string",
"width": "string"
},
"itemAffiliateWebUrl": "string",
"itemGroupId": "string",
"itemGroupType": "string",
"itemId": "string",
"itemWebUrl": "string",
"legacyItemId": "string",
"marketingPrice": {"discountAmount": {"currency": "string",
"value": "string"
},
"discountPercentage": "string",
"originalPrice": {"currency": "string",
"value": "string"
},
"priceTreatment": "string"
},
"price": {"currency": "string",
"value": "string"
},
"qualifiedPrograms": ["string"
],
"shippingOptions": [{"shippingCost": {"currency": "string",
"value": "string"
},
"shippingCostType": "string"
}
],
"title": "string",
"unitPrice": {"currency": "string",
"value": "string"
},
"unitPricingMeasure": "string"
}
],
"href": "string",
"limit": 0,
"next": "string",
"offset": 0,
"prev": "string",
"total": 0
}