listing APIv1_beta.2.1

createItemDraft

POST
/item_draft/
This call gives Partners the ability to create an eBay draft of a item for their seller using information from their site.

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.

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.

Input

Resource URI (production)

POST https://api.ebay.com/sell/listing/v1_beta/item_draft/

URI parameters

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

HeaderTypeDescription
X-EBAY-C-MARKETPLACE-IDstringUse this header to specify an eBay marketplace ID. For a list of supported sites, see API Restrictions in the Listing API overview.

Occurrence: Required

Content-LanguagestringUse this header to specify the natural language of the seller. For details, see Content-Language in HTTP request headers.

Required: For EBAY_CA in French.

(Content-Language = fr-CA)

Occurrence: Strongly Recommended

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.item.draft

eBayUser

See OAuth access tokens for more information.

Input container/fieldTypeDescription
categoryIdstringThe ID of the leaf category associated with this item. A leaf category is the lowest level in that category and has no children.

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

Occurrence: Optional

conditionConditionEnumAn enumeration value representing the condition of the item, such as NEW.

Note: In the US and Australian marketplaces, Condition ID 2000 now maps to an item condition of 'Certified Refurbished', but this item condition is only available for use for a select number of US and Australian sellers. Other sellers on these two marketplaces will get an error when attempting to create an item draft with the Listing API using the 'Manufacturer Refurbished' item condition.

For all other marketplaces besides the US and Australia, Condition ID 2000 still maps to 'Manufacturer Refurbished'. Any US or Australian seller who is interested in eligibility requirements to list with 'Certified Refurbished' should see the Certified refurbished program page in Seller Center.

Occurrence: Optional

formatListingFormatEnumThe format of the listing.

Valid Values: FIXED_PRICE and AUCTION

Occurrence: Optional

pricingSummaryPricingSummaryThe container that for the information about the cost of an item, such as the price or auction start price.

Occurrence: Optional

pricingSummary.auctionReservePriceAmountThe 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 How reserve prices work.

Restrictions:
  • The value is not supported for FIXED_PRICE format.
  • The value format has a maximum of two decimal points.

Occurrence: Optional

pricingSummary.auctionReservePrice.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field.

Restriction: Only the currency of the marketplace is supported. For example, on the US marketplace the only currency supported is USD.

Occurrence: Optional

pricingSummary.auctionReservePrice.valuestringThe monetary amount, in the currency specified by the currency field.

Occurrence: Optional

pricingSummary.auctionStartPriceAmountThe minimum amount required for the first bid.

Note: The auctionStartPrice value must be less than the auctionReservePrice value.

Restrictions:
  • The value is not supported for FIXED_PRICE format.
  • The value format has a maximum of two decimal points.

Occurrence: Optional

pricingSummary.auctionStartPrice.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field.

Restriction: Only the currency of the marketplace is supported. For example, on the US marketplace the only currency supported is USD.

Occurrence: Optional

pricingSummary.auctionStartPrice.valuestringThe monetary amount, in the currency specified by the currency field.

Occurrence: Optional

pricingSummary.priceAmountThe Buy It Now Price for the item.

Occurrence: Optional

pricingSummary.price.currencyCurrencyCodeEnumThe three-letter ISO 4217 code representing the currency of the amount in the value field.

Restriction: Only the currency of the marketplace is supported. For example, on the US marketplace the only currency supported is USD.

Occurrence: Optional

pricingSummary.price.valuestringThe monetary amount, in the currency specified by the currency field.

Occurrence: Optional

productProductThe container for the product details of the item.

Occurrence: Optional

product.aspectsarray of AspectThe list of item aspects that describe the item (such as size, color, capacity, model, brand, etc.)

Occurrence: Optional

product.aspects.namestringThe name of an aspect, such and Brand.

Occurrence: Optional

product.aspects.valuesarray of stringA list of potential values for this aspect.

Occurrence: Optional

product.brandstringThe name brand of the item, such as Nike, Apple, etc.

Occurrence: Optional

product.descriptionstringThe description of the item that was created by the seller. This field supports plain text or rich content within HTML tags.

Note: Active content is not supported. Active content includes animation or video via JavaScript, Flash, plug-ins, or form actions.

Max Length: 500,000

Occurrence: Optional

product.epidstringAn EPID is the eBay product identifier of a product from the eBay product catalog.

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

Occurrence: Optional

product.imageUrlsarray of stringThe image URLs of the item. The first URL will be the primary image, which appears on the View Item page in the eBay listing.

The URL can be from the following:
  • The eBay Picture Services (images previously uploaded).
  • A server outside of eBay (self-hosted).
For more details, see PictureURL and Introduction to Pictures in Listings.

Maximum: 12 URLs (for most categories and marketplaces)

Restrictions:
  • You cannot mix self-hosted and EPS-hosted URLs in the same listing.
  • All image URLs must be 'https'.

Occurrence: Optional

product.titlestringThe seller-created title of the item. This should include unique characteristics of the item, such as brand, model, color, size, capacity, etc.

For example: Levi's 501 size 10 black jeans

Occurrence: Required

charityCharityThis 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 charityId field to identify the charitable organization, and the donationPercentage field that will set the percentage of the sales proceeds that will be donated to the charitable organization.

Occurrence: Optional

charity.donationPercentagestringThis field sets the percentage of the purchase price that the charitable organization (identified in the charityId 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. 10, 15, 20...95,... 100). The seller would pass in 10 for 10 percent, 15 for 15 percent, 20 for 20 percent, and so on, all the way to 100 for 100 percent.

Note: For this field, createItemDraft 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.

Occurrence: Conditional

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

This field is conditionally required if a seller is planning on donating a percentage of the sale proceeds to a charitable organization.

The eBay-assigned unique identifier of a charitable organization can be found using the GetCharities call of the Trading API. In the GetCharities call response, this unique identifier is shown in the id attribute of the Charity container.

Occurrence: Conditional

Output

HTTP response headers

Output container/fieldTypeDescription
itemDraftIdstringThe eBay generated ID of the listing draft.

Occurrence: Always

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

This is returned when the seller is using a mobile app.

Occurrence: Always

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

This is returned when the seller is using mobile web (mweb) or the desktop web.

Note: You must construct the URL using the URL returned in this field and a session token.

For example: sellFlowUrl?id_token=session_token

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
201OK
400Bad Request
500Internal Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
155000API_LISTINGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
155001API_LISTINGREQUESTMissing field: {fieldName}. The indicated field is required for this request. Add the field and resubmit the call.
155002API_LISTINGREQUESTThe X-EBAY-C-MARKETPLACE-ID header is missing. This is a required header.
155003API_LISTINGREQUESTThe Marketplace {marketplaceId} is not supported. Supported values are {allowedMarketplaces}.
155004API_LISTINGREQUESTTo 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.
155005API_LISTINGREQUESTInvalid header: {fieldName}. Correct the value and resubmit the call.
155006API_LISTINGREQUESTImage URLs must be HTTPS.
155007API_LISTINGREQUESTInvalid field: {fieldName}. The indicated field contains an invalid value. Correct the value and resubmit the call.
155008API_LISTINGREQUESTThe currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}.
155009API_LISTINGREQUESTThe 'auctionStartPrice' value must be less than 'auctionReservePrice' value.
155010API_LISTINGREQUESTThe 'price' value must be greater than 'auctionReservePrice' value.
155011API_LISTINGREQUESTThe 'auctionReservePrice' value is not supported for FIXED_PRICE format.
155012API_LISTINGREQUESTThe 'price' value must be greater than 'auctionStartPrice' value.
155013API_LISTINGREQUESTThe 'auctionStartPrice' value is not supported for FIXED_PRICE format.
155014API_LISTINGREQUESTThe 'price' value format is a maximum of two decimal points.
155015API_LISTINGREQUESTThe 'auctionStartPrice' value format is a maximum of two decimal points.
155016API_LISTINGREQUESTThe 'auctionReservePrice' value format is a maximum of two decimal points.
155017API_LISTINGREQUESTTo enable a charity donation, you must submit both 'charityId' and 'donationPercentage'.
155018API_LISTINGREQUESTThe {itemCondition} item condition is no longer supported for the specified marketplace. Please select another item condition. For more details, please refer to the API documentation.

Warnings

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Create a Fixed-Price Item Listing Draft on eBay

This sample creates a fixed-price item listing draft on eBay using the item details from the Partner's site.

Input

The inputs are the item details, such as title, condition, price, etc.
POST
https://api.ebay.com/sell/listing/v1_beta/item_draft/

Output

The output is the ID of the draft and the URL (for mweb and web) and URI (for mobile), which you use to send the seller to the listing draft that was created on the eBay site.

Sample 2: Create an Auction Item Listing Draft on eBay

This sample creates an eBay item listing draft for an auction on eBay using the item details from the Partner's site.

Input

The inputs are the item details, such as title, condition, price, etc., and auction information, such as reserve price.
POST
https://api.ebay.com/sell/listing/v1_beta/item_draft/

Output

The output is the ID of the draft and the URL (for mweb and web) and URI (for mobile), which you use to send the seller to the listing draft that was created on the eBay site.

Sample 3: Create a Charitable Auction Listing Draft on eBay

This sample creates a charitable auction listing draft on eBay using the item details from the Partner's site.

Input

The inputs are the item details, such as title, condition, price, aspects, etc., and the charitable organization that will receive a percentage of the sales proceeds from each sale.
POST
https://api.ebay.com/sell/listing/v1_beta/item_draft/

Output

The output is the ID of the draft and the URL (for mweb and web) and URI (for mobile), which you use to send the seller to the listing draft that was created on the eBay site.