{
"openapi": "3.0.0",
"info": {
"title": "Deal API",
"description": "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.
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.",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
"url": "https://go.developer.ebay.com/api-license-agreement"
},
"version": "v1.3.0"
},
"servers": [
{
"url": "https://api.ebay.com{basePath}",
"description": "Production",
"variables": {
"basePath": {
"default": "/buy/deal/v1"
}
}
}
],
"paths": {
"/deal_item": {
"get": {
"tags": [
"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.
itemAffiliateWebUrl
field to forward your buyer to the ebay.com site.",
"operationId": "getDealItems",
"parameters": [
{
"name": "category_ids",
"in": "query",
"description": "This query parameter specifies the unique identifier of the eBay category for the search.true
, only commissionable items will be returned in the response. If set to false
, commissionable items will not be returned in the response.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.0
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "This header identifies the eBay marketplace.itemAffiliateWebUrl
field to forward your buyer to the ebay.com site. ",
"operationId": "getEvent",
"parameters": [
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "This header identifies the eBay marketplace.itemAffiliateWebUrl
field to forward your buyer to the ebay.com site. ",
"operationId": "getEvents",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "The maximum number of items, from the current result set, returned on a single page.20
100
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "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.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.0
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "This header identifies the eBay marketplace.itemAffiliateWebUrl
field to forward your buyer to the ebay.com site. ",
"operationId": "getEventItems",
"parameters": [
{
"name": "category_ids",
"in": "query",
"description": "This query parameter specifies the unique identifiers of the eBay categories for the search.1
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "delivery_country",
"in": "query",
"description": "This query parameter allows the response to only return items that can be shipped to the specified country (2-digit ISO code).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "event_ids",
"in": "query",
"description": "This query parameter specifies the unique identifiers for the eBay event items being retrieved.1
",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "The maximum number of items, from the current result set, returned on a single page.20
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "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.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.0
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "This header identifies the eBay marketplace.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.",
"$ref": "#/components/schemas/Amount"
},
"qualifiedPrograms": {
"type": "array",
"description": "A list of programs applicable to the item.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"shippingOptions": {
"type": "array",
"description": "The cost required to ship the deal item.",
"items": {
"$ref": "#/components/schemas/ShippingOption"
}
},
"title": {
"type": "string",
"description": "The title of the deal item."
},
"unitPrice": {
"description": "The price per unit for the deal item. Some European countries require listings for certain types of products to include the price per unit so that buyers can accurately compare prices. \"unitPricingMeasure\": \"100g\",
\"unitPrice\": {
\"value\": \"7.99\",
\"currency\": \"GBP\"
",
"$ref": "#/components/schemas/Amount"
},
"unitPricingMeasure": {
"type": "string",
"description": "The designation used to specify the quantity of the deal item, such as size, weight, volume, and count. This helps buyers compare prices. \"unitPricingMeasure\": \"100g\",
\"unitPrice\": {
\"value\": \"7.99\",
\"currency\": \"GBP\"
"
}
},
"description": "The detailed data returned for the deal item."
},
"DealItemSearchResponse": {
"type": "object",
"properties": {
"dealItems": {
"type": "array",
"description": "A list of deal items that match the search criteria.",
"items": {
"$ref": "#/components/schemas/DealItem"
}
},
"href": {
"type": "string",
"description": "The relative path to the current set of results."
},
"limit": {
"type": "integer",
"description": "The maximum number of items, from the current result set, returned on a single page.20
",
"format": "int32"
},
"next": {
"type": "string",
"description": "The relative path to the next set of results."
},
"offset": {
"type": "integer",
"description": "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.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.0
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The relative path to the previous set of results."
},
"total": {
"type": "integer",
"description": "The total number of matches for the search criteria.",
"format": "int32"
}
},
"description": "The result set for the deal item search."
},
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Identifies the type of erro."
},
"domain": {
"type": "string",
"description": "Name for the primary system where the error occurred. This is relevant for application errors."
},
"errorId": {
"type": "integer",
"description": "A unique number to identify the error.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error."
},
"message": {
"type": "string",
"description": "Information on how to correct the problem, in the end user's terms and language where applicable."
},
"outputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
}
},
"description": "This type defines the fields that can be returned in an error."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The object of the error."
},
"value": {
"type": "string",
"description": "The value of the object."
}
}
},
"Event": {
"type": "object",
"properties": {
"applicableCoupons": {
"type": "array",
"description": "A list of coupons associated with the event.",
"items": {
"$ref": "#/components/schemas/Coupon"
}
},
"description": {
"type": "string",
"description": "The event description."
},
"endDate": {
"type": "string",
"description": "The end date for the event."
},
"eventAffiliateWebUrl": {
"type": "string",
"description": "The URL of the View Event page for the event, which includes the affiliate tracking ID."
},
"eventId": {
"type": "string",
"description": "The unique identifier for the event."
},
"eventWebUrl": {
"type": "string",
"description": "The web URL for the event."
},
"images": {
"type": "array",
"description": "The images for the event.",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"startDate": {
"type": "string",
"description": "The start date for the event."
},
"terms": {
"description": "The terms associated with the event.",
"$ref": "#/components/schemas/Terms"
},
"title": {
"type": "string",
"description": "The title of the event."
}
},
"description": "The result set for the event search."
},
"EventItem": {
"type": "object",
"properties": {
"additionalImages": {
"type": "array",
"description": "The additional images for the event item.",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"categoryAncestorIds": {
"type": "array",
"description": "The IDs of the ancestors for the primary category.",
"items": {
"type": "string"
}
},
"categoryId": {
"type": "string",
"description": "The ID of the leaf category for the event item. A leaf category is the lowest level in a category and has no children."
},
"energyEfficiencyClass": {
"type": "string",
"description": "A string value specifying the Energy Efficiency class."
},
"eventId": {
"type": "string",
"description": "The unique event identifier associated with the item."
},
"image": {
"description": "The image for the event item.",
"$ref": "#/components/schemas/Image"
},
"itemAffiliateWebUrl": {
"type": "string",
"description": "The item web URL with affiliate attribution."
},
"itemGroupId": {
"type": "string",
"description": "The unique identifier for the event item group. This is the parent item ID for the seller-defined variations.\"unitPricingMeasure\": \"100g\",
\"unitPrice\": {
\"value\": \"7.99\",
\"currency\": \"GBP\"
",
"$ref": "#/components/schemas/Amount"
},
"unitPricingMeasure": {
"type": "string",
"description": "The designation used to specify the quantity of the event item, such as size, weight, volume, and count. This helps buyers compare prices. \"unitPricingMeasure\": \"100g\",
\"unitPrice\": {
\"value\": \"7.99\",
\"currency\": \"GBP\"
"
}
},
"description": "The detailed data returned for the event item."
},
"EventItemSearchResponse": {
"type": "object",
"properties": {
"eventItems": {
"type": "array",
"description": "A list of event items that match the search criteria.",
"items": {
"$ref": "#/components/schemas/EventItem"
}
},
"href": {
"type": "string",
"description": "The relative path to the current set of results."
},
"limit": {
"type": "integer",
"description": "The maximum number of items, from the current result set, returned on a single page.20
",
"format": "int32"
},
"next": {
"type": "string",
"description": "The relative path to the next set of results."
},
"offset": {
"type": "integer",
"description": "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.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.0
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The relative path to the previous set of results."
},
"total": {
"type": "integer",
"description": "The total number of matches for the specified search criteria.",
"format": "int32"
}
},
"description": "The result set for the event item search."
},
"EventSearchResponse": {
"type": "object",
"properties": {
"events": {
"type": "array",
"description": "A list of results that match the search criteria.",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"href": {
"type": "string",
"description": "The relative path to the current set of results."
},
"limit": {
"type": "integer",
"description": "The maximum number of items, from the current result set, returned on a single page.20
",
"format": "int32"
},
"next": {
"type": "string",
"description": "The relative path to the next set of results."
},
"offset": {
"type": "integer",
"description": "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.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.0
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The relative path to the previous set of results."
},
"total": {
"type": "integer",
"description": "The total number of matches for the specified search criteria.",
"format": "int32"
}
},
"description": "The result set for the specified event search criteria."
},
"Image": {
"type": "object",
"properties": {
"height": {
"type": "string",
"description": "The height of the image."
},
"imageUrl": {
"type": "string",
"description": "The relative path to the image location."
},
"text": {
"type": "string",
"description": "The text associated with the image."
},
"width": {
"type": "string",
"description": "The width of the image."
}
},
"description": "The type that defines the details of an image, such as size and URL."
},
"MarketingPrice": {
"type": "object",
"properties": {
"discountAmount": {
"description": "The monetary value of the seller discount.",
"$ref": "#/components/schemas/Amount"
},
"discountPercentage": {
"type": "string",
"description": "The percentage of the seller discount based on the value returned in the originalPrice field."
},
"originalPrice": {
"description": "The monetary value of the item prior to the discount.",
"$ref": "#/components/schemas/Amount"
},
"priceTreatment": {
"type": "string",
"description": "The pricing treatment (discount) that was applied to the price of the item. 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.",
"$ref": "#/components/schemas/Amount"
},
"shippingCostType": {
"type": "string",
"description": "The class of the shipping cost. FIXED
or CALCULATED