Working with Pictures in an Item Listing
To associate a picture with an item, specify the picture's URL in the item definition.
All pictures must meet the picture requirements.
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 12. On the US and Canada eBay Motors sites (for all vehicle listings) a listing can contain up to 24 pictures, with the first 12 being free, and then each additional picture incurring a fee of $0.15 each.
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.
You can include up to 12 pictures in a listing for no charge. Up to 24 pictures can be added for motor vehicle listings, but the seller is charged $0.15 for each picture beyond the first 12. 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 12 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
.NET Sample in C# for UploadSiteHostedPictures
PHP 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.
$ identify -format '%[colorspace]' image.jpg
To convert an image from CMYK to RGB, you can use tools such as PhotoShop or cmyk2rgb.com.
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:
- If your item has a UPC, ISBN, EAN, MPN, or you're listing in event ticket categories, you can use Item.ProductListingDetails to specify an industry-standard value (e.g., an ISBN) or ticket keywords in your listing request, and eBay will use that information to look for a matching product in eBay's catalogs for you.
- If you know of an existing listing on the eBay site that was listed with the product information you want to use, pass the listing's item ID in GetItem with a detail level of
ReturnAll. This will retrieve the EPID (eBay Product ID) that was used in the listing. Then pass the EPID in Item.ProductListingDetails.ProductReferenceID.
- To search for an EPID, use FindProducts in the Shopping API. Then pass the EPID in Item.ProductListingDetails.ProductReferenceID in your listing request.
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
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.
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
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.)