Listing an Item

This section of the guide describes the details of how to list items on eBay.

Subtopics

General listing details

Required Information for eBay Listings

Optional Information for eBay Listings

Required Product Identifiers Mandate (Current Phase)

Required Product Identifiers Mandate (Future Phase)

Considering Best Match When Revising and Relisting Items

General listing details

Before listing items with the APIs, be sure you're familiar with the following general API details:

Note that GetMyeBaySelling returns seller limit information for the seller if the seller is subject to seller limits. (For more information, see Seller Limits.)

Other information returned with GetMyeBaySelling is the remaining quantity of items that may be listed and the remaining listing value. If you exceed these limits, your AddItem calls will fail. To be sure you are within limits, call GetMyeBaySelling before calling AddItem or AddItems.

Note that the AddItem and ReviseItem calls support both auctions and fixed-price listings, but only the AddFixedPriceItem and ReviseFixedPriceItem call support multiple variations in fixed-price listings. So, if you are going to create multiple-variation listings with the Trading API, the "fixed-price" API calls have to be used.

For information on the fees associated with listing items, see Fees Resulting from Listing an Item. In addition:

Sellers who engage in cross-border trade on sites that require a recoupment agreement must agree to the recoupment terms before using the AddItem or the VerifyAddItem. This agreement allows eBay to reimburse a buyer during a dispute and then recoup the cost from the seller.

Check for a Message node in the VerifyAddItem response because it may indicate that an AddItem attempt will be unsuccessful; see the following Knowledge Base article:

VerifyAddItem Returns Success with No Errors, but AddItem Returns Failure with Errors

https://ebaydts.com/eBayKBDetails?KBid=912

See Managing Inventory for additional information about these calls.

Required Information for eBay Listings

There are a number of item properties that can be set, some required and some optional. All define how the item is displayed, how a buyer needs to go about purchasing the item, and what actions need to occur in the checkout process. See the schema documentation for ItemType for a complete list of its properties.

This section summarizes some of the information that most eBay listings require.

Listing Title

The listing's title summarizes what the item is, and is seen on all pages (View Item page, search results, etc.). The listing title should have the intent of drawing the attention of potential buyers interested in that type of item. A title is required for all listings. The maximum length of an listing title is 80 characters.

For an additional fee, a seller can include a subtitle. The text of the subtitle is also displayed on the View Item page and in search results. The maximum length of an subtitle is 55 characters.

Listing Description

The listing description informs prospective buyers what the item is, and what makes it unique and appealing. The listing description should highlight/cover the most essential product aspects, but does not need to cover all aspects, since this detailed information can be seen in the Item specifics section of the View Item page. For example, a listing description for an iPhone might touch on the model number, color, storage capacity, and network, but all other product aspects can be isolated and viewed in the Item specifics section.

A seller can use HTML or XML-reserved characters in listing descriptions, but cannot use active content such as animation or video via JavaScript, Flash, plug-ins, or form actions. All active content will be blocked/removed from a listing. The HTML tags used in a listing description count toward the maximum allowed character limit, which is 500,000 for most sites.

HTML Content Dimensions

Allowed File Linking

The only external links (to sites outside of eBay) allowed in listings include the following:

Any external links must use the 'HTTPS' protocol (and not 'HTTP'), so if a seller's external server that is hosting images does not support the 'HTTPS' protocol, this server cannot be used. All external links should use the target="_blank" attribute.

For more information, see eBay's Links policy

Optimizing Descriptions for Mobile Devices

Long listing descriptions can be problematic when viewing items on a mobile device, since a listing description on a mobile device cannot exceed 800 characters. So, if the listing description is longer than 800 characters, the full listing description will not be shown on a mobile device and may be cut off abruptly and/or display misleading/incomplete details. The 800 characters that eBay will display in mobile devices is not necessarily the first 800 characters, which can definitely lead to some unpredictable results. To solve this problem, sellers can use specialized HTML div and span tags within the Trading API's <Description> field to customize a listing description only used/viewed in mobile devices. This div tag uses a vocab attribute (set to a value of https://schema.org/) and a typeof attribute (set to a value of Product), and the span tag uses a property attribute (set to a value of description). Below is an example of what these tags would look like inside of a <Description> field:

<Description>
    <div vocab="https://schema.org/" typeof="Product">
    <span property="description">
	The text between the span tags will control the item description that is displayed for 
	the item on mobile devices. Up to 800 characters can be used within the span tags, and 
	any HTML tags count toward this limit. Once the 800 character limit is reached, any 
	remaining text/tags are ignored by eBay and dropped, and will not be shown in the 
	mobile device version of the View Item page. The types of HTML formatting/tags that 
	can be used are limited to the following: all opening and closing tags used for 
	ordered or unordered lists (<ol>, </ol>, <ul>, </ul>, 
	<li>, </li>), &nbsp; (non-breaking space), and <br> or <br/> 
	(line break) tags. Each list element (<li>element1</li>) counts as three 
	characters toward the maximum character limit, and the other list tags (<ol>, 
	</ol>, <ul>, </ul>) will not count toward the maximum character 
	limit. Each <br> or <br/> tag will count 50 characters toward the maximum 
	character limit, and each &nbsp; (non-breaking space) will count just one character 
	toward maximum character limit. If your complete listing description is less than 800 
	characters long, these <div> and <span> tags should not be necessary, as 
	your listing description should display just fine on mobile devices.
    </span>
    </div>
    Complete listing description goes here. 
    .........
	
</Description>

All of the text above between the <span> tags will become the item description on mobile devices. The text between these tags must not exceed 800 characters. Only a few basic HTML formatting/tags can be used between the span tags, and these include tags for ordered and unordered lists, non-breaking space tags (&nbsp;), and line break tags (<br/>). The use of these tags will count towards the 800-character limit as follows:

Sellers must make sure that they do not exceed the 800-character limit allowed in between the span tags. Once/if the 800-character limit is reached, all text after that will just be ignored by eBay.

In addition to using these customized div and span tags to create mobile-friendly listing descriptions, you can also see this Best Practices help doc for more tips on making listings look great on mobile devices.

Item Condition

The item's condition is required in the majority of eBay categories, and it is recommended that you use the Item.ConditionDescription field to describe used items, as opposed to describing the condition of that item in the Item.Description field. For more information about describing the condition of an item, see Specifying an Item's Condition and the eBay help page Item conditions by category.

Site and Categories

The seller must designate the eBay site on which the item will be listed (see Standard Input Data). The seller must also specify a category on the selected site. The seller has the option to specify a second category for the same item on the same site. If a second category is selected, the item is listed simultaneously in the two categories. For more information on categories, see Categories (Introduction). For information on retrieving category details, see Retrieving the Category Hierarchy for a Site.

If you define an item and a problem occurs with the category ID you specified, see Mapping Old Category IDs to Current IDs for information about how to keep category data for individual items synchronized with eBay's category data.

Store Categories

If the seller is an eBay Store owner and wants to list the item in their storefront, the seller can optionally specify up to two custom categories defined for that storefront by using Storefront.StoreCategoryID and Storefront.Category2ID in addition to specifying the primary and secondary eBay categories. For additional information, see Managing Store Categories.

Free Added Category

eBay may choose at times to promote a listing with a free second category. eBay does this to help increase the visibility of the item to buyers who may be browsing in a category different than the one specified for the listing. When eBay adds a category, sellers are not charged any List in Two Categories fees for the listing. eBay may choose to add a second category to listings even on sites that normally do not support the ability to list in two categories.

The AddItem family of calls does not return any information about free added categories. However, GetItem and GetSellerList return information about the added category in a FreeAddedCategory container (and SecondaryCategory container is not returned).

If a seller submits a listing with two categories and it qualifies for a free second category, the fees returned from AddItem will reflect charges for listing in two categories, but the seller will receive a refund of any List in Two Categories fees for that listing. In this situation, GetItem and related calls return both categories in the PrimaryCategory and SecondaryCategory nodes as usual and FreeAddedCategory is not returned.

Product Identifier

Most branded products sold on eBay must be associated with one or more recognized product identifiers. This can be a combination of brand, manufacturer part number (MPN), and Global Trade Item Number (GTIN — one of a set of globally recognized identifiers such as UPC and ISBN). These identifiers are recognized worldwide, and eBay's product catalog is keyed to them. When a seller properly identifies a product, the seller's listing for that product is automatically populated with all of eBay's catalog details about the product.

Different products have varying product identifier requirements and restrictions based on product category, brand, and field validation. You can specify product identifiers using the Item.ProductListingDetails container or the Item.ItemSpecifics container in the Add, Relist, Revise, and Verify calls. For more information about when and how to use product identifiers, see Using Product Identifiers.

Pictures

All listings must have at least one picture of the item. In almost any category at no cost, sellers can include up to 24 pictures in one listing. For multiple-variation listings, a maximum of 12 pictures may be used per variation. Motor vehicle listings are an exception. The number of included pictures in motor vehicle listings depend on the selected vehicle package (see Fees for selling vehicles on eBay Motors). For the complete list of picture requirements and information about using pictures in a listing, see Introduction to Pictures in Listings.

Price

A new listing must have a starting price.

For an auction listing, the starting price is the price at which the progressive bidding starts. For a fixed-price listing, the starting price is the static price at which a buyer can purchase the item. Sellers can also add the Buy It Now feature to an auction listing, or assign a reserve price to the listing. If a reserve price is set, the item will not sell unless the bid of the winning bidder is higher than this price.

Price it Right

https://pages.ebay.com/sellerinformation/tips-for-selling-online/effective-ebay-listings/online-pricing.html

Selling using a fixed price

https://pages.ebay.in/help/sell/fixed-price.html

Standard selling fees

https://pages.ebay.com/help/sell/fees.html

Payment Methods

eBay now controls the available electronic payment methods for every marketplace. A seller will only have to specify one or more offline payment methods for listings that support or require offline payment.

Quantity

A fixed-price listing may offer one item, or a multiple quantity of items. A fixed-price listing ends when the last item has been sold (if the listing duration has not yet passed and ended the listing). An exception to this rule involves using the Out-of-Stock feature. If this feature is enabled for the seller's account, the fixed-price listing with a "Good 'Til Cancelled" listing duration will remain active (but hidden from search results) even if the quantity has gone down to 0. See the Using the Out-of-Stock Feature page for more information on this feature.

Listing Type

Specify the listing type to indicate if the item will sell for a static, fixed price (fixed-price listing), sell using a bidding process (auction listing), or sell via a classified ad where the actual transaction (exchange of money between buyer and seller) takes place off of eBay platform. A listing type is required for a new item listing. If not specified in an API call, the listing type will default to an auction listing. Some listing types have other seller qualifications. For information on all listing types, see Listing Types (Formats).

Duration

A listing's duration is the time (expressed in days) that the listing will be active on the eBay site. For auction listings, the listing ends and the winning bidder is determined when this time has passed (and the highest bid matches or exceeds reserve price, if set). The duration for all fixed-price listings is always "Good 'Til Cancelled", which means the listing will live until quantity is 0. If the Out-of-Stock feature is enabled, even fixed-price listings with 0 quantity will remain active (but hidden from search results). The seller would just need to add quantity to the listing in order for the listing to start showing up in search results and in the view item page. See the Using the Out-of-Stock Feature page for more information on this feature.

Item Location

We recommend you use the postal code to specify where the item is located. This enables the ability for others to search for the item based on distance from a specified zip or postal code, which improves search. For a list of valid postal code formats for countries that support search by proximity, see Search by Postal Code Proximity.

If you do not use the postal code, a seller can specify the location of the item and the country of that location. An item's location is a free-form text value, such as "San Jose, CA." The country is indicated using the ISO 3166 two-letter abbreviation for the country, such as "us" for the United States. If specify a postal code, but do not specify a location, then the location is given a default value derived from the postal code.

The country is defined using the eBay 2-letter country code set.

Use the GeteBayDetails call to see the list of currently supported codes, and the English names associated with each code (e.g., KY="Cayman Islands").

Most of the codes that eBay uses conform to the ISO 3166 standard, but some of the codes in the ISO 3166 standard are not used by eBay. Plus, there are some non-ISO codes in the eBay list. (Additional codes appear at the end of this code list and are noted as non-ISO.)

Shipping

At listing time, the seller selects between using flat-rate shipping or calculated shipping. For flat-rate shipping, the seller specifies all shipping costs upfront based on the buyer's location and the shipping service selected by the buyer. In calculated shipping, eBay calculates shipping costs based on the shipping specifications (package dimensions and the weight of the item, or items if the seller is shipping multiple items to the buyer in the same shipment).

For more on working with shipping services and costs, see Managing Shipping.

Handling (Dispatch) Time

For most items, the seller needs to specify a handling time. This indicates how long it will take for the seller to ship the item to a buyer after receiving cleared payment. This does not include the shipping carrier's shipping time (in transit).

Top-rated sellers must offer a 0-day or 1-day handling time in order for that listing to be eligible as a Top-rated listing. The other requirement for a Top-rated listing is for the seller to accept returns for the item. Only sellers that qualify as Top-rated sellers can have Top-rated listings. For information about top-rated sellers, see https://pages.ebay.com/help/sell/top-rated.html.

Shipping Regions

The seller can also indicate where, by geographical region, the item may be shipped. This is done by specifying one shipping option, indicating: the seller will only ship to users on the same site, the seller will ship to buyers worldwide, the seller will ship to buyers on the seller's site and specified regions, or the seller will not ship the item at all. The default is to ship to buyers on the same site. If the seller indicates they will ship to the same site plus additional regions, one or more shipping regions must be specified to indicate what those additional regions are. Use GeteBayDetails with DetailName set to ShippingLocationDetails to determine which locations are valid the site. For more information, see ShipToLocation.

Return Policy

Sellers who provide a clear return policy are likely to sell a higher percentage of their listed items than sellers who do not have a clear return policy.

Sellers are required to specify a return policy for auction and fixed-price listings in most categories. Sellers can choose not to accept returns, but they must still specify this policy clearly. See Offering a Clear Return Policy.

Top-rated sellers must accept returns for a listing in order for that listing to be eligible as a Top-rated listing. Only sellers that qualify as Top-rated sellers can have Top-rated listings. For information about top-rated sellers, see https://pages.ebay.com/help/sell/top-rated.html.

Item Specifics

The majority of eBay categories require at least a few item specifics. Item specifics are name-value pairs the provide details about an item. In addition to item specifics that are required for a listing category, many more item specifics may be recommended for a category, and sellers should always strive to provide these recommended item specifics if they are applicable to the item. The getItemAspectsForCategory method of the Taxonomy API can be used to see the required, recommended, and optional item specifics for each eBay category.

Optional Information for eBay Listings

This section summarizes some of the additional information that can be included in a listing.

Fast Shipping and Handling

Many buyers want or need to receive an item as soon as possible after purchase (for example, last-minute shopping for the holidays). Such buyers benefit from knowing if purchasing an item from one seller would get the item into the buyer's hands faster than if purchased from another seller.

Sellers can specify prompt domestic handling and expedited shipping for items so buyers can assess whether items can be delivered within an acceptable time range.

Listing Enhancements

Listings on eBay may be enhanced to make them stand out from other listings, such as on listing browse and search pages where there are multiple items from different sellers displayed on the same page. One enhancement is to show the item's title on these pages in a bold typeface. Listing enhancements are optional and all incur additional listing fees.

Out-Of-Stock Feature

Sellers can use the Out-Of-Stock feature to keep their GTC (Good 'Til Canceled) items alive, even when the quantity goes down to zero. This enables them to replenish stock for the same ItemID, without the need to cancel and then relist when the item is back in stock. This feature is set once, as a seller preference, and then applied to all existing items as well as to any new item when the listing is created.

Donate a Percentage of the Sale

Specify whether or not to donate a percentage of the final sale price to a qualified nonprofit organization registered through the PayPal Giving Fund. These charity listings appear in the search results for the standard eBay site and in the eBay for Charity site (https://charity.ebay.com/ in the US). Charity listings will be marked with an eBay for Charity icon adjacent to the item title. A charity listing will also indicate what percentage of the sale proceeds will go towards benefiting the nonprofit organization. For more information on eBay for Charity listings, see Working with Listings that Benefit Nonprofits.

Catalog Product Details

To make it even easier for buyers to find your listing, include product details from a catalog in the listing. With this option, you search an informational catalog for a stock product that is similar your item, and eBay uses that product's stock content to fill in a portion of your listing's Item Specifics and to add other information to supplement your listing description. The eBay catalog contains descriptive information only (no actual physical products). This option is available in certain categories only.

To indicate that you want to include this kind of data in your listing, you need to specify an eBay product ID (EPID) or a UPC, ISBN, EAN, or MPN. See Pre-filling Item Specifics with Product Details for more information about product details and the data you need in order to use stock information in a listing.

If you are new to the API, it may be easiest to first develop and test the listing functionality of your application without using product details, and then add the product details once you have successfully created a number of listings the standard way.

Combined Invoice

If multiple, unpaid order line items exist between the same buyer and seller, that buyer or seller have the option of combining those multiple order line items into one order. This is known as a Combined Invoice order (formerly called combined payment order). The benefits of a Combined Invoice order are:

Shipping discount rules for flat-rate and calculated shipping are set and managed through My eBay. Optionally, shipping discount rules can be set and managed through the SetShippingDiscountProfiles API call. The shipping discounts are set in the CalculatedHandlingDiscount, CalculatedShippingDiscount, and FlatShippingDiscount containers and will apply towards eBay orders if the combined payment option is enabled.

As a seller, you control whether or not you allow buyers (or yourself) to create combined invoices. The combined payment and shipping is found in My eBay. In the API, the seller's strategy for handling combined invoice requests from buyers is set with the CombinedPaymentOption field in the SetUserPreferences call. This field takes one of the following enumeration value; if the NoCombinedPayment value is used, the seller will not allow buyers to combine individual line items into one invoice and payment; if the DiscountSpecified value is used, this indicates that any order discount to the buyer will be based on any calculated handling/shipping, flat-rate shipping, and/or promotional shipping rules have already been set up for the account (through My eBay or through SetShippingDiscountProfiles call); if the SpecifyDiscountLater value is used, it will be at the seller's discretion on whether an order discount to the buyer will be offered. The maximum amount of days (the default is 30 days) in which unpaid order line items can be combined into a Combined Invoice order is set with the CombinedDuration field in SetShippingDiscountProfiles or through the Combined Payments and Shipping Discounts preferences in My eBay.

Other Information

There are also a variety of other properties for an item that can be set. This includes adding a hit counter to the item's View Item page. A seller may also designate an auction or fixed-price listing as a private listing. When private listings are bid on or bought, the IDs of the bidders and the buyer are hidden for privacy reasons. A seller may also supply data that is applicable or meaningful only to the listing application. This application data is stored with the item data in the eBay database, but is never used by eBay for any purpose. It is there solely for the application's use.

Required Product Identifiers Mandate

Many eBay Categories require product identifiers, such as a UPC, an ISBN, an EAN, or a Brand/MPN pair. The next several sections discuss how to discover the eBay categories that require product identifiers, and then how to specify these product identifiers when creating or updating listings.

Finding Categories that Support/Require Product Identifiers

Some categories require that sellers provide a product identifier for new items in certain categories. However, whenever a product identifier (EAN, ISBN, UPC, Brand/MPN pair) is available for a branded product, it is always a good idea to create a listing using a product identifier, because among other benefits, it can improve search results on eBay and on other search engines, and it is a shortcut to creating a listing with robust listing information, including relative and helpful item specifics.

To see if a specific category supports or requires product identifiers, use the GetCategoryFeatures call with the following parameter options:

After a successful call, look for the EANEnabled, ISBNEnabled, and UPCEnabled fields under the Category node.

The values of each of these fields can be:

The value returned in the Category.BrandMPNIdentifierEnabled field is boolean, with true indicating that a brand/MPN pair can be used to identify a product, and false indicating that a brand/MPN pair cannot be used to identify a product.

Using Product Identifiers in Single-Variation Listings

Once you know that you can list your product using a product identifier, you can then set up an AddItem or AddFixedPriceItem call to create a single-variation listing.

Notes on Behavior of Brand/MPN Values

The behavior of a brand/MPN pair is summarized below:

Using Product Identifiers in Multiple-Variation Listings

The process of using product identifiers to create a multi-variation listing is slightly different. First you must use the AddFixedPriceItem call because the AddItem call doesn't support multiple variations. Also it is important to understand that the way in which you specify brand/MPN pairs and UPC, ISBN, or EAN for multi-variation listings differ. These differences are described in the next sections.

Multiple-Variation Listings Using Brand/MPN Pair

The ProductListingDetails.BrandMPN container cannot be used for multi-variation listings. If using brand and MPN (manufacturer part number) values to identify each product variation, the brand name is specified at the item level in the ItemSpecifics.NameValueList container, and the MPN for each product variation is specified at the variation level in the VariationSpecifics.NameValueList container. Examples of what the ItemSpecifics and VariationSpecifics containers would look like are shown below:

Multiple-Variation Listings Using UPC, ISBN or EAN

For multiple-variation listings, the product identifier (e.g., UPC, ISBN, or EAN) must be provided only at the variation level in the VariationProductListingDetails container. If a product identifier is provided in the Item.ProductListingDetails container for a multi-variation listing, the add/revise/relist call will fail. An example of what the VariationProductListingDetails container would look like is shown below:

Unlike single-variation listings, using product identifiers to create a multiple-variation listing does not have the added benefit of item title, item description, product images, and item specifics being automatically picked up in the listing. So, the seller must manually add these fields along with the product identifiers.

Other Notes on Multiple-Variation Listings

Considering Best Match When Revising and Relisting Items

When users search for items on eBay, the default way items are sorted is Best Match.

When you list an item, you can consider how to improve its placement, or rank, in search results. When you revise or relist an item, consider the item's performance score (i.e., the ratio of sales to impressions). An item's performance score affects the item's rank in search results.

Revising an item doesn't affect its performance score, in most cases. Similarly, relisting an item will carry over an item's performance score, regardless of changes made, in most cases. However, whether you are revising or relisting, either of the following changes will reset an item's performance score:

When relisting an item, the item performance score carries over for the first new item only. That is, if an item is relisted multiple times, only the first new item inherits the performance score. When it is time to relist the new item, its performance score carries over for the first new item only, as well.