Working with Pictures in an Item Listing

To associate a picture with an item, specify the picture's URL in the item definition.


Using eBay Picture Service vs. Self-Hosted Pictures

Uploading Pictures to eBay Picture Services (EPS)

Using a Self-Hosted Picture

Using a Stock Photo in an Item Listing

Associating Pictures with an Item

Retrieving Picture Data

All pictures must meet the picture requirements.

In addition to the sections listed above, see also Introduction to Pictures in Listings, Creating Item Listings, and Retrieving Items.

Using eBay Picture Service vs. Self-Hosted Pictures

There are two ways you can host pictures. You can upload your image files to the eBay Picture Service (EPS), which stores the files on an eBay server or you can store the image files on a server outside of eBay.

You can specify self-hosted or EPS-hosted URLs in the PictureURL field of the Add/Revise/Relist/Verify calls. The URLs passed in must all be self-hosted or all EPS-hosted. You cannot have a mix. Also, the maximum number of pictures you can have for free has been increased to 24.

These URLs will also be returned in GetItem, GetMyeBaySelling, and other "Get" calls that retrieve items. The first uploaded picture is used as the Gallery image and the product image and the value of GalleryURL is set to the URL of this image.

For additional details, see Item.PictureDetails.PictureURL.

Uploading Pictures to eBay Picture Services (EPS)

When any image is uploaded, EPS stores copies of the image at multiple sizes for display on the View Item page, Search Results page, and other locations (such as My eBay). The largest size that is stored is 1600x1600 pixels, depending on the UploadSiteHostedPictures.PictureSet value supplied. The image may be resized down to that maximum size if it is larger, otherwise EPS will store a copy that is the same size as the original image.

An image uploaded must use one of the following graphic formats: BMP, GIF, JPG, PNG, or TIF. Images in BMP, PNG, and TIF formats are converted to JPG at the time of upload, while JPG and GIF images retain their original file format.

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). Any fees associated with listing pictures through EPS will be returned in the Fees container of an Add/Revise/Relist/Verify item call.

For more information, see the eBay help page Adding photos to your listing.

The UploadSiteHostedPictures call enables you to upload image files one-at-a-time to EPS by including a binary attachment (or a reference to a picture on a web server). You do not need to use this call to upload self-hosted images before creating the listing. You can now specify up to 24 self-hosted URLs at once in Item.PictureDetails.PictureURL using the AddItem or AddFixedPriceItem calls. However, you must use the UploadSiteHostedPictures call to upload binary attachments. The call returns the URL of the stored image in SiteHostedPictureDetails.FullURL. You use this URL as the value for the PictureDetails.PictureURL field in a listing call. See Associating Pictures with an Item for more information.

The UploadSiteHostedPictures call includes support for watermarks and returns specific error messages for problems with uploading photos.

For more information, see the following pages.


FAQs on eBayPictureServices (EPS) and the UploadSiteHostedPictures API call

Java Sample for UploadSiteHostedPictures

Options for adding pictures to an item (eBay SDK for .NET)

Using a Self-Hosted Picture

If a listing uses a self-hosted picture (except in the case of a multi-variation listing), the picture will be copied to eBay Picture Services (EPS) for use in on the Search Results page, as well as the View Item page.

Self-hosted pictures must meet the picture requirements.

Both the self-hosted URL and the EPS URL of the self-hosted picture are returned by GetItem in PictureDetails.ExtendedPictureDetails.PictureURLs.ExternalPictureURL (self-hosted URL) PictureDetails.ExtendedPictureDetails.PictureURLs.eBayPictureURL (EPS URL).

When you call ReviseItem or RelistItem, you can provide new self-hosted URLs in the PictureURL field. You can change the picture using ReviseItem if the listing has at least 12 hours left AND there have been no bids.

CMYK Color Format

Images using the CMYK color format are not allowed. If your listing uses self-hosted pictures with this format, you will not receive an error when creating the listing, but the image will not appear in the listing.

One way to identify images using the CMYK format is by using the identify command of the Image Magick Package.

For Example:

$ identify -format '%[colorspace]' image.jpg

To convert an image from CMYK to RGB, you can use tools such as PhotoShop or

Using a Stock Photo in an Item Listing

eBay provides stock catalog information, including stock photos, for commonly sold items. To include a stock photo and other stock product information (also called product details) in an item listing, specify the catalog product ID in your listing request, and then specify additional fields to configure the catalog data you want to use. A product's stock photo can be used only for items in new condition.

There are three main ways to find a catalog product ID:

Once you have identified a catalog product, you can include the product's stock photo in your listing by setting Item.ProductListingDetails.IncludeStockPhotoURL to true. If a stock photo is available, it is used at the top of the View Item page and in the Item Specifics section of the listing.

If you also include Item.PictureDetails.PictureURL, the stock photo only appears in the Item Specifics section of the listing. Other pictures you specify appear in a separate section of the listing. If you set IncludeStockPhotoURL to false, the stock photo does not appear in the listing at all. In GetItem and related calls, the URL of the stock photo will be returned in StockPhotoURL.

To use stock photo as the Gallery image, set Item.ProductListingDetails.IncludeStockPhotoURL and Item.ProductListingDetails.UseStockPhotoURLAsGallery to true or use the first image passed in PictureURL as the Gallery image

Also see Using an eBay Stock Photo as a Gallery Picture.

For additional information, see the following topics.

How eBay Determines Which Image To Use


Associating Pictures with an Item

When defining a new item, use fields in Item.PictureDetails for pictures. The PictureDetails.PictureURL field specifies a URL for a picture. The PictureDetails.PhotoDisplay field specifies special effects.

A listing call such as AddItem will associate pictures with a listing. See the Call Reference for AddItem, which includes descriptions of the PhotoDisplayCodeType values.

AddItem Call Reference

When you make a call such as AddItem, eBay parses the values you submit in the following Item.PictureDetails fields: PictureURL and GalleryURL. eBay determines which pictures are hosted on the eBay site and which are self-hosted.

How eBay Determines Which Image To Use


Using PictureURL and GalleryURL

Using eBay Picture Service vs. Self-Hosted Pictures

Retrieving Picture Data

Data for pictures is stored in the Item.PictureDetails node. The GetItem call returns the picture data that was used when the item was listed.

An application should check the Item.PictureDetails container to determine picture data. If this element returns a null value, there are no pictures associated with the item. If picture data is returned, the same child elements of Item.PictureDetails are used at listing time. (See Associating Pictures with an Item.)