eBay SDK for Java Guide: Listing an Item with Attribute and/or Product Data

This section describes the means and strategies for listing an item the standard way with Item Specifics and listing with Pre-filled Item Information.

If your locally stored characteristic set data has not been updated recently, execute GetCategory2CSCall and use the available filters to determine whether the data needs to be updated. If it does, retrieve the meta-data changes.

If the category-to-characteristic set mappings changed, it is likely that the Item Specifics and product search meta-data also changed for some categories. Execute GetAttributesCSCall to retrieve characteristic sets that have changed. Execute GetProductSearchPageCall and GetProductFinderCall to retrieve product search meta-data that has changed.

If you are using the Attributes Library, implement data-source providers that can check for changes and that can retrieve only the data that has changed.

When the user selects a category, check the mappings returned from GetCategory2CSCall or a data-source provider that implements ICategoryCSProvider to determine whether the category supports Item Specifics and whether it supports Pre-filled Item Information. Depending on what the category supports and what your application supports, you can use some combination of the following logic to allow the user to choose a listing option:

If the seller is listing in a Media category (Books, DVDs & Movies, Music, or Video Games), they can attempt to list their item with Pre-filled Item Information by specifying an ISBN, EAN, or UPC value by using ExternalProductID . A seller should only use this approach when they want to include all optional stock information, and they do not want to search for and preview a matching stock product from a catalog first. See Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID)

If the seller is listing in an Event Tickets catagory, they can attempt to list their item with Pre-filled Item Information by specifying the event name, venue, and date via ExternalProductID. A seller should only use this approach when they want to include all optional stock information, and they do not want to search for and preview a matching ticket description from the ticket catalog first. See Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date).

If the seller chooses to list the standard way with Item Specifics, retrieve the category's characteristic set meta-data from your local data store. Some categories do not have Item Specifics, but those that do may require attributes to be included in the request in order for the item to be listed.

If the seller selected two categories that are mapped to different characteristic sets, retrieve the meta-data for both characteristic sets from your local data store.

If the seller selected two categories that are mapped to the same characteristic set (e.g., Men's Big & Tall Outerwear and Men's Regular Other Jackets both map to Men's Outerwear), retrieve that characteristic set meta-data from your local data store.

If the seller wants to auto-fill Item Specifics based on the listing's categories, be sure the characteristic set meta-data in your local data store includes category mapping details.

If the seller chooses to list with Pre-filled Item Information (without using ExternalProductID), determine whether the category supports a single attribute search, product finder search, or both. Retrieve the category's product search page meta-data or product finder meta-data from your local data store and allow the user to search for and select a product. See Searching for Pre-filled Item Information.

In this case, if the seller selected two categories, see Product Search Considerations when Listing in Two Categories for information about which category's search data to retrieve.

If the user chooses to perform a product finder-style search, we recommend that you use the Product Finder XSL stylesheet or a data-source provider that implements IProductFinderXslProvider to handle the presentation. See Retrieving Product Search Page Meta-Data and Working with the Product Finder XSL Stylesheet for more information.

After the user finds and selects a product, retrieve the product's Item Specifics and other information by using GetProductSellingPagesCall or your XML data-source provider. See Retrieving a Product's Item Specifics.

If the listing is in a Media category (Books, DVD & Movies, Music, or Video Games), and if the seller knows the ISBN, EAN, or UPC value for the item they are listing, you can try to list the item by passing this value (by using ExternalProductID) without first searching for a matching product (see Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID)). If the seller chooses this approach, they can still specify optional attributes. However, as this approach does not involve going through the product search flow, you do not normally retrieve the attribute meta-data and render a product selling page for the product. To handle this case, eBay offers you an alternative approach: In Media categories, you can assume that at least one optional attribute is available: The Condition attribute. Its possible values are "New" and "Used". In a user interface, you could present this attribute as a drop-down list or as a set of radio buttons. When you create your AddItemCall request, you can use the lookup attribute fields (LookupAttributes) and specify "New" or "Used" instead of specifying the attribute ID and value ID.


Note: Currently, the lookup attribute only recognizes the values "New" and "Used", and it assumes the attribute is Condition. Do not attempt to specify other values for other attributes in the lookup attribute. The "New" and "Used" values have been normalized across all sites. Therefore, even if a given site or category normally uses a variation like "New in box", you should still just specify "New" as the lookup attribute value. The lookup attribute is only valid as input. eBay translates the value to the appropriate condition attribute in the listing's Item Specifics.

If the listing is in an Event Tickets category, you can try to pass the event name, venue, and date (by using ExternalProductID) without first searching for a matching product (see Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date)). If the seller chooses this approach, they still need to specify certain Item Specifics in the listing request.

If the listing is in another category (or the seller is not using ExternalProductID), you should present the Item Specifics to the seller so that they can select the desired attributes.

To render the XML returned from GetAttributesCSCall or GetProductSellingPagesCall, or your XML data-source provider, we recommend that you apply the XSL stylesheet that was returned from GetAttributesXSLCall or use the AttributesMaster to render the Item Specifics data in a user interface. This approach is usually easiest for application developers because a given category's attributes and values can change over time, and because some attributes can have a number of complex dependencies. See Retrieving the Item Specifics SYI XSL Stylesheet and Working with Attribute XSL Stylesheets.

If you want to render Item Specifics and handle all the dependencies yourself, you need to understand the Item Specifics content model that is returned as XML from GetAttributesCSCall or GetProductSellingPagesCall, or your XML data-source provider. See Attribute and Product Finder Content Models.

Important: eBay strongly recommends that you avoid directly modifying the XML returned from GetAttributesCSCall or GetProductSellingPagesCall, or your XML data-source provider except as required for use with the Item Specifics XSL (see Working with Attribute XSL Stylesheets). Any other direct changes to the XML documents returned from these attribute and product meta-data calls are not supported.

If the user is listing the standard way with Item Specifics and they have selected two categories that are mapped to different characteristic sets, present each characteristic set on separate pages. If the user selected two categories that are mapped to the same characteristic set, present the characteristic set only once in the user interface. You cannot specify the same characteristic set twice (with different attribute and values) in the same AddItemCall request.

You can skip this step if the seller is using lookup attributes (see above) in their listing. This step only applies when the seller specifies attributes and values based on meta-data retrieved by using GetAttributesCSCall or GetProductSellingPagesCall (or an XML data-source provider that executes one of these calls).

When the user selects the attributes and values for their listing, validate the user's selections (see Validating Attribute Data Before Listing Items). If there are problems, inform the user (e.g., via error messages).

The XML retrieved by using GetAttributesCSCall or GetProductSellingPagesCallincludes validation rules that you can use to validate individual attributes and values that the user selected. See Validating Attribute Data Before Listing Items or use the functionality provided by the AttributesMaster class in the Attributes Library. In addition, the meta-data defines various dependencies between attributes that need to be maintained. If you are using the Item Specifics SYI XSL stylesheet or the Attributes Library, it will manage most of these dependencies for you. If you are not, you will need to understand the details of the Item Specifics meta-data model in order to manage these dependencies (see Attribute and Product Finder Content Models).

It is a good idea to validate the user's selections before submitting the data. (You do not need to validate pre-filled attributes.) If the data the seller selects is not valid, the listing call will return errors. If necessary, present the data to the user again with error messages that identify problems.

It is a good idea to check the attribute data for the following common problems. See the validate( ) method on the AttributesMaster class for an example of how to do this.

For example, an application that uses the Item Specifics SYI XSL stylesheet might use this approach to present errors:

Build a new XML document that specifies the characteristics the user selected. If you are using the Attributes Library, use the AttributesMaster object's renderHtml( ) method. Otherwise, see Converting Selected Attributes to AttributeSetType.

If errors were found during validation, append the errors to the XML document. If you are using the Attributes Library, use the AttributesMaster object's validate( ) method. Otherwise, see Generating Error Messages in the Item Specifics Form).

Reapply the Item Specifics SYI XSL stylesheet to display the selected attribute data and the error message(s).If you are using the Attributes Library, use the AttributesMaster object's renderHtmlForPostback( ) method.

When the user is ready to submit their listing to eBay, gather all the necessary IDs and values for the Item Specifics or product the user specified. This data is summarized in the sections below and also in Table 18-2.

Set the fields on AttributeSet and/or ProductListingDetails based on the user's selections. If you are using the Attributes Library, use the AttributesMaster object's nameValuesToAttributeSets( ) method to create one or more AttributeSet objects, as appropriate for the listing. Otherwise, see Converting Selected Attributes to AttributeSetType.

It is a good idea to check the attribute data for the following common problems. See the validate( ) method on the AttributesMaster class for an example of how to do this. The XSL stylesheet will enforce the following rules in the user interface, but you need to make sure you also transfer all the correctly selected attributes and values when you create the AttributeSet object:

If you specify a value for a child attribute, you also specify a value for its parent.

If an attribute is only valid in a visibility (Type 4, Value-to-Attribute) dependency relationship, you also specify an appropriate parent value. For example, within the Tickets characteristic set, Face Value is required and only valid when certain Venue State/Province values are selected; otherwise, it is not allowed (see Characteristic Parent-Child Relationships (Dependencies)).

(Optional) No Type 1 (pre-filled) attributes are included in the request, as they will be ignored (see Determining Whether the User Can Choose an Attribute Value).

(Optional) If a Type 2 (conditionally pre-filled) attribute is included in the request, its value was not already pre-filled by eBay, as it will be ignored.

No required attributes are missing from the request (see Characteristic Parent-Child Relationships (Dependencies) and Validation Rules in the Attribute Meta-Data).

Specifying Item Specifics and/or Product Information

For each category for which the seller has specified Item Specifics, create an AttributeSet object and fill in its properties based on the attributes and values the seller selected.

You can also specify the version number of the attribute set (which is identical to the version number of the characteristic set) you are using. This is a convenient way to double-check that the version you are using is current (a warning is returned if the version is outdated).

If either category is associated with a site-wide characteristic set, the request can also contain any number of additional AttributeSet properties for site-wide attributes.

Assign the AttributeSet (or sets) to the Item.AttributeSetArray property. Assign the corresponding category ID to the PrimaryCategory or SecondaryCategory property, as appropriate.

If the user is listing with a stock product (Pre-filled Item Information):

Do not specify Type 1 or pre-filled Type 2 attributes, as eBay generates pre-filled attributes and values for you based on the product.

For attributes that relate to the category associated with the product, use GetProductSellingPagesCall to determine valid attributes. (You only need to specify attributes that are not pre-filled.)

For attributes that do not relate to the category associated with the product, call GetAttributesCSCall to determine valid attributes.

If the user is listing with Pre-filled Item Information, give them the option to include the stock photo (if any) in their listing and to use the stock photo as their gallery image. Also give the user the option to include the supplemental pre-filled summary in their listing.

For the catalog-enabled category that the user is listing in (and that supports Pre-filled Item Information), create a ProductListingDetails object and set its properties based on the product ID and the options the user selected. Assign the ProductListingDetails object to the Item.ProductListingDetails property.

If the user is not listing with Pre-filled Item Information and they want to auto-fill some Item Specifics based on the listing's category instead, set both the Item.CategoryMappingAllowed and Item.CategoryBasedAttributesPrefill flags to true. If the auto-filled attributes have the same IDs as any you pass in the request, the values you pass in will override the auto-filled values. See Auto-Filling Attributes Based on a Category.

Fill in other Item object properties as usual and set the item on the AddItemCall request as usual. See Listing an Item for information about other item properties.

Optionally, specify how you want eBay to handle any invalid attribute data that you pass in the request (see Attribute Error Handling).

When you are listing with Pre-filled Item Information, certain input fields have different usage rules than they do when you are listing the standard way. In addition, you can pass in an ErrorHandling field (defined on the abstract request, not on ItemType) to control indicate how you want eBay to handle any invalid attribute data that you pass in the request (see Attribute Error Handling).

Table 22-1 Item Fields That Support Pre-filled Item Information
Item Field	Additional Reading
AbstractRequestType.ErrorHandling	Attribute Error Handling
Item.AttributeSetArray	Validating Attribute Data Before Listing Items
Item.CategoryBasedAttributes Prefill	Auto-Filling Attributes Based on a Category Auto-filling attributes based on a category is not the same as using Pre-filled Item Information based on a catalog product (see Item.ProductListingDetails). Alternatively, you can pre-fill attributes on the client side by using mapping meta-data returned by `GetAttributesCS`. See CategoryMappingDetails Elements.
Item.CategoryMappingAllowed	Mapping Old Category IDs to Current IDs
Item.Description	Optional when `IncludePrefilledItemInformation` is set to `true`. Also optional when `ExternalProductID` is used (because it sets `IncludePrefilledItemInformation` to `true`). (This also means GetItemCall and GetSellerListCall may return some items with empty `Description` fields.)
Item.ExternalProductID	Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID) Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date)
Item.LookupAttributeArray	Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID) Only valid in Media categories (Books, DVD and Movies, Music, and Video Game categories).
Item.PrimaryCategory	Listing in Two Categories with Item Specifics Product Search Considerations when Listing in Two Categories
Item.ProductListingDetails	The Catalog Product (Pre-filled Item) API
Item.SecondaryCategory	Listing in Two Categories with Item Specifics for rules. Product Search Considerations when Listing in Two Categories

The example below creating an Item object and assigning values to a number of its properties. See the addItem.jsp sample in the \samples\attributesDemo\AttributesDemo directory for a more detailed example.

Example 22-1 Defining the New Item
// Use the Attributes Library AttributeSet object instead of AttributeSetType AttributeSet[] sets = ITEM_ATTR_SETS; CategoryType[] selCats = SEL_CATS; SiteCodeType siteID = SITE_ID; CurrencyCodeType currencyType = CURRENCY_OF_SITE;
try { // Create the Item object (item) ItemType item = new ItemType(); item.setSite(siteID);
// Set the attribute properties AttributeSetArrayType asAry = new AttributeSetArrayType(); asAry.setAttributeSet(sets); item.setAttributeSetArray(asAry);
// If the seller specified a product ID, include Pre-filled Item Information if( sets[0].getProductID() != null ) { ProductListingDetailsType pld = new ProductListingDetailsType(); pld.setProductID(sets[0].getProductID()); pld.setIncludeStockPhotoURL(Boolean.TRUE); pld.setIncludePrefilledItemInformation(Boolean.TRUE); item.setProductListingDetails(pld); item.setTitle("New listing with Pre-filled Item Information"); } else { item.setTitle("New listing with Item Specifics"); }
// Assign values to other required and optional item properties as usual See Listing an Item

Pre-filling a Listing Based on ISBN, EAN, or UPC Values (ExternalProductID)

If the listing is in a media category (Books, DVD & Movies, Music, or Video Games), and if you know (i.e., the seller knows) the ISBN, EAN, or UPC value for the item you are listing, you can try to list the item with catalog information without first searching for a matching product. To do this, you create a basic AddItemCall object and use the ExternalProductID.Value property to pass in the ISBN, EAN, or UPC value and use one of the corresponding code list values in ExternalProductID.Type to indicate the type of value you passed, such as ISBN. (Do not use the Item.ProductListingDetails.ProductID property in this case. )

If you are using a media catalog and the primary and secondary category are both catalog-enabled, the external identifier must correspond to the primary category.

If the listing is in a ticket category, see Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date) for additional rules about using ticket keywords as the external product identifier. (Please do not attempt to use this keywords option for Media catalogs, as you may see inconsistent results and possible data corruption.)

When you execute AddItemCall with an external product identifier, eBay searches the product catalog for a product that matches the ISBN, EAN, UPC you passed in and (if a match is found) uses that product in the listing. eBay also sets all optional flags (e.g., IncludeStockPhotoURL) to true for the product automatically.

The main intent of this approach is to let you specify an ISBN, EAN value or UPC value so that you do not need to first search the catalog to determine the product ID for a stock product. This helps the seller list the item more quickly, and it requires fewer API calls.

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. If you also set PictureDetails.GalleryType, the stock photo will be used as the Gallery image.

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. In this case, use GetProductSellingPagesCall or your XML data-source provider to retrieve information about each product to determine which one most closely matches your listing. Then, execute AddItemCall again, and specify the product ID of the desired product

If you pass in an old product ID and only one match is found, eBay will list the item with the latest version of the product and the latest product ID, and the call will return a warning indicating that the data has changed (see Catalog Product ID Updated).

When specifying an eBay product ID, you can either use the ExternalProductID property or the ProductListingDetails property. These are the main differences between these two properties:

You can pass an ISBN, EAN, UPC, or eBay product ID value in the ExternalProductID property. You can only pass a product ID (no ISBN, EAN, or UPC value) in the ProductListingDetails property.

If you are passing in a product ID, you can use either property for any catalog-enabled category. That is, when you use a product ID, the use of the ExternalProductID property is not limited to Media categories. It is only when you use an ISBN, EAN, or UPC value that the listing is restricted to Media categories.

When you use ProductListingDetails, you have control over the values set for optional flags like IncludeStockPhotoURL. When you use ExternalProductID, all optional flags for the product, like IncludeStockPhotoURL, are set to true automatically by eBay.

ExternalProductID is a property of AddItemCall (not Item), and it cannot be used with any other calls. ProductListingDetails is a property of the Item object and it can be used with all item-listing calls.

ExternalProductID can only be used as input. ProductListingDetails can be used as input, and it is also returned in the GetItemCall response.

If you specify both ExternalProductID and ProductListingDetails in the same request, eBay ignores any values you specify in the ProductListingDetails fields.

See Step 5: Define the Item for information about the input fields that you can use when listing an item with an ISBN, EAN, or UPC value.

Pre-filling a Ticket Listing Based on Keywords (Name, Venue, and Date)

If the listing is in an Event Tickets category on the US or Canada eBay site, you can attempt to list the item with catalog information by specifying a set of keywords that uniquely identify the ticket (event name, venue, date, and time). This is useful when you do not want to first search the ticket catalog to determine the product ID for a stock product. This approach helps sellers list tickets more quickly, and it requires fewer API calls than the search-to-sell flow (i.e., the GetProductSearchResults flow).

To use this feature, you create a basic AddItemCall object and use the ExternalProductID.Value property to pass in the keyword values. Set ExternalProductID.Type to the value Keywords. (Do not use the Item.ProductListingDetails.ProductID field in this case.)

Important: The Keywords option is designed to uniquely identify stock ticket products only. It is only supported for listings that use Pre-filled Item Information from the ticket catalog. Please do not attempt to use this keywords option for other catalogs. If you use this option for other catalogs, you may see inconsistent results and possible data corruption.

Table 22-2 describes the valid ticket keywords and the rules for using them. You can pass these keywords in any order.

Table 22-2 Valid Values for US Ticket Keywords in ExternalProductID
Keyword Type	Validation Rules	Sample Values
Event Name	The name of the event, as shown on the ticket. Typically the headliner. There is no maximum number of words or characters. However, the words in the name must be an exact match (or a subset consisting of complete words) to the words in the product title in the catalog. The words in the name are matched using OR logic (the order of the words does not matter). In other words, if the headliner is shown on the ticket and in the catalog as "My Favorite Musician", you can pass "favorite musician" or "my favorite musician". But if you pass extra words like "usa tour" (e.g., "My Favorite Musician USA tour"), no match will be found because the ticket title in the catalog does not include "USA tour". Similarly, if the sporting event is shown on the ticket and in the catalog as "San Francisco Giants vs Oakland Athletics (Exh)", you can pass "san francisco giants oakland athletics (exh)", or "Oakland Athletics vs. San Francisco Giants", or "giants athletics" (or even "athletics san oakland giants francisco"). But if you pass "San Francisco Giants vs Oakland Athletics Exhibition" (where you spell out "exhibition" instead of using "exh" as shown on the ticket), or if you use the name "Oakland A's" instead of "Oakland Athletics", no match will be found. The event name is not case-sensitive. As with all strings, you need to escape reserved characters such as ampersand. See Simple Schema Types.	my favorite musician
Venue	The name of the venue, as shown on the ticket. The validation rules are the same as the rules for the event name. In addition, eBay supports both US English and UK English spelling variations for typical words found on tickets (such as "theater" and "theatre").	ebay amphitheatre
Event Date	The date of the event, as shown on the ticket. Use the date shown on the ticket, without attempting to adjust it for a different time zone (such as Pacific time or GMT). In most cases, you should be able to specify any numeric date format in month/day/year order. eBay supports m or mm for the month, d or dd for the day, and yy or yyyy for the year, in all combinations. The delimiters must be forward slashes (/).	12/01/2005 12/1/05
Event Time	The time of the event, as shown on the ticket. Use the time value shown on the ticket, without attempting to convert it to a different time zone (such as Pacific time or GMT). Do not round the value up or down (e.g., do not round 7:01 PM to 7:00 PM). In most cases, you should be able to specify the time format exactly as shown on the ticket. The following formats have been tested (where "am" and "pm" without periods are not case-sensitive): Time only: H:MM HH:MM Time with "am" or "pm", with spaces: H:MM am HH:MM am HH:MM pm Time with "am" or "pm", with no spaces: H:MMam HH:MMam HH:MMpm Time with "am" or "pm", with no minutes (only applicable to time values that are on the hour, with "00" minutes): Ham Hpm HHam HHpm You can also use lowercase "a.m." or "p.m." (with periods) instead of "am" or "pm". Uppercase "A.M." and "P.M." (with periods) are not supported.	2:00 PM 2pm 2:00 p.m.

For example, you could pass the following set of keywords in the ExternalProductID.Value field:

For ticket listings, the catalog-enabled event tickets category must be the primary category.

When you list a ticket in this manner, eBay searches the ticket catalog and (assuming a unique match is found) pre-fills certain Item Specifics and other data based on the catalog data. If a single matching product is found, the item will be listed with that product's Pre-filled Item Information, including a stock venue map (if available) and other stock information. The stock venue map will be used as the listing's picture and Gallery image. Typically, the venue map shows the venue's seating chart relative to the stage, screen, or field.

If no matches are found, the call returns an error and the item is not listed. If this occurs, use one of these approaches to correct the problem:

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 the keywords you passed in. If this occurs, use one of these approaches:

If you pass in an old product ID (instead of ticket keywords) and only one match is found, eBay will list the item with the latest version of the product and the latest product ID, and the call will return a warning indicating that the data has changed (see Catalog Product ID Updated).

When specifying an eBay product ID, you can either use the ExternalProductID property or the ProductListingDetails property. These are the main differences between these two properties:

You can pass ticket keywords or an eBay product ID value in the ExternalProductID property. You can only pass a product ID (not ticket keywords) in the ProductListingDetails property.

ExternalProductID is a property of AddItemCall (not Item), and it cannot be used for revising or relisting items. ProductListingDetails is a property of the Item object and it can be used with all item-listing calls.

ExternalProductID can only be used as input. ProductListingDetails can be used as input, and it is also returned in the GetItemCall response.

If you specify both ExternalProductID and ProductListingDetails in the same request, eBay ignores any values you specify in the ProductListingDetails fields.

Required Attributes for Ticket Catalog Listings

Ticket listings have certain required Item Specifics (such as the number of tickets you are selling) that you also need to pass when you list a ticket—even if you pre-fill most Item Specifics from the ticket catalog. It is also a good idea to pass optional Item Specifics that are not in the catalog (such as the section and row).

Table 22-3 lists some common ticket attributes that are not pre-filled by the ticket catalog. These attributes were applicable on the US and Canada sites as of November 30, 2005 in the Tickets attribute set (ID: 1). Use GetAttributesCSCall to determine other optional ticket attributes that may be available.

Table 22-3 Commonly Used Event Ticket Item Specifics (US and CA)
Attribute Label and ID	Value Label (ValueLiteral) and ID	Required?
Number of Tickets (ID: 1)	1 (ID: 1025) 2 (ID: 1026) 3 (ID: 1027) 4 (ID: 1028) 5 (ID: 1029) 6 (ID: 1030) 7 (ID: 1031) 8 (ID: 1032) 9 (ID: 1033) 10 (ID: 1034) Other (ID: -6) (ValueLiteral min: 1, max: 100000)	Required
Section (ID: 10400)	Arbitrary string (ID: -3) ValueLiteral max length: 6 characters	Optional
Row (ID: 10399)	Arbitrary string (ID: -3) ValueLiteral max length: 6 characters	Optional
Event Subtype (ID: 37)	Concerts: Classical (ID: 1018) Comedy (ID: 18903) Country/Folk (ID: 1019) Jazz, Blues (ID: 1020) R&B/Rap/Hip Hop (ID: 1023) Rock/Pop/Altern. (ID: 1024) Other (ID: -6) (ValueLiteral max length: 30 characters) Theater: Family, Children's (ID: 17084) Musicals (ID: 1016) Plays (ID: 1017) Other (ID: -6) (ValueLiteral max length: 30 characters) Sporting Events: For sporting events, the Event Subtype attribute is usually pre-filled from the catalog, so you should not pass it in your listing request. The IDs are provided here for reference only: Baseball (ID: 1007) Basketball-College (ID: 1008) Basketball-Pro (ID: 1009) Boxing (ID: 18945) Football-College (ID: 1010) Football-Pro (ID: 1011) Golf (ID: 1012) Hockey (ID: 1013) Motor Sports (ID: 1006) Olympics (ID: 18949) Soccer (ID: 1014) Tennis (ID: 24066) Wrestling (ID: 1015) Other (ID: -6) (ValueLiteral max length: 30 characters) Movies: Event subtypes are not applicable to movies at the time of this writing. Note: This list was updated in November 2005. For the latest list of event subtypes for each event type, use GetAttributesCSCall and look for parent-child dependencies with `childAttrId="37"`. See Characteristic Parent-Child Relationships (Dependencies) if you are not familiar with how these dependencies work.	Optional
Face Value (ID: 62)	Numeric value (ID: -3) ValueLiteral min: 0.01, ,max: 2000000000 Do not specify a thousands separator (e.g., a comma). Required (and only applicable) for tickets listed in the states identified below.	Conditional
Venue State/Province (ID: 9)	In most cases, the venue state is pre-filled from the catalog, so you do not need to pass it in the listing's Item Specifics. However, if the venue is in one of the following states, you may need to specify the Venue State/Province attribute in your request so that eBay can validate the dependency between this attribute and the Face Value attribute. If the event venue is in one of the following states or provinces, the Face Value attribute is required in AddItemCall. Arkansas (ID: 1038) Connecticut (ID: 1041) Florida (ID: 1044) Illinois (ID: 1048) Kentucky (ID: 1052) Louisiana (ID: 1053) Massachusetts (ID: 1056) Michigan (ID: 1057) Minnesota (ID: 1058) Mississippi (ID: 1059) Missouri (ID: 1060) New Jersey (ID: 1067) New Mexico (ID: 1068) New York (ID: 1069) North Carolina (ID: 1062) Pennsylvania (ID: 1073) Rhode Island (ID: 1074) South Carolina (ID: 1075) Provinces in Canada that require a Face Value attribute: Alberta (ID: 1086) Manitoba (ID: 1088) Ontario (ID: 1094) Note: This list was updated in November 2005. For the latest list of states that require you to fill in the face value, use GetAttributesCSCall and look for parent-child dependencies with `childAttrId="62"`. See Characteristic Parent-Child Relationships (Dependencies) if you are not familiar with how these dependencies work.	Optional

Making the API call entails creating a Fees object and passing the Item object as an argument to the the AddItemCall.addItem( ) method, storing the return value of the addItem( ) method into the Fees object.

Example 22-2 Making the API Call
FeesType fees; AddItemCall aic = new AddItemCall(apiContext); aic.setSite(siteID); // Execute the request. fees = aic.addItem(item); // Store the results (such as to a database) } // Catch and handle errors, displaying appropriate messages for the end-user // See Error Handling for information about handling infrastructure errors

AddItemCall retrieves the item ID (the unique identifier for the new listing), along with the estimated fees the seller can expect to pay for the listing. The listing fees are returned by the AddItemCall.addItem( ) method in a Fees object. The other values are set in the Item object previously defined for the input. See Listing an Item for more information about data that is returned from AddItemCall.

If you have not updated your Item Specifics or product meta-data recently, some problems could occur when you submit the listing:

If the AddItemCall request fails and you receive an error that says the attribute set version number is out of date, execute GetAttributesCSCall or GetProductSellingPagesCall (as appropriate) to retrieve the latest version of the Item Specifics or product meta-data, and then make sure the data the seller specified is still valid. See Retrieving a Product's Item Specifics and Attribute System Version Changed.

If you specify a product ID that is no longer in the eBay system, the AddItemCall request may fail and return an error indicating that the product ID is not valid. In this case, retrieve the latest version of the product meta-data, and then make sure the data the seller specified is still valid. See Searching for Pre-filled Item Information.

Determine whether the change would be of interest to the seller. For example, retrieve the item to determine which attributes or product ID was actually used in the listing. See Call GetItem to Retrieve the Listed Attributes and Product Information for information on retrieving a listing that includes Item Specifics.

If appropriate, display the updated attribute set to the user and give them an opportunity to reconfirm or update the selected attributes. See Retrieving a Product's Item Specifics.

Execute ReviseItemCall to update the listing, if necessary. See Revising Items.

At your convenience, execute the attribute and product meta-data retrieval calls to retrieve the latest version of the Item Specifics and product search meta-data.

If your application typically lists in certain categories only, you may want to customize how eBay should handle your listings when problems are found with the attribute data you pass in (see Attribute Error Handling).

After listing an item with Item Specifics and/or Pre-filled Item Information, it is a good idea to execute GetItemCall to compare the request to the data that was actually listed to make sure that the listing matches the data that you sent. For example, if eBay removed an attribute or value from the attribute database, the listed item will not include that attribute or value. See Creating Listings Before the Listing Start Date for an example of a situation in which the attributes in your listing might not match the current attributes on the site. Also see Attribute Error Handling for examples of situations in which attributes might be removed from a successful listing.

Retrieving the listed data is particularly useful if you listed with an ISBN, EAN, or UPC value or ticket keywords, so that you can find out what was included in the listing.

If a listing includes Item Specifics, the Item Specifics will be returned when you execute GetItemCall with the ReturnAll or ItemReturnAttributes detail level. Similarly, if the listing includes Pre-filled Item Information, the product details will be returned with these detail levels.

When you list in certain categories (or, more specifically, certain characteristic sets), GetItemCall may return additional attributes that are computed from other attribute values. This means that the AttributeSet data in the response may not always be identical to the AttributeSet that you submitted. For example, suppose a category's Item Specifics include separate attributes for City (e.g., "San Jose"), State (e.g., "CA), and Zip Code (e.g., "95125"). In some categories, the GetItemCall response might contain those attributes plus an additional attribute that shows all three values together in one field (e.g., "San Jose, CA 95125") for display purposes.

Use a similar process to display Item Specifics when revising or re-listing the item. See Revising Items for restrictions on modifying and adding attributes when revising a listing.

If you have listed an item with Item Specifics, it may be helpful to save the meta-data that was in effect at the time so that you can use it later to render the existing listing. Once an item has been listed with Item Specifics, the original selections will not be modified in the existing listing. However, if you decide to modify a listing's Item Specifics when you revise or re-list the item (using ReviseItemCall or RelistItemCall), you may need to use the latest Item Specifics. When an item is revised or re-listed, it can continue to use the same Item Specifics as the original listing as long as they are still valid. If they are no longer valid, the revise or re-list call may return an error.

eBay SDK for Java
Attributes & Catalogs > Listing with Item Specifics and Catalog Data > Listing an Item with Attribute and/or Product Data


Attributes & Catalogs > Listing with Item Specifics and Catalog Data > Listing an Item with Attribute and/or Product Data
© 2005–2007 eBay Inc. All rights reserved.