The Catalog Product (Pre-filled Item) API

Instead of filling in well-known Item Specifics for every listing, you can start with stock listing information (a product) that is similar to your item, and then add your own information to customize the listing description. The product contains partially filled out Item Specifics and other descriptive information—collectively known as Pre-filled Item Information. Using Pre-filled Item Information gives sellers a faster way to fill in Item Specifics and other information about an item.

To list with Pre-filled Item Information, you begin by obtaining an eBay catalog product ID. See Calls You Use to List with Pre-filled Item Information for information about retrieving eBay catalog product IDs.

The Pre-filled Item Information functionality is based on the Item Specifics functionality (see Summary of Listing the Standard Way with Item Specifics and Return Policies). This means that you should have a basic understanding of the Item Specifics API before you begin working with the Pre-filled Item Information API.

Summary of the Catalog Product Model

This section defines a number of terms that eBay uses to describe notions related to Pre-filled Item Information. It also illustrates the high-level elements of the Pre-filled Item Information model. You should already be familiar with the terminology related to Item Specifics (see Summary of the Attributes Model).

Product: A product is an entry in an eBay catalog that defines well-known information about particular kinds of items. An example of a product would be information about a particular edition of "My Favorite Movie: The Sequel" on DVD, identified by a specific UPC. Other editions of the same movie would have different UPC values, and would therefore be considered separate products. Each product consists of pre-filled Item Specifics, additional descriptive information, plus a stock photo (if available).

Note: For developers who are familiar with the details of the eBay attributes model: Products can provide the source for Type 1 and Type 2 characteristics in the attribute meta-data. See Determining Whether the User Can Choose an Attribute Value.

A product is not the same as an item. Products cannot be bought or sold; they merely describe well-known properties of particular kinds of items. A seller selects a product from a catalog and uses the data to populate some or all of a listing's Item Specifics. Thus, you can think of a product as an item prototype (or as Item Specifics that have already been partially filled in plus other descriptive information). A buyer can use a product finder to search for items whose Item Specifics match a product of interest.

See ProductType in the schema documentation for information about the object we use to represent catalog products.

Each product has a unique ID. In most cases, you must include this ID in your listing request in order to identify the product. (Certain categories offer other ways to identify products.)

For information on how to find products and how to include product IDs in your listing, see Calls You Use to List with Pre-filled Item Information.

Product family: A product family identifies a group of related products. For example, a movie called "My Favorite Movie: The Sequel" might be released on DVD, but there might be several editions of the DVD (e.g., in different languages) with different UPC values. All variations are part of the same product family ("My Favorite Movie: The Sequel" in the DVD format).

See ProductFamilyType in the schema documentation for information about the object we use to represent product families.

Catalog: A catalog is a database of product information. Currently, catalog content is available (enabled) for certain categories only. For information on how to determine which categories are catalog-enabled, see Calls You Use to List with Pre-filled Item Information. (There is no "catalog" object in the schema.)

Attribute: An attribute is an aspect or feature that distinguishes a particular type of item according to its category. On the eBay site, all Item Specifics fields are attributes. For example, in a book category, "Format" would be an attribute, and "Hardcover" might be the value you choose to assign to that attribute. See Summary of the Attributes Model.

When you list with Pre-filled Item Information, some or all of the attribute values are always pre-filled. That is, the user cannot choose a value. For example, the length of a particular movie might be a value that the seller can never specify or change. This well-known data is defined in the eBay database (which could be a product catalog). Certain other attribute values might be conditionally pre-filled (i.e., not user-selectable unless the value is currently unknown). For example, an independent film's rating might not be available in the eBay database yet, so the seller would be able to specify the rating if desired.

Note: For developers who are familiar with the lower-level details of the eBay attributes model: Pre-filled attributes are identified by Type 1 and Type 2 characteristics in the attribute meta-data. Some attributes that are currently Type 0 may become Type 1 or Type 2 attributes in the future. See Determining Whether the User Can Choose an Attribute Value.

For information on how to determine a product's pre-filled and selectable attributes, see Calls You Use to List with Pre-filled Item Information.

Product Search: In order to list an item based on a stock product, you first need to find the stock product. We offer a number of ways to search for stock product content:

Product search page: In this type of search (also called a single-attribute search), you create a simple query that consists of one attribute (with a value). This retrieves a single product or a very short list of search results to choose from. Some products are fairly easy to find based on a single attribute. For example, in Consumer Electronics categories (Digital Cameras, Cell Phones, and PDAs), you can specify a unique (or nearly unique) identifier, like a part number. In Media categories (Books, DVDs & Movies, Music, and Video Games), you can specify a descriptive name, like a title.
Product finder: A product finder is a set of attributes that you configure to form a complex query. In the Sell Your Item flow, this is a complex query against the eBay product catalog. Currently, this type of search is available in Consumer Electronics categories only. In this type of search, you specify values for multiple attributes, like Brand and Resolution (i.e., number of megapixels). This retrieves a list of matching products.

This approach is useful when the user does not know the part number, or a product does not have a single, distinguishing feature that is easy to search on. For example, searching for a digital camera based solely on the brand would likely yield far too many results to be useful. Searching on the brand, product line, and resolution will retrieve a much shorter list of results.

External product identifier: In Media categories (Books, DVDs & Movies, Music, and Video Games) you can also take a shortcut and use ExternalProductID to specify an ISBN, EAN, or UPC in your AddItemCall request directly, without searching for a matching product. Similarly, in Event Ticket categories you can use ExternalProductID to specify the event name, venue, and time without searching for a matching product. eBay will then perform the search for you. If we find a single matching product, we will add all of its stock information to your listing. If we find multiple matches, we will return a short list of product IDs to choose from.

Implement the ICategoryCSProvider interface or use the GetCategory2CSCall to determine which categories support product search pages and which ones support Product Finders. For every catalog-enabled category, at least one of these methods is offered. In some cases, both are offered. See Calls You Use to List with Pre-filled Item Information for more information.

Note: GetCategory2CSCall does not return information about the availability of the external product identifier method. Instead, you can simply use this guideline: If a Media category (Books, DVDs & Movies, Music, and Video Games) is catalog-enabled, it will support this external product identifier method.

When you search for a product, eBay returns a brief summary of the product's pre-filled attributes as defined in the catalog. The API defines objects that model this information.

Figure 18-6 illustrates the relationship between product information (including product attributes) that is used in a listing and product data that is found as a result of a catalog search. The search data gives you a product ID. You use that product ID as a key when you list an item, but you do not specify the pre-filled attributes (although you can specify attributes that were not pre-filled). When you retrieve the item, all the pre-filled attributes and any other attributes you specified are returned.

Figure 18-6 Product Data in a Listing and Product Characteristics in a Catalog

Characteristic Set: For a basic definition of characteristic sets, see Summary of the Attributes Model. Catalog content (i.e., product information) is enabled for certain categories only. The list of catalog-enabled categories is a subset of the categories that are mapped to characteristic sets. Thus, catalog-enabled categories are always attributes-enabled as well.

A product has a number of attributes that are pre-filled from a catalog. In addition, it may have other characteristics that are not pre-filled. When you create a listing, you can select values for these other attributes based on the characteristic set meta data. In the API , the meta-data is defined in raw XML rather than in the schema.

The table below summarizes the basic product and attribute data you need when listing with Pre-filled Item Information. The sample values shown in the table are not necessarily valid values on the Production site. They are intended to illustrate such values only. See Calls You Use to List with Pre-filled Item Information for a summary of the API calls you use to obtain this data and to create listings with this data.

Table 18-2 Data Required to List with Pre-filled Item Information 

Field	Required	Sample Value	Display Name	Notes
ProductListingDetails	Y/N	56259:2:1055:3653535 891:35123931:d5779 702842281221998200 103508894:1:1:1:10 56041020	Product ID	Use this to specify an eBay catalog product ID and optional stock information. Either this property or ExternalProductID is required (but not both)
ExternalProductID	Y/N	0807281948 ISBN	ISBN	Use this to specify an ISBN, EAN, UPC, ticket keywords, or eBay product ID. Only applicable in Media and Event Ticket categories. Either this property or ProductListingDetails is required (but not both)
AttributeSet.attributeSetID	Y/N	1388	Fiction & Nonfiction Books	Same value as the characteristic set ID. Only required when optional attributes are specified.
Attribute.AttributeID	Y/N	23713	Subject	Required when an optional attribute is specified.
ValueList.ValueID	Y/N	23778	Computers & Internet	Required if the attribute value is a positive number. If the ID is -3 or -6 (Other), use ValueLiteral to specify the value that the user entered
ValueList.ValueLiteral	Y/N	Computers & Internet	Computers & Internet	Required if ValueID is -6.

Calls You Use to List with Pre-filled Item Information

Due to the large amount of catalog data available and changes that are made as new products become available, it is not practical for you to hard-code eBay catalog information in your application. Instead, the eBay Platform offers you a set of data-driven calls that let you import, update, and render catalog product information dynamically. This section briefly compares the ways in which you can implement the Pre-filled Item Information listing option and summarizes the calls you would use.

In categories that support Pre-filled Item Information, you can use identifiers like ISBN, EAN, UPC, or manufacturer's part number (depending on the category) or common keywords like Title or Brand to search for stock listing information from a catalog. Once you have chosen a product to start with, you can select content, including stock photos, descriptions, and additional information (like song lists, film descriptions, etc.) that will be added to your listing automatically.

In a few categories (specifically, Media categories and Event Ticket categories), we provide you with a shortcut that lets you bypass the search step (thereby saving you several calls). You can specify an ISBN, EAN, UPC, ticket keywords, or eBay product ID when you add an item, and eBay will perform the catalog search for you, find the matching product, and use it in the listing (along with the stock photo and any other information that is available).

Specifying an External Product ID or Catalog Product ID to Pre-fill Item Information

If you are listing with Pre-filled Item Information in Books, DVD & Movies, Music, Video Games, or Event Ticket categories, you can pass an industry-standard identifier in AddItemCall instead of passing an eBay product ID. In this case, eBay will determine the stock product to use for the listing.

To support listing in this manner, use the following calls and the Attributes Library, which aggregates and simplifies certain aspects of this workflow.

Figure 18-7 Listing with a UPC, EAN, ISBN, or Ticket Keywords

GetCategoriesCall and ICategoryCSProvider (or GetCategory2CSCall)

The category data retrieval calls return data that does not change very often, so you only need to execute them once on any given day that your application is in use. Store the results locally and use the same data for the rest of the day.

Use GetCategoriesCall to retrieve the eBay category hierarchy.
Use the ICategoryCSProvider interface (instead of using GetCategory2CSCall directly) to supply IAttributesMaster with the mappings needed to convert category IDs to characteristic set IDs. Implement this interface as appropriate for your application's data storage needs. The CategoryCSDownloader class is included in the Attributes Library as a sample implementation of the ICategoryCSProvider interface. The CategoryCSDownloader class downloads the data needed to convert category IDs to characteristic set IDs directly from eBay and caches the data in memory. See Retrieving Category-to-Meta-Data Mappings.
Later, when the user selects a Books, DVD & Movies, Music, Video Games, or Event Tickets category that is catalog-enabled, give the user the option to list their item by using an ISBN, EAN, or UPC value or ticket keywords (event name, venue, and date/time).
AddItemCall with ExternalProductID

Use AddItemCall to list the item. See Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date).

Specify an ISBN, EAN, or UPC value or ticket keywords using the ExternalProductID property on AddItemCall. (If you already know the eBay product ID, you can specify that value instead.)
Optionally, fill in the Item.Description field with free text. This is optional when you use ExternalProductID because additional stock information from the product will automatically be used.
Optionally, fill in attributes that were not pre-filled (e.g., the new/used condition of the book).
Fill in other required fields for the listing (e.g., payment methods) and specify optional listing enhancements (e.g., BoldTitle) as needed.

When you submit the listing, eBay searches a product database (a catalog) for a product that matches the ISBN, EAN, UPC, or ticket keywords (or eBay product ID) you passed in.

If a single matching product is found, the item will be listed with that product's Pre-filled Item Information, including the product's stock photo and other stock information. The stock photo will be used at the top of the View Item page and in the Item Specifics section of the listing. It will also be used as the Gallery image if you choose to list your item in the gallery (see Using an eBay Stock Photo as a Gallery Picture).
If more than one match is found, the call returns an error (indicating that too many products were found) and a list of product IDs for the products that matched on the ISBN, EAN, or UPC you passed in.

Before using AddItemCall, you can also use GetItemRecommendationsCall to retrieve eBay pricing data to help the seller choose prices for listings that include Pre-filled Item Information. GetItemRecommendationsCall can also return other tips to improve a listing. See Getting Recommendations to Improve a Listing for additional information.

IAttributesXmlProvider and IAttributesXslProvider (or GetProductSellingPagesCall and GetAttributesXSLCall)

If the AddItemCall response returns an error with a list of product IDs, retrieve the current Pre-filled Item Information for each product so that you can determine which one most closely matches your listing.

Instead of using GetProductSellingPagesCall directly, use the IAttributesXmlProvider interface to supply IAttributesMaster with the characteristic set XML source that contains all the current Pre-filled Item Information for the product. Implement this interface as appropriate for your application's data storage needs. The AttributesXmlDownloader class is included in the Attributes Library as a sample implementation of the IAttributesXmlProvider interface. The AttributesXmlDownloader class downloads the product selling page XML directly from eBay and caches the data in memory.See Retrieving a Product's Item Specifics. (If you prefer to retrieve a list of products that the user can choose from instead, see Searching for a Stock Product to Pre-fill Item Information).
Instead of using GetAttributesXSLCall directly, use the IAttributesXslProvider interface to supply IAttributesMaster with the XSL stylesheet text to use for easily rendering stock product information in a user interface. Implement this interface as appropriate for your application's data storage needs. The AttributesXslDownloader class is included in the Attributes Library as a sample implementation of the IAttributesXslProvider interface. The AttributesXslDownloader class downloads the XSL stylesheet text from eBay and caches it in memory. See Retrieving the Item Specifics SYI XSL Stylesheet.

One way to modify the look and feel of the product's Item Specifics form is to apply another XSL stylesheet that generates a new XML document with customized (or patched) presentation instructions. Unlike the main stylesheet, which transforms the XML to HTML, the patching stylesheet transforms the XML to XML. The eBay SDK for .NET uses a default patching stylesheet. You can replace this stylesheet by replacing the eBay.Service.SDK.Attribute\Resources\Attributes_Style.xsl file. For examples of patching stylesheets, please see Working with Attribute XSL Stylesheets.

Once you have selected the best match, execute AddItemCall again, and specify the ID of the desired product.

Searching for a Stock Product to Pre-fill Item Information

The most common way to list with Pre-filled Item Information is to first search for a product that is similar to your item, and then pass its ID and optional stock information as input to AddItemCall. When you list an item with Pre-filled Item Information, you only pass in attributes that are not pre-filled. eBay generates all other attributes and values for you at listing time.

To determine which attributes are pre-filled, you implement IAttributesXmlProvider, which wraps GetProductSellingPagesCall. GetProductSellingPagesCall is very similar to GetAttributesCSCall, but it retrieves pre-filled information for a particular product in addition to standard Item Specifics. In order to be able to use GetProductSellingPagesCall, you need to pass in the ID of a product that is similar to the item you are listing.

To find a product ID, you search a catalog of products that are applicable for the category of interest. As described in Summary of the Catalog Product Model, some categories support searching on a single key attribute, some support searching by using a product finder (a complex query), and some support both.

To support listing in this manner, use the following calls and the Attributes Library, which aggregates and simplifies this workflow.

Figure 18-8 Searching for and Listing with a Product ID

GetCategoriesCall and ICategoryCSProvider (or GetCategory2CSCall)

The category data retrieval calls return data that does not change very often, so you only need to execute them once on any given day that your application is in use. Store the results locally and use the same data for the rest of the day.

Use GetCategoriesCall to retrieve the eBay category hierarchy.
Instead of using GetCategory2CSCall directly, use the ICategoryCSProvider interface to supply IAttributesMaster (see below) with the mappings needed to convert category IDs to characteristic set IDs and product finder IDs. Implement this interface as appropriate for your application's data storage needs. The CategoryCSDownloader class is included in the Attributes Library as a sample implementation of the ICategoryCSProvider interface. The CategoryCSDownloader class downloads the data needed to convert category IDs to characteristic set IDs and product finder IDs directly from eBay and caches the data in memory. Use this data to determine which categories are catalog-enabled (i.e., support Pre-filled Item Information) and the available search methods. If the Category.CatalogEnabled property is set to true, it indicates that the category supports Pre-filled Item Information. If the Category.ProductSearchPageAvailable property is set to true, the category supports simple catalog queries (single-attribute product search pages). If the Category.ProductFinderAvailable property is set to true, the category supports complex catalog queries (Product Finders). Some categories support both query formats. See Retrieving Category-to-Meta-Data Mappings.
GetProductSearchPageCall

Use GetProductSearchPageCall to retrieve a set of attributes that you can configure to form simple (single-attribute) queries for catalog products. For example, if you want to search for a book, the response will indicate that you can search on Title, Author, or ISBN (but not all three). See Retrieving Product Search Page Meta-Data.

This call returns data that does not change very often. You can retrieve search page data for a specified list of characteristic sets or for all characteristic sets (defined for a particular eBay site). Typically, you execute this call once a day, store the results locally, and then use the same data for the rest of the day.

The response only returns the list of search attributes you use to form the query. The call does not perform an actual product search.

Figure 18-9 A Product Search Page on an eBay Web Site


GetProductFinderCall and GetProductFinderXSLCall
Use GetProductFinderCall to retrieve a set of attributes that you can configure to form complex queries for catalog products. A complex query consists of one or more attributes. The response only specifies the attributes you can search against. The call does not perform an actual product search. See Retrieving Product Finder Meta-Data.
Use GetProductFinderXSLCall to retrieve eBay's Product Finder XSL stylesheet, and then use the stylesheet to transform the GetProductFinderCall response into an HTML form that a user can fill in. You can render this kind of form in a Web-based or Windows desktop client application. See Retrieving the Product Finder XSL Stylesheet and Working with the Product Finder XSL Stylesheet.

The product finder meta-data retrieval calls return data that does not change very often, so you only need to execute them once on any given day that your application is in use. Store the results locally and use the same data for the rest of the day.

Figure 18-10 A Product Finder Rendered Using the Product Finder XSL


GetProductSearchResultsCall and, if necessary, GetProductFamilyMembersCall
Use GetProductSearchResultsCall to search a catalog for a product that is very similar to yours (e.g., a particular movie, where the title, lead actors, etc. are already filled in), and take note of its product ID. The response contains a list of all products that matched the search criteria. See Searching for Catalog Products.
If the quantity of matching versions of a given product exceeds a maximum limit that you specify in the GetProductSearchResultsCall, use GetProductFinderCall to retrieve all versions of that product. See Retrieving All Members of a Product Family.

Figure 18-11 shows a set of product search results an eBay Web site.

Figure 18-11 Product Search Results on an eBay Web Site



Figure 18-12 shows retrieving all versions of a particular product on the eBay Web site.

Figure 18-12 Retrieving All Versions of a Product



To support the ability to search the eBay catalog, your application needs to be connected to the Internet. You need to use GetProductSearchResultsCall (and, if necessary, GetProductFamilyMembersCall) each time you want to search for catalog content. You cannot download and store eBay's catalog data to conduct searches locally later.

To reduce the number of calls you need to make, these calls support batch searches. That is, you can use a single call to search for products that match a number of items. This is useful for sellers who are submitting many listings at the same time.

IAttributesXmlProvider and IAttributesXslProvider (or GetProductSellingPagesCall and GetAttributesXSLCall)

Once the seller has selected a product ID, you need to retrieve all the current Pre-filled Item Information for that product. If you frequently list items based on the same product, you can store a product's ID locally. However, be aware that product IDs can change, so you should be prepared to update your list of product IDs regularly (particularly when you receive warnings that your product IDs are out of date).

Instead of using GetProductSellingPagesCall directly, use the IAttributesXmlProvider interface to supply IAttributesMaster with the characteristic set XML source that contains all the current Pre-filled Item Information for the product. Implement this interface as appropriate for your application's data storage needs. The AttributesXmlDownloader class is included in the Attributes Library as a sample implementation of the IAttributesXmlProvider interface. The AttributesXmlDownloader class downloads the product selling page XML directly from eBay and caches the data in memory. This call supports batch retrievals. That is, you can use a single call to retrieve data for multiple products at once. See Retrieving a Product's Item Specifics.
Instead of using GetAttributesXSLCall directly, use the IAttributesXslProvider interface to supply IAttributesMaster with the XSL stylesheet text to use for easily rendering stock product information in a user interface. Implement this interface as appropriate for your application's data storage needs. The AttributesXslDownloader class is included in the Attributes Library as a sample implementation of the IAttributesXslProvider interface. The AttributesXslDownloader class downloads the XSL stylesheet text from eBay and caches it in memory. See Retrieving the Item Specifics SYI XSL Stylesheet.

The product meta-data downloaders return data that does not change very often, so you only need to execute them once on any given day that your application is in use. Store the results locally and use the same data for the rest of the day.

One way to modify the look and feel of the product's Item Specifics form is to apply another XSL stylesheet that generates a new XML document with customized (or patched) presentation instructions. Unlike the main stylesheet, which transforms the XML to HTML, the patching stylesheet transforms the XML to XML. The eBay SDK for .NET uses a default patching stylesheet. You can replace this stylesheet by replacing the eBay.Service.SDK.Attribute\Resources\Attributes_Style.xsl file. For examples of patching stylesheets, please see Working with Attribute XSL Stylesheets.

Figure 18-13 GetProductSellingPages XML Transformed into HTML


IAttributesMaster

This interface defines the core functionality for managing all attributes-related operations in the eBay SDK for .NET. In addition, the AttributesMaster class is included in the Attributes Library as a sample implementation of the IAttributesMaster interface.

Use the RenderHtmlForCategories() method to render product information for the category or categories in which the user wants to list the item. This renders the Item Specifics form in an HTML-based user interface.
When user enters Item Specifics data in an HTML form and submits the form, the form generates HTML POST data that reflects the user's selections. Use the RenderHtmlForPostback() method to render the selected Item Specifics in HTML (i.e., to update the form).
After the user selects and submits attributes and values for each category, use the NameValuesToAttributeSets() method to parse the name/value pairs in the generated HTTP query string and convert the data to standard attribute set objects for each category.
Optionally, use the validate() method to validate the attribute sets. This is used to validate selected attribute values as needed, based on validation rules supplied in the attribute meta-data. This method returns an ErrorSetCollection object. If any errors are found, pass the errors in the RenderHtml() or RenderHtmlForPostback() method on IAttributesMaster to generate the Item Specifics HTML form with error hints. For example, a typical error might be that required attributes are missing.

Use the XmlProvider, XslProvider, and CategoryCSProvider properties defined on IAttributesMaster to specify the source you want to use for retrieving attributes meta-data. The source can be one of the sample downloader classes provided in the eBay SDK for .NET or your own implementations. See Working with Attribute XSL Stylesheets for additional information.

AddItemCall with ProductListingDetails

Use AddItemCall to list the item with Pre-filled Item Information. See Listing with Item Specifics and Catalog Data.

Instead of specifying all the Item Specifics for your item, use the ProductListingDetails property to specify a product ID and a flag to indicate whether you want to use the Pre-filled Item Information from that product.
Optionally, specify flags to indicate that you want to use the product's stock photo in your listing and/or as your Gallery image (instead of specifying PictureURL and/or GalleryURL) (see Using an eBay Stock Photo as a Gallery Picture).
Optionally, if some of the product's pre-filled Item Specifics are editable, use the AttributeSetArray property to fill them in. Also fill in other attributes that were not pre-filled (e.g., the new/used condition of the DVD).
Fill in the Description field with free text. This is optional if you choose to include additional stock information from the product. Otherwise, the description is required.
Fill in other required fields and specify optional listing enhancements (e.g., BoldTitle) as needed.