openapi: 3.0.0 info: title: Deal API description: Note: This is a Limited Release(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.

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.' 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 - 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 - 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: limit in: query description: The maximum number of items, from the current result set, returned on a single page. 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.

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 - 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 - 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DealItemSearchResponse' '400': description: Bad Request 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 x-response-codes: errors: '180009': domain: API_DEAL category: REQUEST description: Not authorized. Please contact developer support for assistance. '500': description: Internal Server 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 /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.

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. ' 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 - 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 - 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Event' '400': description: Bad Request '403': description: Forbidden x-response-codes: errors: '180009': domain: API_DEAL category: REQUEST description: Not authorized. Please contact developer support for assistance. '404': description: Not Found x-response-codes: errors: '180004': domain: API_DEAL category: REQUEST description: The event Id is invalid for the requested marketplace. '500': description: Internal Server 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 /event: get: tags: - event description: 'This method returns paginated results containing all eBay events for the specified marketplace.

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. ' 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 - 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 - 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 - 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EventSearchResponse' '400': description: Bad Request 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 x-response-codes: errors: '180009': domain: API_DEAL category: REQUEST description: Not authorized. Please contact developer support for assistance. '500': description: Internal Server 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 /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.

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

Use the getEvents method to retrieve event IDs.

Maximum Value: 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.

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

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 - 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 - 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 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EventItemSearchResponse' '400': description: Bad Request 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 x-response-codes: errors: '180009': domain: API_DEAL category: REQUEST description: Not authorized. Please contact developer support for assistance. '500': description: Internal Server 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 components: schemas: Amount: type: object properties: currency: type: string 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. For implementation help, refer to eBay API documentation value: type: string description: The monetary value, in the currency specified by the currency field. description: The currency and value of the item. Coupon: type: object properties: redemptionCode: type: string description: The coupon code. terms: description: The terms of use associated with the coupon. $ref: '#/components/schemas/Terms' description: The details for the coupon available for the item. DealItem: type: object properties: additionalImages: type: array description: The additional images for the deal 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 deal item. A leaf category is the lowest level in a category and has no children. commissionable: type: boolean description: A boolean value specifying whether the listing has commission. dealAffiliateWebUrl: type: string description: The deal associated with the item with affiliate attribution. dealEndDate: type: string description: The date after which the deal ends. dealStartDate: type: string description: The date on which the deal starts. dealWebUrl: type: string description: The web URL for the deal associated with the item. energyEfficiencyClass: type: string description: A string value specifying the Energy Efficiency class. image: description: The primary image for the deal 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 deal item group. This is the parent item ID for the seller-defined variations.

Note: This field is returned for multiple-SKU items.' itemGroupType: type: string 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. For implementation help, refer to eBay API documentation itemId: type: string description: 'The unique identifier for the deal item.

Note: This field is only returned for single-SKU items.' itemWebUrl: type: string description: The web URL for the deal item. legacyItemId: type: string description: The legacy item ID associated with the deal item. 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: 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.

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

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

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

Note: This field is returned for multiple-SKU items.' itemGroupType: type: string 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. For implementation help, refer to eBay API documentation itemId: type: string description: 'The unique identifier for the event item.

Note: This field is only returned for single-SKU items.' itemWebUrl: type: string description: The web URL for the event item. legacyItemId: type: string description: The legacy item ID associated with the event item. 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: type: string description: ' For implementation help, refer to eBay API documentation' shippingOptions: type: array description: The cost required to ship the event item. items: $ref: '#/components/schemas/ShippingOption' title: type: string description: The title of the event item. 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"
' 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.

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

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

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

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

Note: The pricing treatment affects how and where the discounted price can be displayed. For implementation help, refer to eBay API documentation' description: A type that describes the seller discount. ShippingOption: type: object 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. ' description: 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. summary: type: string description: A summarized description of the terms. description: 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.