Retrieving a Product's Item Specifics

On the eBay Web site, the user selects a product by clicking a Sell One Like This button on the search results page (or on the page that lists all products in one particular family). The eBay site then displays the Title & Description page. Many of the Item Specifics are pre-filled based on the product the user selected. A few attributes that are expected to vary or that do not yet have pre-filled values may still be editable.

Figure 21-6 Pre-filled Item Specifics on an eBay Web Site

Use GetProductSellingPagesCall to retrieve stock information about a product, including Item Specifics. The data lets you render the equivalent of the Item Specifics portion of the Title & Description page. This call gives you a dynamic and scalable way to import, update, and render pre-filled and editable Item Specifics for a catalog product. You should not hard-code product meta-data in your application.

GetProductSellingPagesCall returns the product Item Specifics XML for one or more products in a single ProductSellingPagesData object as a string. The attributes and values are not defined in the WSDL (i.e., there are no code lists that describe the meta-data), and therefore they will not be converted into objects or modules by your SOAP client.

The input to GetProductSellingPagesCall comes from GetProductSearchResultsCall (or GetProductFamilyMembersCall). You use the response as input to calls related to adding, revising, and relisting items (the AddItem family of calls).

GetProductSellingPagesCall returns the same characteristics meta-data as GetAttributesCSCall, with these differences:

The data is returned as a string in the ProductSellingPagesData property (instead of AttributeData).
In the XML string, the data for each selling page is embedded in a Product container node that contains additional information about the product (e.g., the stock photo URL).
The meta-data (Characteristics container) still includes all possible values for Type 0 and Type 2 attributes (even if the Type 2 attributes are pre-filled), but the default values (AttributeSet container) specifies default and pre-filled values for the attributes.

You can use the Item Specifics SYI XSL stylesheet to render the XML returned from GetProductSellingPagesCall. See Working with Attribute XSL Stylesheets. If you are using the Attributes Library, the AttributesMaster class provides helper methods that you can use to render the XML and get the attributes that the user selects. In this case, you do not need to write code to handle the stylesheet yourself. If you provide your own implementation of the AttributesMaster class, you will need to understand how to work with the XSL stylesheet.

If you choose not to use the XSL stylesheet, or if your application design requires you to understand the details of the product selling page meta-data, see Attribute and Product Finder Content Models for additional information about the XML returned in the ProductSellingPagesData property.

This section describes the following process:

Prerequisites

Step 1:  Indicate the Product Data to Return

Step 2:  Make the API Call

Step 3:  Maintain the Product XML

Step 4:  Next Steps

Prerequisites

You need a current product ID to pass as input to this call. Typically, you get the product ID as a result of executing GetProductSearchResultsCall or GetProductFamilyMembersCall. In some cases, the product ID might be returned as a result of executing AddItemCall (see Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID)).

Step 1: Indicate the Product Data to Return

GetProductSellingPagesCall lets you retrieve information about multiple products (i.e., the call supports batch requests). This may be useful for users who are listing several different items at the same time. If you use a data-source provider like the AttributesXmlDownloader class instead, you can design the GetMultipleCSXmlText( ) method to retrieve data for multiple products as well.

When creating the GetProductSellingPagesCall request, set the ProductList property. For each product, specify the ID of the product whose stock information you are retrieving. Also specify the characteristic set and its version value.

If you use a data-source provider class like AttributesXmlDownloader instead of using GetProductSellingPagesCall directly, the Attributes Library includes a wrapper class called AttributeSet.This extends the AttributeSetType object and adds functionality to handle catalog product data as part of the same object. To specify that you want to retrieve product data rather than standard Item Specifics, set AttributeSet.ProductID to the product ID the user selected. Then pass in the collection of AttributeSet objects as an argument to the GetMultipleCSXmlText( ) method.

In addition, you need to specify the context in which the call is being executed—selling, revising, or re-listing. This will imply certain server-side validation rules when eBay processes the request. Set the UseCase property on GetProductSellingPagesCall to make sure you retrieve the appropriate version of product information and attribute meta-data when you are listing, revising, or re-listing an item with Pre-filled Item Information. The ProductUseCase code list defines the possible use cases:

Use the AddItem code when you are executing this call before adding an item. This causes the response to return the latest product ID, attribute meta-data, and stock information for the product. This is important in case the product ID has changed since you originally retrieved it.
Use the ReviseItem code before revising an item. This causes the response to return the product ID, attribute data, and other data that is (or was) associated with the version of the product you passed in. This is useful in case the product ID or associated data has changed in the system since the item was originally listed. When revising an item, this helps you make changes that are consistent with the original listing.
Use the RelistItem code before re-listing an item. This causes the response to include the latest product ID and other information in the system. When you re-list an item, you need to use the latest version of the product and related meta-data.

GetProductSellingPages summarizes the main input fields that are applicable for this call.

Step 2: Make the API Call

Making the API call with the Attributes Library entails specifying the product you want to retrieve by setting AttributeSet.ProductId to the product ID the user selected. Then pass in the array of AttributeSet objects as an argument to the GetMultipleCSXmlText( ) method on the data-source provider that implements the IAttributesXmlDownloader interface. This retrieves the product data as an XML string and creates an XMLDocument object that is easier to work with. If you create your own data-source provider class that implements the IAttributesXmlProvider interface, your class would call the GetProductSellingPages( ) method defined on the GetProductSellingPagesCall class to retrieve the XML string.GetProductSellingPagesCall returns a ProductSellingPagesData object containing a string that specifies the product and Item Specifics XML for each product ID that you requested. The data is returned as raw XML so that you can more easily apply the Item Specifics XSL to render it.

Table 21-1 GetProductSellingPagesCall Return Fields 

Return Fields	Type/Code List	Purpose
ProductSellingPagesData	string	An XML string containing one or more product definitions (one for each product ID requested) along with related meta-data. For each product, the XML specifies the pre-filled values of each attribute, the possible values of attributes that are not pre-filled, the logic for presenting the attributes to a user, and rules for validating the user's selections. The meta-data format is based on the format of the AttributeData string returned by GetAttributesCSCall. Product and attribute information is nested within a set of Product tags. The product-specific data is merged into the attribute data so that the same XSL stylesheet can render both standard Item Specifics and pre-filled Item Specifics.

For each product, the raw XML contains a ProductInfo node that contains a URL for the product's stock photo, a URL for linking to a preview of the Pre-filled Item Information, and copyright content that your application should present to users (see Figure 21-6). This represents the product information that can be included in the listing. (In your application, you should give the user options to include the stock photo in the listing, to use the stock photo as the Gallery image, and to include Pre-filled Item Information in the listing.)

The XML also specifies the set of attributes and characteristics (Item Specifics) that are applicable for the product. That is, if the product is a DVD, the call would return the DVDs attribute meta-data and appropriate default attributes and values. For example, if the selected movie product is a comedy, the AttributeSet node would specify the default value for the Genre attribute as "Comedy" and it would specify the catalog system as the source of the value (AttributeSet.Attribute.source = "1").

The XML format of the Item Specifics portion of the response is consistent with the format of the response returned from calls to GetAttributesCSCall (although the data may be different, due to the pre-filled information). This means an application with a graphical user interface can use a stylesheet returned from GetAttributesXSLCall or a data-source provider that implements IAttributesXslProvider to render this part of the content. See Working with Attribute XSL Stylesheets.

If you are not using the XSL, attribute values that can be selected or overridden by the user should be presented as editable, in the same manner as any Type 0 or selectable (i.e., not pre-filled) Type 2 characteristics (see Determining Whether the User Can Choose an Attribute Value). For example, a movie's Condition attribute is never read-only, but if the Genre attribute is pre-filled by the catalog, it might be considered read-only (because the same movie might always be considered a comedy, no matter who the seller is). Some product attribute values that pre-filled by the catalog may still be overridable. For example, if a particular model of a laptop normally comes with a certain amount of memory, but the user has added more memory, the user should be able to override the value.

You can store the response XML in order to present the product information to the seller so that they can review and confirm the product, choose optional Item Specifics, and choose to include the stock photo and other information. However, in general you should assume that a product 's definition in the catalog can change periodically.

For each product, the call returns one full characteristic set and (for certain eBay sites) zero or more site-wide characteristic sets. The XML structure is the same for each, but site-wide characteristic sets also specify an additional type XML attribute to indicate that they are site-wide. You can use the Item Specifics SYI XSL stylesheet to render the site-wide characteristics alongside the category-specific characteristics.

Step 3: Maintain the Product XML

As each product you retrieve is only applicable for one particular kind of item, you cannot reuse the same product information when listing other types of items. Also, product IDs can change periodically. Therefore, it is often not practical to reuse the same GetProductSellingPagesCall response for listings that are created on different days.

GetProductSellingPagesCall also does not support versioning. For example, you cannot specify the version of a product to find out if the data has changed since you last retrieved that product.

You should each time you need to list a new product. If you frequently list the same type of product, you can try to use the same product ID in the AddItemCall request for each subsequent identical item. If the product ID changes, the AddItemCall request will return an error indicating that the product ID is not valid. In that case, you would need to determine the correct product ID and then again to retrieve the latest product details.

Step 4: Next Steps

After you have retrieved the product details and the user has chosen optional Item Specifics and other information, you can use the selected data in a listing. See Listing with Item Specifics and Catalog Data.