openapi: 3.0.0
info:
title: eBay Account Advertising_eligibility Deal_item API
description: The Account API gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information.
For details on the availability of the methods in this API, see Account API requirements and restrictions.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/account/v1
tags:
- name: Deal_item
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
components:
schemas:
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.
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.
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.
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.
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.
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.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
authorizationCode:
authorizationUrl: https://auth.ebay.com/oauth2/authorize
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope/sell.account.readonly: View your account settings
https://api.ebay.com/oauth/api_scope/sell.account: View and manage your account settings