api-specs/sell_listing_v1_beta_oas3.yaml
---
openapi: "3.0.0"
info:
title: "Listing API"
description: "<span class=\"tablenote\"><b>Note:</b> This is a <a href=\"https://developer.ebay.com/api-docs/static/versioning.html#limited\"\
\ target=\"_blank\"> <img src=\"/cms/img/docs/partners-api.svg\" class=\"legend-icon\
\ partners-icon\" title=\"Limited Release\" alt=\"Limited Release\" />(Limited\
\ Release)</a> API available only to select developers approved by business units.</span><br\
\ /><br />Enables a seller adding an ad or item on a Partner's site to automatically\
\ create an eBay listing draft using the item details from the Partner's site."
contact:
name: "eBay Inc,"
license:
name: "eBay API License Agreement"
url: "https://go.developer.ebay.com/api-license-agreement"
version: "v1_beta.3.1"
servers:
- url: "https://api.ebay.com{basePath}"
description: "Production"
variables:
basePath:
default: "/sell/listing/v1_beta"
paths:
/item_draft/:
post:
tags:
- "item_draft"
description: "This call gives Partners the ability to create an eBay draft of\
\ a item for their seller using information from their site. <br /><br />This\
\ lets the Partner increase the exposure of items on their site and leverage\
\ the eBay user listing experience seamlessly. This experience provides guidance\
\ on pricing, aspects, etc. and recommendations that help create a listing\
\ that is complete and improves the exposure of the listing in search results.\
\ <br /><br />After the listing draft is created, the seller logs into their\
\ eBay account and uses the listing experience to finish the listing and publish\
\ the item on eBay."
operationId: "createItemDraft"
parameters:
- name: "Content-Language"
in: "header"
description: "Use this header to specify the natural language of the seller.\
\ For details, see Content-Language in <a href=\"/api-docs/static/rest-request-components.html#headers\"\
>HTTP request headers</a>. <br /><br /><b> Required: </b>For EBAY_CA in\
\ French. <br /><br />(Content-Language = <code>fr-CA</code>)"
required: false
schema:
type: "string"
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
description: "Use this header to specify an eBay marketplace ID. For a list\
\ of supported sites, see <a href=\"/api-docs/sell/listing/overview.html#API\"\
>API Restrictions</a> in the Listing API overview. "
required: true
schema:
type: "string"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ItemDraft"
required: false
responses:
201:
description: "OK"
content:
application/json:
schema:
$ref: "#/components/schemas/ItemDraftResponse"
400:
description: "Bad Request"
x-response-codes:
errors:
155010:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'price' value must be greater than 'auctionReservePrice'\
\ value."
155011:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'auctionReservePrice' value is not supported for\
\ FIXED_PRICE format."
155008:
domain: "API_LISTING"
category: "REQUEST"
description: "The currency {currency} is not supported for {fieldName}.\
\ The supported currency for the {marketplaceId} marketplace is\
\ {supportedCurrencyCode}."
155009:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'auctionStartPrice' value must be less than 'auctionReservePrice'\
\ value."
155014:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'price' value format is a maximum of two decimal\
\ points."
155015:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'auctionStartPrice' value format is a maximum of\
\ two decimal points."
155012:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'price' value must be greater than 'auctionStartPrice'\
\ value."
155013:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'auctionStartPrice' value is not supported for FIXED_PRICE\
\ format."
155018:
domain: "API_LISTING"
category: "REQUEST"
description: "The {condition} item condition is restricted. Please\
\ select another item condition. For more details, please refer\
\ to the API documentation."
155016:
domain: "API_LISTING"
category: "REQUEST"
description: "The 'auctionReservePrice' value format is a maximum\
\ of two decimal points."
155017:
domain: "API_LISTING"
category: "REQUEST"
description: "To enable a charity donation, you must submit both 'charityId'\
\ and 'donationPercentage'."
155002:
domain: "API_LISTING"
category: "REQUEST"
description: "The X-EBAY-C-MARKETPLACE-ID header is missing. This\
\ is a required header."
155003:
domain: "API_LISTING"
category: "REQUEST"
description: "The Marketplace {marketplaceId} is not supported. Supported\
\ values are {allowedMarketplaces}."
155001:
domain: "API_LISTING"
category: "REQUEST"
description: "Missing field: {fieldName}. The indicated field is required\
\ for this request. Add the field and resubmit the call."
155006:
domain: "API_LISTING"
category: "REQUEST"
description: "Image URLs must be HTTPS."
155007:
domain: "API_LISTING"
category: "REQUEST"
description: "Invalid field: {fieldName}. The indicated field contains\
\ an invalid value. Correct the value and resubmit the call."
155004:
domain: "API_LISTING"
category: "REQUEST"
description: "To create the draft, we need more information about\
\ the item. Please update the title to include unique characteristics\
\ of the item, such as brand, model, color, size, capacity, etc.\
\ For example, Levi's 501 size 10 black jeans."
155005:
domain: "API_LISTING"
category: "REQUEST"
description: "Invalid header: {fieldName}. Correct the value and resubmit\
\ the call."
500:
description: "Internal Server Error"
x-response-codes:
errors:
155000:
domain: "API_LISTING"
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/sell.item.draft"
components:
schemas:
Amount:
type: "object"
properties:
currency:
type: "string"
description: "The three-letter <a href=\"https://www.iso.org/iso-4217-currency-codes.html\"\
\ target=\"_blank\">ISO 4217</a> code representing the currency of the\
\ amount in the <b> value</b> field. <br /><br /><b>Restriction: </b>\
\ Only the currency of the marketplace is supported. For example, on the\
\ US marketplace the only currency supported is USD. For implementation\
\ help, refer to <a href='https://developer.ebay.com/api-docs/sell/listing/types/bas:CurrencyCodeEnum'>eBay\
\ API documentation</a>"
value:
type: "string"
description: "The monetary amount, in the currency specified by the <b>\
\ currency</b> field."
description: "The type that defines the fields for the currency and a monetary\
\ amount."
Aspect:
type: "object"
properties:
name:
type: "string"
description: "The name of an aspect, such and Brand."
values:
type: "array"
description: "A list of potential values for this aspect."
items:
type: "string"
description: "The type that defines the fields for the item aspects."
Charity:
type: "object"
properties:
donationPercentage:
type: "string"
description: "This field sets the percentage of the purchase price that\
\ the charitable organization (identified in the <strong>charityId</strong>\
\ field) will receive for each sale that the listing generates. This field\
\ is conditionally required if a seller is planning on donating a percentage\
\ of the sale proceeds to a charitable organization. This numeric value\
\ can range from 10 to 100, and in any 5 (percent) increments in between\
\ this range (e.g. <code>10</code>, <code>15</code>, <code>20</code>...<code>95</code>,...\
\ <code>100</code>). The seller would pass in <code>10</code> for 10 percent,\
\ <code>15</code> for 15 percent, <code>20</code> for 20 percent, and\
\ so on, all the way to <code>100</code> for 100 percent.<br /><br /><span\
\ class=\"tablenote\"><b>Note: </b> For this field, <strong>createItemDraft</strong>\
\ will only validate that a positive integer value is supplied, so the\
\ listing draft will still be successfully created (with no error or warning\
\ message) if a non-supported value is specified. However, if the seller\
\ attempted to publish this listing draft with an unsupported value, the\
\ charity information would just be dropped from the listing. </span>"
charityId:
type: "string"
description: "The eBay-assigned unique identifier of the charitable organization\
\ that will receive a percentage of the sales proceeds. The charitable\
\ organization must be reqistered with the PayPal Giving Fund in order\
\ to receive sales proceeds through eBay listings.<br/><br/> This field\
\ is conditionally required if a seller is planning on donating a percentage\
\ of the sale proceeds to a charitable organization. <br/><br/>The eBay-assigned\
\ unique identifier of a charitable organization can be found using the\
\ <strong>GetCharities</strong> call of the Trading API. In the <strong>GetCharities</strong>\
\ call response, this unique identifier is shown in the <strong>id</strong>\
\ attribute of the <strong>Charity</strong> container."
description: "This type is used to identify the charitable organization that\
\ will receive a percentage of sale proceeds for each sale generated by the\
\ listing. This container also includes the donation percentage, which is\
\ the percentage of the sale proceeds that the charitable organization will\
\ get.<br/><br/>In order to receive a percentage of the sales proceeds, the\
\ non-profit organization must be registered with the PayPal Giving Fund,\
\ which is a partner of eBay for Charity."
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."
ItemDraft:
type: "object"
properties:
categoryId:
type: "string"
description: "The ID of the leaf category associated with this item. A\
\ leaf category is the lowest level in that category and has no children.\
\ <br /><br /><span class=\"tablenote\"><b>Note: </b> If you submit both\
\ a category ID and an EPID, eBay determines the best category based on\
\ the EPID and uses that. The category ID will be ignored. </span>"
condition:
type: "string"
description: "The enumeration value passed in here sets the condition of\
\ the item, such as <code>NEW</code> or <code>USED_EXCELLENT</code>. See\
\ <a href=\"/api-docs/sell/listing/types/api:ConditionEnum\">ConditionEnum</a>\
\ for the full list of supported values.<br /><br />Supported item conditions\
\ can vary by eBay category. To see which item conditions are supported\
\ for a category, you can use the <a href=\"/api-docs/sell/metadata/resources/marketplace/methods/getItemConditionPolicies\"\
>getItemConditionPolicies</a> method of the <strong>Metadata API</strong>.\
\ <br /><br /><span class=\"tablenote\"> <strong>Note:</strong> The 'Manufacturer\
\ Refurbished' item condition is no longer a valid item condition in any\
\ eBay marketplace, and to reflect this change, the pre-existing <code>MANUFACTURER_REFURBISHED</code>\
\ enumeration value has been replaced by the <code>CERTIFIED_REFURBISHED</code>\
\ enumeration value. CR-eligible sellers should make a note to start using\
\ <code>CERTIFIED_REFURBISHED</code> from this point forward. To list\
\ an item as 'Certified Refurbished', a seller must be pre-qualified by\
\ eBay for this feature. Any seller who is not eligible for this feature\
\ will be blocked if they try to create a new listing or revise an existing\
\ listing with this item condition. <br><br> Any seller that is interested\
\ in eligibility requirements to list with 'Certified Refurbished' should\
\ see the <a href=\"https://pages.ebay.com/seller-center/listing-and-marketing/certified-refurbished-program.html\"\
\ target=\"_blank\">Certified refurbished program</a> page in Seller Center.\
\ </span><br /><br /><span class=\"tablenote\"> <strong>Note:</strong>\
\ As of September 1, 2021, <code>SELLER_REFURBISHED</code> can no longer\
\ be used as a condition value in the <strong>Cell Phones & Smartphones</strong>\
\ category (category ID 9355) for the following marketplaces: US, Canada,\
\ UK, Germany, and Australia. The <code>SELLER_REFURBISHED</code> item\
\ condition will be replaced by one of three new refurbished values, which\
\ include <code>EXCELLENT_REFURBISHED</code> (condition ID 2010), <code>VERY_GOOD_REFURBISHED</code>,\
\ and <code>GOOD_REFURBISHED</code> (condition ID 2030). To use any of\
\ these new refurbished item conditions in category 9355, sellers must\
\ go through an application and qualification process. Any seller who\
\ is not eligible to use these new refurbished item conditions in category\
\ 9355 will get an error if they try to create an item draft with any\
\ of these three new item conditions. </span> For implementation help,\
\ refer to <a href='https://developer.ebay.com/api-docs/sell/listing/types/api:ConditionEnum'>eBay\
\ API documentation</a>"
format:
type: "string"
description: "The format of the listing. <br><br><b>Valid Values: </b> <code>FIXED_PRICE</code>\
\ and <code>AUCTION</code> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/listing/types/api:ListingFormatEnum'>eBay\
\ API documentation</a>"
pricingSummary:
description: "The container that for the information about the cost of an\
\ item, such as the price or auction start price."
$ref: "#/components/schemas/PricingSummary"
product:
description: "The container for the product details of the item."
$ref: "#/components/schemas/Product"
charity:
description: "This container is used to identify the charitable organization\
\ that will receive a percentage of sale proceeds for each sale generated\
\ by the listing. This container consists of the <strong>charityId</strong>\
\ field to identify the charitable organization, and the <strong>donationPercentage</strong>\
\ field that will set the percentage of the sales proceeds that will be\
\ donated to the charitable organization."
$ref: "#/components/schemas/Charity"
description: "The type that defines the fields for the listing details."
ItemDraftResponse:
type: "object"
properties:
itemDraftId:
type: "string"
description: "The eBay generated ID of the listing draft."
sellFlowNativeUri:
type: "string"
description: "The URI the Partner uses to send the seller to their listing\
\ draft that was created on the eBay site. From there the seller can change,\
\ update, and publish the item on eBay. <br /><br />This is returned when\
\ the seller is using a mobile app. "
sellFlowUrl:
type: "string"
description: "The web URL the Partner uses to send the seller to the listing\
\ draft that was created on the eBay site. From there the seller can change,\
\ update, and publish the item on eBay. <br /><br />This is returned when\
\ the seller is using mobile web (mweb) or the desktop web. <br /> <br\
\ /><b>Note: </b> You must construct the URL using the URL returned in\
\ this field and a session token.<br /><br /><b>For example: </b> <code><i>sellFlowUrl</i>?id_token=<i>session_token</i><code>"
description: "The type that defines the field for the <b> createItemDraft</b>\
\ response."
PricingSummary:
type: "object"
properties:
auctionReservePrice:
description: "The minimum amount the seller is willing to sell the item\
\ for. If the reserve price isn't met, the item won't be sold. For details,\
\ see <a href=\"https://www.ebay.com/help/buying/bidding/reserve-prices-work?id=4018\"\
>How reserve prices work</a>.<br /><br /><b>Restrictions</b>: <ul><li>The\
\ <b>value</b> is not supported for <code>FIXED_PRICE</code> format.</li><li>The\
\ <b>value</b> format has a maximum of two decimal points.</li></ul>"
$ref: "#/components/schemas/Amount"
auctionStartPrice:
description: "The minimum amount required for the first bid.<br /><br /><span\
\ class=\"tablenote\"><b>Note: </b> The <b>auctionStartPrice</b> value\
\ must be less than the <b>auctionReservePrice</b> value.</span><br /><br\
\ /><b>Restrictions</b>: <ul><li>The <b>value</b> is not supported for\
\ <code>FIXED_PRICE</code> format.</li><li>The <b>value</b> format has\
\ a maximum of two decimal points.</li></ul>"
$ref: "#/components/schemas/Amount"
price:
description: "The Buy It Now Price for the item."
$ref: "#/components/schemas/Amount"
description: "The type that defines the fields for the price details for an\
\ item."
Product:
type: "object"
properties:
aspects:
type: "array"
description: "The list of item aspects that describe the item (such as size,\
\ color, capacity, model, brand, etc.)"
items:
$ref: "#/components/schemas/Aspect"
brand:
type: "string"
description: "The name brand of the item, such as Nike, Apple, etc."
description:
type: "string"
description: "The description of the item that was created by the seller.\
\ This field supports plain text or rich content within HTML tags.<br\
\ /><br /><span class=\"tablenote\"><b>Note: </b>Active content is not\
\ supported. Active content includes animation or video via JavaScript,\
\ Flash, plug-ins, or form actions.</span><br /><br /><b>Max Length:</b>\
\ 500,000"
epid:
type: "string"
description: "An EPID is the eBay product identifier of a product from the\
\ eBay product catalog. <br /><br /><span class=\"tablenote\"><b>Note:\
\ </b> If you submit both a category ID and an EPID, eBay determines the\
\ best category based on the EPID and uses that. The category ID will\
\ be ignored. </span>"
imageUrls:
type: "array"
description: "The image URLs of the item. The first URL will be the primary\
\ image, which appears on the View Item page in the eBay listing. <br\
\ /><br />The URL can be from the following: <ul><li>The eBay Picture\
\ Services (images previously uploaded). </li> <li>A server outside\
\ of eBay (self-hosted). </li> </ul> For more details, see <a href=\"\
https://developer.ebay.com/Devzone/XML/docs/Reference/eBay/AddFixedPriceItem.html#Request.Item.PictureDetails.PictureURL\"\
\ target=\"_blank\">PictureURL</a> and <a href=\"https://developer.ebay.com/DevZone/guides/features-guide/default.html#development/Pictures-Intro.html\"\
\ target=\"_blank\">Introduction to Pictures in Listings</a>. <br /><br\
\ /><b>Maximum: </b> 12 URLs (for most categories and marketplaces)<br\
\ /><br /><b>Restrictions: </b><ul><li>You cannot mix self-hosted and\
\ EPS-hosted URLs in the same listing.</li> <li> All image URLs <b> must</b>\
\ be 'https'. </li> </ul>"
items:
type: "string"
title:
type: "string"
description: "The seller-created title of the item. This should include\
\ unique characteristics of the item, such as brand, model, color, size,\
\ capacity, etc. <br /><br /> <b>For example: </b> Levi's 501 size 10\
\ black jeans"
description: "The type that defines the fields for the aspects of a product."
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.item.draft: "View and manage\
\ your item drafts."