The Attributes (Item Specifics & Return Policy) API

The Attributes API provides a standardized way to describe different aspects of a listing, such as Item Specifics (part of the item's basic description) or an item's return policy (part of the listing's payment and shipping instructions). This section describes the attributes model and the calls you use to retrieve attributes meta-data and to list with Item Specifics. The Attributes Library wraps the Item Specifics classes, and makes supporting Item Specifics even easier for developers. Therefore, you only need to read this section if you are modifying the Attributes Library sample classes or providing your own implementations of the Attributes Library interfaces.

Summary of the Attributes Model

In the API, Item Specifics and return policies are implemented by means of the eBay attributes model. For example, in book categories, the Format and Publication Year fields on eBay's Title & Description page are implemented as eBay attributes.

This section defines a number of terms that eBay uses to describe notions related to Item Specifics and other features that use the attributes model, and it illustrates the high-level elements of the attributes model.

Attribute: An attribute is an aspect or feature that distinguishes a particular type of item according to its category. On the eBay site, Item Specifics fields and return policy fields are implemented as 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. In most categories, the use of attributes is optional. A few categories (e.g., US Real Estate) require a seller to fill in values for Item Specifics that are marked as required.

In the API, most (non-attribute) objects model specific business notions (e.g., Currency) or specific meta-data about the request or response itself (e.g., TotalNumberOfPages). The meaning of these objects remains constant regardless of the category in which an item is listed. For example, to specify an item's currency, you assign a value to the Item.Currency property.

Item Specifics and return policies are modeled differently: Instead of defining category-specific properties for Format or Publication Year, eBay defines a generic Attribute property (AttributeType) for these fields. The business intent of the attribute (i.e., that it represents a book's format rather than, say, a ticket's event type) is specified in the attribute object's data.

Another difference between attributes and other input fields is that when you list an item with Item Specifics, you identify each attribute by specifying a numeric ID rather than a literal name. For example, you cannot assign "Hardcover" to a Format property on the item (no such property exists). Instead, you would look up the ID of the Format attribute and assign that ID to a generic Attribute.AttributeID property (i.e., Item.AttributeSetArray.Attribute.AttributeID). Using IDs makes it easier for applications to differentiate between attributes with similar literal names, look up attributes programmatically, and provide support for localization. Later sections in this guide describe how to determine attribute IDs.

The attributes model promotes flexibility and reusability, freeing you from the need to define separate Item classes or modules in your application to handle differences between every category. That is, it allows you to use the same Item model regardless of whether you are listing a book or an airplane.

Note: Conceptually, this data-driven approach is similar to the approach used in the error model. That is, the schema does not define "invalid date-range" errors and "user ID not found" errors. Instead, the same generic Errors construct is used for all application-level errors, regardless of the nature of the error.

See AttributeType in the schema documentation for information about the object that is used to represent attributes. In the eBay SDK for Java, the Attributes Library defines an Attribute class that extends AttributeType and provides additional functionality.

Value: An attribute can be associated with a single value, such as "Concerts" (for the Event Type attribute of a ticket), or with multiple values, such as "Microphone" and "Phone Capability" (for the Features attribute of a PDA). Some attributes have predefined lists of values (i.e., Value properties). For example, a book's Format attribute would have predefined values like "Hardcover", "Softcover", and other standard values. Each value has an ID (i.e., a Value.ValueID property). When using predefined values in the listing, you specify the value IDs instead of literal strings. (Value IDs are not necessarily unique. For example, if two different attributes each have an "Other" option, the value ID for "Other" will generally the same for both attributes.)

See ValType in the schema documentation for information about attribute value properties. In the eBay SDK for Java, the Attributes Library defines a Value class that extends ValType and provides additional functionality.

AttributeSet: An attribute set is a list of attributes and values that have been filled in for an item. That is, an attribute set corresponds to the complete set of Item Specifics for an item. Each attribute set has an ID, which is unique across all eBay sites. For information on how to determine the available attribute set IDs for a given category, see Calls You Use to List with Item Specifics and Return Policies.

See AttributeSetType in the schema documentation for information about the properties that are used to represent attribute sets. In the eBay SDK for Java, the Attributes Library defines an AttributeSet class that extends AttributeSetType and provides additional functionality.

Figure 18-2 An AttributeSet as a Property of an Item

The table below summarizes the basic attribute data you need when listing an item the standard way with Item Specifics. See Calls You Use to List with Item Specifics and Return Policies for a summary of the API calls you use to obtain this data.

Table 18-1 Data You Use to List an Item with Item Specifics 

Field	Required	Sample Value	Display Name	Notes
AttributeSet.AttributeSetID	Y	1388	Fiction & Nonfiction Books	Same value as the characteristic set ID. Always required when attributes are specified.
Attribute.AttributeID	Y	23713	Subject	Always required when the attribute is specified.
ValueList.ValueID	Y/N	23778	Computers & Internet	Use this to specify the value ID when the user selects a value that is predefined by eBay. See Attribute Elements. If the value ID is -3 (arbitrary string) or -6 (Other), use ValueLiteral to specify the value that the user entered.
ValueList.ValueLiteral	Y/N	Computers & Internet	Computers & Internet	Use this to fill in the user's free-text value if ValueID is -3 or -6. (Otherwise, eBay treats the attribute as unspecified.) Don't use this when the user selects a value that is predefined by eBay.

Characteristic: A characteristic is the specification of an attribute and its meta-data. The meta-data specifies all the possible values of the attribute and the logic for using and presenting the attribute.

For example, in a Books category, the Subject attribute's meta-data might include a list of predefined possible values like "Fiction & Literature" and "Science & Tech." Of course, as eBay cannot predict all possible values that a seller may want to specify for an item, the attribute also supports a user-defined value (identified as "Other"). The Subject attribute's meta-data also specifies relationships to other attributes. For example, you need to choose a main subject like "Fiction & Literature" or "Science & Tech" before you can choose a secondary subject, like "Fantasy" vs. "Engineering". The meta-data also includes a list of validation rules (e.g., a string length rule).

For information on how to retrieve attribute meta-data (characteristics), see Calls You Use to List with Item Specifics and Return Policies.

Characteristic Set: A characteristic set (CS) consists of a list of all the possible characteristics for a given category (usually a meta-category and all its child categories) plus instructions for presenting those characteristics in a form. Thus, you can think of a characteristic set as the collection of all the possible data, validation logic, and presentation logic behind a single Item Specifics form. Contrast this with an attribute set, which is used to hold the list of attributes and values that have been specified for a particular item.

Characteristic meta-data for standard Item Specifics is defined in a plain XML format rather than in the eBay unified schema. If you are using the approach recommended in Calls You Use to List with Item Specifics and Return Policies, you can ignore most of the details of the meta-data. However, if you are not using the recommended approach, or if your application design requires you to understand the model, see Attribute and Product Finder Content Models for information about details of the characteristic meta-data XML.

Figure 18-3 shows the relationship between AttributeSet and the characteristic meta-data. This diagram focuses on the objects that are defined in the WSDL. The Attributes Library provides similar classes that wrap the classes generated from the WSDL.

Figure 18-3 The Relationship Between Characteristic Sets and Attribute Sets

Each characteristic set is mapped to one or more levels in the eBay category hierarchy at which a particular group of items can share a common set of characteristics (Item Specifics). These are usually (but not always) the category levels at which a given item can be listed during the selling process. For example, the Books characteristic set is mapped to several book categories.

You should not assume that just because one lower-level category supports Item Specifics, it means that all sibling categories also support Item Specifics. For example, within the Books meta-category on the US eBay site, the Fiction & Literature subcategories generally support Item Specifics, but the Magazine Subscription subcategories might not support Item Specifics. For eBay Web Services, this means the Magazine Subscription subcategories would not be mapped to any characteristic sets.

eBay supports two types of characteristic sets:

Full characteristic sets

A full characteristic set is basically a standard set of Item Specifics. A category can be mapped to a maximum of one (1) full characteristic set.

Site-wide characteristic sets

Available on certain sites only: Most attributes are only meaningful in particular categories. For example, the Publication Year attribute is meaningful in book categories, but it would not appear for other categories. In addition to these category-level attributes, some eBay sites support the notion of global or site-wide characteristic sets. Site-wide characteristic sets can apply to any category (including categories that do not have their own Item Specifics). Although attributes in these characteristic sets could just be defined as regular item properties, they are defined as attributes to leverage the browsing and searching benefits of Item Specifics. Site-wide characteristic sets generally have fewer attributes than full characteristic sets.

The Condition attribute is an example of an attribute that can be in a site-wide characteristic set (although category-specific Condition attributes also exist on some sites). Often, buyers are interested in filtering and sorting search results according to the item condition (i.e., whether an item is new or used). To make it easier for sellers to specify the condition of their item in a structured way, many categories include a Condition attribute in their Item Specifics section. In some categories, the Condition attribute is defined as part of the category's own full set of Item Specifics. If the category has no Condition attribute of its own, the category can be mapped to a site-wide characteristic set that contains a Condition attribute. See Specifying an Item's Condition for additional information.

Return policy attributes can also be defined in site-wide characteristic sets. See Offering a Clear Return Policy for additional information.

Typically, a category is mapped to a site-wide characteristic set when the category has no Item Specifics at all or when the category's Item Specifics do not happen to already include attributes that match the site-wide attributes. A category can be mapped to multiple site-wide characteristic sets (e.g., Condition and Return Policy).

For information on how to determine which categories support full and site-wide characteristic sets, see Calls You Use to List with Item Specifics and Return Policies.

Page Locations: Buyers and sellers expect Item Specifics to be grouped with an item's title and description, and they expect return policy information to be grouped with payment and shipping instructions. To help you distinguish between return policy meta-data and Item Specifics meta-data, each attribute includes page location information that describes the group in which the attribute fits. The page location for return policy data is named ReturnPolicy. If no page location is specified for a given attribute, it means the attribute is associated with Item Specifics (the default group).

Auto-Filled Attributes and Category Mapping Details: eBay defines attributes and values that can be used to auto-fill attributes when a seller lists in certain categories.

In some cases, the auto-filled Item Specifics are values that are standard for or equivalent to a particular category. For example, in the Software : RIM Blackberry category, eBay might auto-fill a Type attribute with the value "Software" and a Compatible Brand attribute with the value "RIM Blackberry". In other cases, the auto-filled Item Specifics are equivalent to obsolete categories. This would typically occur when an obsolete category like Cannondale (a brand of bicycle) is combined into a more generic category like Road Bikes & Frames. In this example, eBay would auto-fill a Brand attribute with the value "Cannondale" (if the seller specifies the Cannondale category in a listing).

Use the category mapping details in the attribute meta-data when you want to use a category ID to auto-fill Item Specifics on the client side. Alternatively, you can pass in Item.CategoryBasedAttributesPrefill and Item.CategoryMappingAllowed in your listing request to allow eBay to auto-fill the same Item Specifics in the listing for you on the server side. The latter approach is recommended when you are revising or relisting a large number of items that were originally defined with categories that might now be obsolete and/or you prefer not to update the Item Specifics on the client side.

Note: Auto-filling attributes based on a category is not the same as using Pre-filled Item Information based on an eBay catalog product (see The Catalog Product (Pre-filled Item) API).

See CategoryMappingDetails Elements for additional information.

Calls You Use to List with Item Specifics and Return Policies

This section briefly summarizes the process you would use to list an item with Item Specifics. Later sections of this documentation provide more information on how to implement each approach in an application.

See Listing Items for information on listing the standard way with a basic description (without using Item Specifics).

Auto-Filling Attributes Based on a Category

One simple way to include a few Item Specifics in your listing is to set the Item.CategoryBasedAttributesPrefill and Item.CategoryMappingAllowed fields to true in your listing request. If the listing's category supports auto-filling attributes based on the category, eBay will fill in the values of certain attributes for you.

To use this feature, it is not necessary to also specify attributes in the request (using Item.AttributeSetArray). This means you do not need to understand the complete Attributes API flow in order to benefit from auto-filled attributes.

For example, if you list in the Cell Phones : Accessories : Software : RIM Blackberry category, eBay might auto-fill the Type attribute with the value "Software" and the Compatible Brand attribute with the value "RIM Blackberry". That way, buyers who search against those attributes will be more likely to find your listing.

The figure below shows an Item Specifics form with auto-filled attribute values.

Figure 18-4 Item Specifics Form With and Without Auto-Filled Attribute Values

If you do decide to also pass attributes in the request, the attributes you specify may override any attributes that eBay auto-fills. In the previous example, suppose you set the Compatible Brand attribute's value to "PalmOne, Handspring" in the listing request. In this case, the listing will include Type="Software" (auto-filled by eBay) and Compatible Brand="PalmOne, Handspring" (your attribute selection). Even if you later revise the item and remove the overridden "PalmOne, Handspring" value, eBay will treat the Compatible Brand attribute as overridden and it will not be auto-filled again in the listing.

Note: Once an item has been listed, the attribute data returned from GetItemCall does not indicate whether a given attribute has been auto-filled or overridden. If you need to understand this usage information (for troubleshooting purposes), it may be helpful to track this information on the client side.

If your request includes an outdated category ID, eBay will attempt to map your category to a more current category, and then eBay will auto-fill attributes based on the differences between the old category and the new category.

For example, suppose the category Cannondale has been combined into a more generic category like Road Bikes & Frames. If you specify the old category ID for Cannondale, eBay would list the item in the Road Bikes & Frames category and auto-fill the Brand attribute with the value "Cannondale". In this way, the listing still reflects the semantics of your original request. See Mapping Old Category IDs to Current IDs for more information about this option.

The sections below describe how to include Item Specifics in a listing request without using this auto-fill functionality.

Summary of Listing the Standard Way with Item Specifics and Return Policies  

When you list an item with Item Specifics and/or a return policy, you specify the attribute set ID, attribute ID, value ID, and (if "Other" was chosen as the value) the literal value (a string) that the user entered. You determine the IDs based on the values the user selected from the category's characteristic set. Also, you provide your own free-form description of the listing and, optionally, the return policy details.

In some categories, all the attributes are optional and have very few dependencies, so the logic you need to implement in order to list with Item Specifics is fairly straightforward. In other categories, some attributes may be required, and some may have complex dependencies, so the implementation can be more complex. For example, in the United States, Item Specifics are required for listings in Tickets, Real Estate, and Motors categories. Item Specifics for Tickets and Motors have more complex dependencies and validation rules than Item Specifics for other categories. See Ticket Listings and Listing US and CA eBay Motors Items.

Note for US Ticket Listings Only: New York and Illinois ticket resale laws require online platforms permitting sales of event tickets to offer full buyer protection. eBay offers full buyer protection on ticket sales to New York and Illinois events through PayPal. eBay therefore requires all sellers to accept PayPal payments for ticket listings when the venue state is New York or Illinois (regardless of where the buyer or seller is located). To do this, pass PayPal as an option in your array of Item.PaymentMethods.

As the library of attributes and values is revised periodically to meet the needs of eBay's user community, you should not hard-code attributes meta-data into your applications. Instead,implement the data-source provider interfaces provided in the eBay SDK for Java to retrieve and manage the data. These data-source provider interfaces are part of the Attributes Library, which aggregates and simplifies operations related to Item Specifics and Pre-filled Item Information functionality. Sample implementations are included in the Attributes Library. The samples retrieve meta-data and cache the data in memory only. You can create your own implementations that retrieve the data, store it (such as in a database), and then use the data store as the data source.

We strongly recommend that you use the Attributes Library in order to implement a solution that supports Item Specifics and/or return policies. The information below describes the sequence of calls you use to support listing with Item Specifics. It also describes how to use the Attributes Library, which aggregates and simplifies this workflow.

Figure 18-5 Listing the Standard Way with Item Specifics or Return Policies

GetCategoriesCall and ICategoryCSProvider (or GetCategory2CSCall)

A set of 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 to supply IAttributesMaster (see below) with the mappings needed to convert category IDs to characteristic set IDs (instead of using GetCategory2CSCall directly). Implement this interface as appropriate for your application's data storage needs. See the RenderHtmlForCategories() method on IAttributesMaster. 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.
IAttributesXmlProvider and IAttributesXslProvider (or GetAttributesCSCall and GetAttributesXSLCall
Use the IAttributesXmlProvider interface to supply IAttributesMaster with the characteristic set XML source to use (instead of using GetAttributesCSCall directly). 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 characteristic set XML directly from eBay and caches the data in memory. See Retrieving Item Specifics Meta-Data.
Use the IAttributesXslProvider interface to supply IAttributesMaster with the XSL stylesheet text to use for easily rendering Item Specifics in a user interface (instead of using GetAttributesXSLCall directly). 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.

Like the category calls, the attribute 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.

One way to modify the look and feel of the 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 Java uses a default patching stylesheet. You can replace this stylesheet by using the setStyleXsl() method defined on GetAttributesCSCall.For examples of patching stylesheets, please see Working with Attribute XSL Stylesheets.

IAttributesMaster

This interface defines the core functionality for managing all attributes-related operations in the eBay SDK for Java. 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 Item Specifics or return policies for the category or categories in which the user wants to list the item. This renders the fields in an HTML-based user interface.
When user enters Item Specifics or return policy 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 attributes 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 ErrorSet object. If any errors are found, pass the errors in the renderHtml() or renderHtmlForPostback() method on IAttributesMaster to generate the Item Specifics or return policy HTML form with error hints. For example, a typical error might be that required attributes are missing.

Use the getXmlProvider(), getXslProvider(), and getCategoryCSProvider() methods 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 Java or your own implementations. See Working with Attribute XSL Stylesheets for additional information.

AddItemCall with Item Specifics

Use AddItemCall to list an item. See Listing with Item Specifics and Catalog Data. When filling in the listing details:

Fill in the Description property with the listing description.
Fill in any required Item Specifics, plus optional Item Specifics as desired.
Optionally, use the CategoryMappingAllowed and CategoryBasedAttributesPrefill properties to allow eBay to update the categories as needed and to auto-fill applicable Item Specifics based on the item's categories.
Optionally, use the PictureURL and GalleryURL properties to specify images to include in the listing.
Fill in other required fields and specify optional listing enhancements (e.g., BoldTitle) as desired.

Note: It is also a good idea to use VerifyAddItemCall to test your input data for errors and to preview estimates of your listing fees before actually submitting the listing.

In addition, ReviseItemCall, RelistItemCall, and GetItemCall support working with Item Specifics.