{ "openapi": "3.1.0", "info": { "title": "Deal API", "description": "Note: This is a \"Limited(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://developer.ebay.com/join/api-license-agreement" }, "version": "v1.0.0" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production server url.", "variables": { "basePath": { "default": "/buy/deal/v1" } } } ], "security": [ {} ], "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.

This method can return a maximum of 10,000 items. For a list of supported sites and other restrictions, see Buy API Requirements.

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.", "operationId": "getDealItems", "parameters": [ { "name": "category_ids", "in": "query", "description": "This query parameter specifies the unique identifier of the eBay category for the search.

For details see Get Categories for Buy APIs.", "required": false, "schema": { "type": "string", "description": "The category ids." }, "style": "form", "explode": true }, { "name": "commissionable", "in": "query", "description": "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.", "required": false, "schema": { "type": "string", "description": "The commissionable." }, "style": "form", "explode": true }, { "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", "description": "The delivery country." }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "description": "The maximum number of items, from the current result set, returned on a single page.", "required": false, "schema": { "type": "string", "description": "The limit." }, "style": "form", "explode": true }, { "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.

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", "required": false, "schema": { "type": "string", "description": "The offset." }, "style": "form", "explode": true }, { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This header identifies the eBay marketplace.

See HTTP request headers for supported marketplace ID values.", "required": true, "schema": { "type": "string", "description": "The header." }, "style": "simple", "explode": false }, { "name": "X-EBAY-C-ENDUSERCTX", "in": "header", "description": "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 section of the Buying Integration Guide.", "required": false, "schema": { "type": "string", "description": "The header." }, "style": "simple", "explode": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealItemSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180001": { "domain": "API_DEAL", "category": "REQUEST", "description": "Invalid, missing or unsupported marketplace. Please refer to documentation." }, "180002": { "domain": "API_DEAL", "category": "REQUEST", "description": "The specified limit is invalid. Maximum value supported is 100." }, "180003": { "domain": "API_DEAL", "category": "REQUEST", "description": "The specified offset is invalid." }, "180005": { "domain": "API_DEAL", "category": "REQUEST", "description": "category_ids length exceeded. Please check documentation for maximum values supported." }, "180007": { "domain": "API_DEAL", "category": "REQUEST", "description": "Invalid or unsupported filter 'commissionable' for the requested marketplace. Please refer to documentation." }, "180010": { "domain": "API_DEAL", "category": "REQUEST", "description": "Invalid filter for 'delivery_country'. Please refer to the documentation for supported values." } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180009": { "domain": "API_DEAL", "category": "REQUEST", "description": "Not authorized to access requested marketplace. Please contact technical support." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180000": { "domain": "API_DEAL", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/buy.deal" ] } ], "summary": "This is for getting deal item." }, "summary": "This is for getting deal item." }, "/event/{event_id}": { "get": { "tags": [ "event" ], "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.

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. ", "operationId": "getEvent", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This header identifies the eBay marketplace.

See HTTP request headers for supported marketplace ID values.", "required": true, "schema": { "type": "string", "description": "The header." }, "style": "simple", "explode": false }, { "name": "X-EBAY-C-ENDUSERCTX", "in": "header", "description": "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 section of the Buying Integration Guide.", "required": false, "schema": { "type": "string", "description": "The header." }, "style": "simple", "explode": false }, { "name": "event_id", "in": "path", "description": "This path parameters specifies the unique identifier for the eBay event being retrieved.

Use the getEvents method to retrieve event IDs.", "required": true, "schema": { "type": "string", "description": "The event id." }, "style": "simple", "explode": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180009": { "domain": "API_DEAL", "category": "REQUEST", "description": "Not authorized to access requested marketplace. Please contact technical support." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180004": { "domain": "API_DEAL", "category": "REQUEST", "description": "The eventId is invalid for the requested marketplace." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180000": { "domain": "API_DEAL", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/buy.deal" ] } ], "summary": "Get details for ebay Event by event id." }, "summary": "Get details for ebay Event by event id." }, "/event": { "get": { "tags": [ "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.

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. ", "operationId": "getEvents", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of items, from the current result set, returned on a single page.

Default: 20

Maximum Value: 100", "required": false, "schema": { "type": "string", "description": "The limit" }, "style": "form", "explode": true }, { "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.

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", "required": false, "schema": { "type": "string", "description": "The query" }, "style": "form", "explode": true }, { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This header identifies the eBay marketplace.

See HTTP request headers for supported marketplace ID values.", "required": true, "schema": { "type": "string", "description": "The header" }, "style": "simple", "explode": false }, { "name": "X-EBAY-C-ENDUSERCTX", "in": "header", "description": "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 section of the Buying Integration Guide.", "required": false, "schema": { "type": "string", "description": "The header" }, "style": "simple", "explode": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180001": { "domain": "API_DEAL", "category": "REQUEST", "description": "Invalid, missing or unsupported marketplace. Please refer to documentation." }, "180002": { "domain": "API_DEAL", "category": "REQUEST", "description": "The specified limit is invalid. Maximum value supported is 100." }, "180003": { "domain": "API_DEAL", "category": "REQUEST", "description": "The specified offset is invalid." } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180009": { "domain": "API_DEAL", "category": "REQUEST", "description": "Not authorized to access requested marketplace. Please contact technical support." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180000": { "domain": "API_DEAL", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/buy.deal" ] } ], "summary": "This method returns paginated results containing all eBay events" }, "summary": "This method returns paginated results containing all eBay events" }, "/event_item": { "get": { "tags": [ "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.

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. ", "operationId": "getEventItems", "parameters": [ { "name": "category_ids", "in": "query", "description": "This query parameter specifies the unique identifiers of the eBay categories for the search.

For details see Get Categories for Buy APIs.

Maximum Value: 1", "required": false, "schema": { "type": "string", "description": "The catetory id." }, "style": "form", "explode": true }, { "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", "description": "The delivery country." }, "style": "form", "explode": true }, { "name": "event_ids", "in": "query", "description": "This query parameter specifies the unique identifiers for the eBay event items being retrieved.

Use the getEvents method to retrieve event IDs.

Maximum Value: 1", "required": true, "schema": { "type": "string", "description": "The event id." }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "description": "The maximum number of items, from the current result set, returned on a single page.

Default: 20", "required": false, "schema": { "type": "string", "description": "The limit." }, "style": "form", "explode": true }, { "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.

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", "required": false, "schema": { "type": "string", "description": "The offset." }, "style": "form", "explode": true }, { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "This header identifies the eBay marketplace.

See HTTP request headers for supported marketplace ID values.", "required": true, "schema": { "type": "string", "description": "The header." }, "style": "simple", "explode": false }, { "name": "X-EBAY-C-ENDUSERCTX", "in": "header", "description": "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 section of the Buying Integration Guide.", "required": false, "schema": { "type": "string", "description": "The header." }, "style": "simple", "explode": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180001": { "domain": "API_DEAL", "category": "REQUEST", "description": "Invalid, missing or unsupported marketplace. Please refer to documentation." }, "180002": { "domain": "API_DEAL", "category": "REQUEST", "description": "The specified limit is invalid. Maximum value supported is 100." }, "180003": { "domain": "API_DEAL", "category": "REQUEST", "description": "The specified offset is invalid." }, "180004": { "domain": "API_DEAL", "category": "REQUEST", "description": "The event Id is invalid." }, "180005": { "domain": "API_DEAL", "category": "REQUEST", "description": "category_ids length exceeded. Please check documentation for maximum values supported." }, "180006": { "domain": "API_DEAL", "category": "REQUEST", "description": "event_ids length exceeded. Maximum supported is one." }, "180008": { "domain": "API_DEAL", "category": "REQUEST", "description": "Missing eventId. Please provide a valid event Id for the marketplace." }, "180010": { "domain": "API_DEAL", "category": "REQUEST", "description": "Invalid filter for 'delivery_country'. Please refer to the documentation for supported values." } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180009": { "domain": "API_DEAL", "category": "REQUEST", "description": "Not authorized to access requested marketplace. Please contact technical support." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "180000": { "domain": "API_DEAL", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/buy.deal" ] } ], "summary": "This method returns a paginated set of event items." }, "summary": "This method returns a paginated set of event items." } }, "components": { "schemas": { "Amount": { "type": "object", "properties": { "currency": { "description": "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.", "$ref": "#/components/schemas/CurrencyCodeEnum" }, "value": { "type": "string", "description": "The monetary value, in the currency specified by the currency field." } }, "description": "This type defines the currency and value of the item." }, "Coupon": { "type": "object", "properties": { "redemptionCode": { "type": "string", "description": "The coupon code.", "examples": [ "ESDJ-SDA" ] }, "terms": { "description": "The terms of use associated with the coupon.", "$ref": "#/components/schemas/Terms" } }, "description": "This type defines the details for the coupon available for the item." }, "CurrencyCodeEnum": { "type": "string", "description": "This enumerated type lists the three-letter ISO 4217 code representing the supported world currencies. | - **AED**: United Arab Emirates dirham - **AFN**: Afghan afghani - **ALL**: Albanian lek - **AMD**: Armenian dram - **ANG**: Netherlands Antillean guilder - **AOA**: Angolan kwanza - **ARS**: Argentine peso - **AUD**: Australian dollar - **AWG**: Aruban florin - **AZN**: Azerbaijani manat - **BAM**: Bosnia and Herzegovina convertible mark - **BBD**: Barbados dollar - **BDT**: Bangladeshi taka - **BGN**: Bulgarian lev - **BHD**: Bahraini dinar - **BIF**: Burundian franc - **BMD**: Bermudian dollar - **BND**: Brunei dollar - **BOB**: Bolivian Boliviano - **BRL**: Brazilian real - **BSD**: Bahamian dollar - **BTN**: Bhutanese ngultrum - **BWP**: Botswana pula - **BYR**: Belarusian ruble - **BZD**: Belize dollar - **CAD**: Canadian dollar - **CDF**: Congolese franc - **CHF**: Swiss franc - **CLP**: Chilean peso - **CNY**: Chinese yuan renminbi - **COP**: Colombian peso - **CRC**: Costa Rican colon - **CUP**: Cuban peso - **CVE**: Cape Verde escudo - **CZK**: Czech koruna - **DJF**: Djiboutian franc - **DKK**: Danish krone - **DOP**: Dominican peso - **DZD**: Algerian dinar - **EGP**: Egyptian pound - **ERN**: Eritrean nakfa - **ETB**: Ethiopian birr - **EUR**: European Union euro - **FJD**: Fiji dollar - **FKP**: Falkland Islands pound - **GBP**: British pound sterling - **GEL**: Georgian lari - **GHS**: Ghanaian cedi - **GIP**: Gibraltar pound - **GMD**: Gambian dalasi - **GNF**: Guinean franc - **GTQ**: Guatemalan quetzal - **GYD**: Guyanese dollar - **HKD**: Hong Kong dollar - **HNL**: Honduran lempira - **HRK**: Croatian kuna - **HTG**: Haitian gourde - **HUF**: Hungarian forint - **IDR**: Indonesian rupiah - **ILS**: Israeli new shekel - **INR**: Indian rupee - **IQD**: Iraqi dinar - **IRR**: Iranian rial - **ISK**: Icelandic krona - **JMD**: Jamaican dollar - **JOD**: Jordanian dinar - **JPY**: Japanese yen - **KES**: Kenyan shilling - **KGS**: Kyrgyzstani som - **KHR**: Cambodian riel - **KMF**: Comoro franc - **KPW**: North Korean won - **KRW**: South Korean won - **KWD**: Kuwaiti dinar - **KYD**: Cayman Islands dollar - **KZT**: Kazakhstani tenge - **LAK**: Lao kip - **LBP**: Lebanese pound - **LKR**: Sri Lankan rupee - **LRD**: Liberian dollar - **LSL**: Lesotho loti - **LTL**: Lithuanian litas - **LYD**: Libyan dinar - **MAD**: Moroccan dirham - **MDL**: Moldovan leu - **MGA**: Malagasy ariary - **MKD**: Macedonian denar - **MMK**: Myanmar kyat - **MNT**: Mongolian tugrik - **MOP**: Macanese pataca - **MRO**: Mauritanian ouguiya - **MUR**: Mauritian rupee - **MVR**: Maldivian rufiyaa - **MWK**: Malawian kwacha - **MXN**: Mexican peso - **MYR**: Malaysian ringgit - **MZN**: Mozambican metical - **NAD**: Namibian dollar - **NGN**: Nigerian naira - **NIO**: Nicaraguan cordoba oro - **NOK**: Norwegian krone - **NPR**: Nepalese rupee - **NZD**: New Zealand dollar - **OMR**: Omani rial - **PAB**: Panamanian balboa - **PEN**: Peruvian sol - **PGK**: Papua New Guinean kina - **PHP**: Philippine peso - **PKR**: Pakistani rupee - **PLN**: Polish zloty - **PYG**: Paraguayan guarani - **QAR**: Qatari riyal - **RON**: Romanian leu - **RSD**: Serbian dinar - **RUB**: Russian ruble - **RWF**: Rwandan franc - **SAR**: Saudi riyal - **SBD**: Solomon Islands dollar - **SCR**: Seychelles rupee - **SDG**: Sudanese pound - **SEK**: Swedish krona - **SGD**: Singapore dollar - **SHP**: Saint Helena pound - **SLL**: Sierra Leonean leone - **SOS**: Somali shilling - **SRD**: Surinamese dollar - **STD**: Sao Tome and Principe dobra - **SYP**: Syrian pound - **SZL**: Swazi lilangeni - **THB**: Thai baht - **TJS**: Tajikistani somoni - **TMT**: Turkmenistani manat - **TND**: Tunisian dinar - **TOP**: Tongan pa'anga - **TRY**: Turkish lira - **TTD**: Trinidad and Tobago dollar - **TWD**: New Taiwan dollar - **TZS**: Tanzanian shilling - **UAH**: Ukrainian hryvnia - **UGX**: Ugandan shilling - **USD**: United States dollar - **UYU**: Uruguayan peso - **UZS**: Uzbekistani som - **VEF**: Venezuelan bolivar - **VND**: Vietnamese dong - **VUV**: Vanuatu vatu - **WST**: Samoan tala - **XAF**: CFA franc BEAC - **XCD**: East Caribbean dollar - **XOF**: CFA franc BCEAO - **XPF**: CFP franc - **YER**: Yemeni rial - **ZAR**: South African rand - **ZMW**: Zambian kwacha - **ZWL**: Zimbabwean dollar", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STD", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL" ] }, "DealItem": { "type": "object", "properties": { "additionalImages": { "type": "array", "description": "The additional images for the deal item.", "items": { "$ref": "#/components/schemas/Image" }, "examples": [ [ { "height": "10", "imageUrl": "testUrl", "text": "text", "width": "10" } ] ] }, "categoryAncestorIds": { "type": "array", "description": "The IDs of the ancestors for the primary category.", "items": { "type": "string", "description": "id" }, "examples": [ [ "1" ] ] }, "categoryId": { "type": "string", "description": "The ID of the leaf category for the deal item. A leaf category is the lowest level in a category and has no children.", "examples": [ "1" ] }, "commissionable": { "type": "boolean", "description": "A boolean value specifying whether the listing has commission.", "examples": [ true ] }, "dealAffiliateWebUrl": { "type": "string", "description": "The deal associated with the item with affiliate attribution.", "examples": [ "testUrl" ] }, "dealEndDate": { "type": "string", "description": "The date after which the deal ends.", "examples": [ "2026-01-01" ] }, "dealStartDate": { "type": "string", "description": "The date on which the deal starts.", "examples": [ "2026-01-01" ] }, "dealWebUrl": { "type": "string", "description": "The web URL for the deal associated with the item.", "examples": [ "testUrl" ] }, "energyEfficiencyClass": { "type": "string", "description": "A string value specifying the Energy Efficiency class.", "examples": [ "testClass" ] }, "image": { "description": "The primary image for the deal item.", "$ref": "#/components/schemas/Image" }, "itemAffiliateWebUrl": { "type": "string", "description": "The item web URL with affiliate attribution.", "examples": [ "testUrl" ] }, "itemGroupId": { "type": "string", "description": "The unique identifier for the deal item group. This is the parent item ID for the seller-defined variations.

Note: This field is returned for multiple-SKU items.", "examples": [ "id" ] }, "itemGroupType": { "description": "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.", "$ref": "#/components/schemas/ItemGroupTypeEnum" }, "itemId": { "type": "string", "description": "The unique identifier for the deal item.

Note: This field is only returned for single-SKU items.", "examples": [ "id" ] }, "itemWebUrl": { "type": "string", "description": "The web URL for the deal item.", "examples": [ "testUrl" ] }, "legacyItemId": { "type": "string", "description": "The legacy item ID associated with the deal item.", "examples": [ "id" ] }, "marketingPrice": { "description": "The original price for the deal item, and the discount amount and percentage.", "$ref": "#/components/schemas/MarketingPrice" }, "price": { "description": "The price for the deal item.

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.", "$ref": "#/components/schemas/Amount" }, "qualifiedPrograms": { "type": "array", "description": "A list of programs applicable to the item.", "items": { "$ref": "#/components/schemas/ProgramEnum" }, "examples": [ [ "EBAY_PLUS" ] ] }, "shippingOptions": { "type": "array", "description": "The cost required to ship the deal item.

Note: For items with calculated shipping, this array is only returned if the X-EBAY-C-ENDUSERCTX header is supplied.", "items": { "$ref": "#/components/schemas/ShippingOption" }, "examples": [ [ { "shippingCost": { "value": "1", "currency": "AED" }, "shippingCostType": "FIXED" } ] ] }, "title": { "type": "string", "description": "The title of the deal item.", "examples": [ "title" ] }, "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.

For example:

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

For example, the following tells the buyer that the item is 7.99 per 100 grams.

\"unitPricingMeasure\": \"100g\",
\"unitPrice\": {
  \"value\": \"7.99\",
  \"currency\": \"GBP\"", "examples": [ "GBP" ] } }, "description": "This type defines 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" }, "examples": [ [ { "additionalImages": [ { "height": "10", "imageUrl": "testUrl", "text": "text", "width": "10" } ], "categoryAncestorIds": [ "id1" ], "categoryId": "id", "commissionable": true, "dealAffiliateWebUrl": "testUrl", "dealEndDate": "2026-01-01" } ] ] }, "href": { "type": "string", "description": "The relative path to the current set of results.", "examples": [ "testHref" ] }, "limit": { "type": "integer", "description": "The maximum number of items, from the current result set, returned on a single page.

Default: 20", "format": "int32", "examples": [ 20 ] }, "next": { "type": "string", "description": "The relative path to the next set of results.", "examples": [ "next" ] }, "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.

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", "format": "int32", "examples": [ 20 ] }, "prev": { "type": "string", "description": "The relative path to the previous set of results.", "examples": [ "prev" ] }, "total": { "type": "integer", "description": "The total number of matches for the search criteria.", "format": "int32", "examples": [ 40 ] } }, "description": "This type defines the result set for the deal item search." }, "Error": { "type": "object", "properties": { "category": { "type": "string", "description": "Identifies the type of error." }, "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", "description": "This type defines the parameters for an error.", "properties": { "name": { "type": "string", "description": "The object of the error.", "examples": [ "categoryId" ] }, "value": { "type": "string", "description": "The value of the object.", "examples": [ "1234" ] } } }, "Event": { "type": "object", "properties": { "applicableCoupons": { "type": "array", "description": "A list of coupons associated with the event.", "items": { "$ref": "#/components/schemas/Coupon" }, "examples": [ [ { "redemptionCode": "ESDJ-SDA", "terms": { "fullText": "fullText", "summary": "summary of the term" } } ] ] }, "description": { "type": "string", "description": "The event description.", "examples": [ "description" ] }, "endDate": { "type": "string", "description": "The end date for the event.", "examples": [ "20260101" ] }, "eventAffiliateWebUrl": { "type": "string", "description": "The URL of the View Event page for the event, which includes the affiliate tracking ID.", "examples": [ "testUrl" ] }, "eventId": { "type": "string", "description": "The unique identifier for the event.", "examples": [ "1" ] }, "eventWebUrl": { "type": "string", "description": "The web URL for the event.", "examples": [ "www.test.com" ] }, "images": { "type": "array", "description": "The images for the event.", "items": { "$ref": "#/components/schemas/Image" }, "examples": [ [ { "height": "10", "imageUrl": "testUrl", "text": "text", "width": "10" } ] ] }, "startDate": { "type": "string", "description": "The start date for the event.", "examples": [ "2026-01-02" ] }, "terms": { "description": "The terms associated with the event.", "$ref": "#/components/schemas/Terms" }, "title": { "type": "string", "description": "The title of the event.", "examples": [ "event title" ] } }, "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" }, "examples": [ [ { "height": "10", "imageUrl": "testUrl", "text": "text", "width": "10" } ] ] }, "categoryAncestorIds": { "type": "array", "description": "The IDs of the ancestors for the primary category.", "items": { "type": "string", "description": "id" } }, "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.", "examples": [ "id" ] }, "energyEfficiencyClass": { "type": "string", "description": "A string value specifying the Energy Efficiency class.", "examples": [ "testClass" ] }, "eventId": { "type": "string", "description": "The unique event identifier associated with the item.", "examples": [ "id" ] }, "image": { "description": "The image for the event item.", "$ref": "#/components/schemas/Image" }, "itemAffiliateWebUrl": { "type": "string", "description": "The item web URL with affiliate attribution.", "examples": [ "test Url" ] }, "itemGroupId": { "type": "string", "description": "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.", "examples": [ "id" ] }, "itemGroupType": { "description": "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.", "$ref": "#/components/schemas/ItemGroupTypeEnum" }, "itemId": { "type": "string", "description": "The unique identifier for the event item.

Note: This field is only returned for single-SKU items.", "examples": [ "id" ] }, "itemWebUrl": { "type": "string", "description": "The web URL for the event item.", "examples": [ "testUrl" ] }, "legacyItemId": { "type": "string", "description": "The legacy item ID associated with the event item.", "examples": [ "itemId" ] }, "marketingPrice": { "description": "The original price for the event item, and the discount amount and percentage.", "$ref": "#/components/schemas/MarketingPrice" }, "price": { "description": "The applicable price for the event item.", "$ref": "#/components/schemas/Amount" }, "qualifiedPrograms": { "type": "array", "description": "A list of programs applicable to the event item.", "items": { "$ref": "#/components/schemas/ProgramEnum" } }, "shippingOptions": { "type": "array", "description": "The cost required to ship the event item.

Note: For items with calculated shipping, this array is only returned if the X-EBAY-C-ENDUSERCTX header is supplied.", "items": { "$ref": "#/components/schemas/ShippingOption" } }, "title": { "type": "string", "description": "The title of the event item.", "examples": [ "test Title" ] }, "unitPrice": { "description": "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\",
\"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.

For example, the following tells the buyer that the item is 7.99 per 100 grams.

\"unitPricingMeasure\": \"100g\",
\"unitPrice\": {
  \"value\": \"7.99\",
  \"currency\": \"GBP\"", "examples": [ "1" ] } }, "description": "This type defines 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" }, "examples": [ [ { "additionalImages": [ { "height": "10", "imageUrl": "testUrl", "text": "text", "width": "10" } ] } ] ] }, "href": { "type": "string", "description": "The relative path to the current set of results.", "examples": [ "test.com" ] }, "limit": { "type": "integer", "description": "The maximum number of items, from the current result set, returned on a single page.

Default: 20", "format": "int32", "examples": [ 10 ] }, "next": { "type": "string", "description": "The relative path to the next set of results.", "examples": [ "next" ] }, "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.

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", "format": "int32", "examples": [ 10 ] }, "prev": { "type": "string", "description": "The relative path to the previous set of results.", "examples": [ "test" ] }, "total": { "type": "integer", "description": "The total number of matches for the specified search criteria.", "format": "int32", "examples": [ 10 ] } }, "description": "This type defines 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.", "examples": [ "testhref" ] }, "limit": { "type": "integer", "description": "The maximum number of items, from the current result set, returned on a single page.

Default: 20", "format": "int32", "examples": [ 10 ] }, "next": { "type": "string", "description": "The relative path to the next set of results.", "examples": [ "20" ] }, "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.

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", "format": "int32", "examples": [ 10 ] }, "prev": { "type": "string", "description": "The relative path to the previous set of results.", "examples": [ "0" ] }, "total": { "type": "integer", "description": "The total number of matches for the specified search criteria.", "format": "int32", "examples": [ 100 ] } }, "description": "This type defines 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." }, "ItemGroupTypeEnum": { "type": "string", "description": "An enumerated type for the values that represent the type of the item group. An item group contains items that have various aspect differences, such as color, size, or storage capacity.

Code so that your app gracefully handles any future changes to this list. | - **SELLER_DEFINED_VARIATIONS**: This enum value indicates that this group was created by the seller. Currently, this is the only value supported.", "enum": [ "SELLER_DEFINED_VARIATIONS" ], "examples": [ "SELLER_DEFINED_VARIATIONS" ] }, "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.", "examples": [ "10" ] }, "originalPrice": { "description": "The monetary value of the item prior to the discount.", "$ref": "#/components/schemas/Amount" }, "priceTreatment": { "description": "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.", "$ref": "#/components/schemas/PriceTreatmentEnum" } }, "description": "A type that describes the seller discount." }, "PriceTreatmentEnum": { "type": "string", "description": "An enumerated type for the values that represent a discount type. | - **MINIMUM_ADVERTISED_PRICE**: This enumeration value indicates that the price treatment is Minimum Advertised Price (MAP). This is the lowest price at which the item is allowed to be advertised/shown and can be shown only after the item has been added to the cart. - **LIST_PRICE**: This enumeration value indicates that the price treatment is Strike Through Pricing (STP). For this treatment, the seller listing price (which is crossed off/struck through) and the discounted price are shown. - **MARKDOWN**: This enumeration value indicates that the price treatment is a markdown. The price before the markdown (Was price) is shown, as well as the discounted price. This item is part of a seller promotion and has an end date.", "enum": [ "MINIMUM_ADVERTISED_PRICE", "LIST_PRICE", "MARKDOWN" ], "examples": [ "LIST_PRICE" ] }, "ProgramEnum": { "type": "string", "description": "An enumerated type for the values that represent a program type. | - **EBAY_PLUS**: This enumeration value indicates that the item is eligible for eBay Plus benefits.", "enum": [ "EBAY_PLUS" ] }, "ShippingOption": { "type": "object", "required": [ "shippingCost", "shippingCostType" ], "properties": { "shippingCost": { "description": "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.", "$ref": "#/components/schemas/Amount" }, "shippingCostType": { "type": "string", "description": "The class of the shipping cost.

Valid Values: FIXED or CALCULATED

Code so that your app gracefully handles any future changes to this list. ", "examples": [ "FIXED" ] } }, "description": "This type defines the details provided for the shipping provider, such as shipping cost and type." }, "Terms": { "type": "object", "properties": { "fullText": { "type": "string", "description": "A full-text description of the terms.", "examples": [ "Full text of terms" ] }, "summary": { "type": "string", "description": "A summarized description of the terms.", "examples": [ "Summary of terms" ] } }, "description": "This type defines the terms for the event, provided in a full-text description and summary." } }, "securitySchemes": { "api_auth": { "type": "oauth2", "description": "The security definitions for this API. Please check individual operations for applicable scopes.", "flows": { "clientCredentials": { "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token", "scopes": { "https://api.ebay.com/oauth/api_scope/buy.deal": "View eBay sale events and deals." } } } }, "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "deal_item", "description": "detail item tag" }, { "name": "event", "description": "event tag" }, { "name": "event_item", "description": "event item tag" } ] }