Item Specifics Updates for Clothing, Shoes & Accessories
(Updated June 7, 2011 -- Note that support for ID-based attributes in these categories has been extended to July 20, 2011. Also, GetCategorySpecifics returns required custom item specifics for applicable categories as of early June 2011.)
From April through July 2011, eBay is making changes in fashion categories for fashion enthusiasts. Here’s what developers need to know to support these changes. (These changes will affect eBay US and international sites.)
No ID-Based Attributes in Clothing, Shoes & Accessories
Support for ID-based attributes (Item.AttributeSetArray) is ending soon (late July) in Clothing, Shoes & Accessories. Use custom item specifics (Item.ItemSpecifics) in AddItem and related calls instead. (All areas of Clothing, Shoes & Accessories have supported the new custom item specifics format for the past year or more.)
If you still have Clothing, Shoes & Accessories listings with ID-based attributes, eBay will convert those existing listings to custom item specifics for you.
Category Structure Changes in Clothing, Shoes & Accessories
A number of changes have been made to the Clothing, Shoes & Accessories category structure. Category structure changes will eliminate redundancies, improve coverage, and meet buyers’ shopping experience expectations. Your (or your sellers') listings falling under impacted categories may have been moved to new categories based on existing category ID and item specifics. After the category structure updates are effective (on April 5th), please revise your listings if you feel a different category is a better fit.
In addition to the category structure changes, we are tailoring custom item specific values in Clothing, Shoes & Accessories. The values are being improved to meet sellers’ needs and to help with item specifics relevance. For example, some subcategories are moving out of the Clothing, Shoes & Accessories category structure and into item specifics instead. (Some new categories are being added, as well.)
GetCategorySpecifics identifies the available custom item specifics for leaf categories, as well as dependencies between item specifics. After the metadata changes are available in the system, see NameRecommendation.ValidationRules.MinValues to identify required item specifics, and NameRecommendation.ValidationRules.Relationship for any dependencies. GetItemRecommendations will also be updated.
Note: Although GetCategory2CS and GetAttributesCS may still return ID-based attribute data for these categories, we recommend that you avoid using these calls for Clothing, Shoes & Accessories. As a general rule, if GetCategoryFeatures shows that a category supports custom item specifics (ItemSpecificsEnabled) or a category has been converted from ID-based attributes to custom item specifics (AttributeConversionEnabled), you should use custom item specifics instead of ID-based attributes.
Required Item Specifics Coming in June and July in Clothing, Shoes & Accessories
Starting July 20, 2011 all new and revised listings in Clothing, Shoes & Accessories categories must include the following custom item specifics: Brand, Size Type, Size, Style, and Color. Required item specifics may vary by category.
These calls will fail if listings in the above categories are missing required item specifics:
- AddItem and AddFixedPriceItem
- RelistItem and RelistFixedPriceItem
- ReviseItem and ReviseFixedPriceItem (even if your revision does not touch the item specifics)
The following cases will not be blocked for now. However, we recommend that sellers include the required item specifics in these listings in order to benefit from the new buyer experience:
- ReviseInventoryStatus (for changing price and quantity) won't be blocked regardless of whether existing listings in Clothing, Shoes & Accessories categories have the required item specifics.
- Good 'Til Canceled (GTC) listings that you don't revise, they will continue to renew automatically for the next several months even if they are missing required item specifics.
Early Access Info: Starting in June 2011, GetCategorySpecifics and GetItemRecommendations will identify the required custom item specifics for leaf categories, before they become mandated on July 20. (Alternatively, see the lookup table for developers (link below) to view the mandated item specifics).
In general, if ValidationRules.MinValues is set to 1, it means the item specific is required for that category. For Clothing, Shoes & Accessories categories, it means that the item specific will be required after July 20.
AddItem and related calls will not enforce these required item specifics in fashion categories until July 20. However, we encourage you to start using the required item specifics as early as possible.
More Information On These Fashion Category Changes
Site changes for Fashion Pages - April 2011
Item specifics required in Fashion categories
Required Item Specifics Lookup Table for Sellers
Review the category, catalog and item specific updates coming April and May
Item Specifics Lookup Table (All Categories) for Developers
Upload properly formatted payload files for Large Merchant Services (LMS) jobs
LMS jobs would hang or take too long if the uploaded payload file contained the requests on very few lines. Such jobs also negatively impacted the execution times of other jobs that were being processed.
In order to avoid this situation, the LMS team has implemented a feature to proactively detect and reject payload files that do not have line breaks (>20000 chars on a single line). This feature will be turned on in production during the week of 4th of April 2011.
Call for action: Please ensure that you incorporate line breaks between requests to avoid this situation. Also make sure that individual requests are properly formatted and are not on a single line.
713 Trading, Shopping, Merchant Data API Docs Now Available
Please remember to use a test environment when updating applications to use a new schema version.
To find out when a version of the API will be available, see the table at the top of the Release Notes for that API.
You can find the latest API documentation at the eBay Developer Documentation Center.
- 2011 Spring Seller Update for Sellers
- Additional Shipping Services Supported Beginning 719
- Condition ID 3000 Changed to 2750 for Some Media Categories
- GetSuggestedCategories Provides Better Category Suggestions
See the Trading API System Announcements for bug fixes included in this release.
ShoppingShopping Release Notes
See the Shopping API System Announcements for bug fixes included in this release.
Merchant DataMerchant Data Release Notes
See the Large Merchant Services API System Announcements for bug fixes included in this release.
API Tech Docs
Major Change to Large Merchant Services: UTF-8 encoding is required starting Feb 14, 2011
Beginning 2011-02-14, Large Merchant Services will require all input files to be UTF-8 encoded. Other encodings (e.g. ISO-8859-1) will not be rejected by the system, but some characters may not be rendered correctly on the View Item page.
Please make the required changes in your application.
eBay Developer Technical Support Team
Developer Impact: Duplicate Listing Policy
Yesterday, Dinesh Lathi announced a new Duplicate Listing policy on eBay (US, CA, CAFR) and eBay Motors. Starting October 26, a seller’s duplicate listings may be removed unless they are "significantly different in buyer benefit and value from items offered in their other Fixed Price listings." This policy does not apply to auction format.
Developers may want to consolidate listings for their sellers. The easiest thing to do is take duplicate single-quantity listings, increase the quantity of one listing, and end the other listings. If the other listings are ended on Oct 26, insertion fees will be credited.
Duplicate listings can also be consolidated into multi-variation listings, or fitment listings (in Motors P&A). It is not possible to directly convert the format, so the original duplicate listings will need to be ended, and the consolidated item listed as a new multi-variation or fitment listing.
Sellers who continue to create duplicate listings may be subject to a range of additional actions including "listing cancellation, loss of fees, limits on account privileges, loss of seller status, and account suspension." Developers will want to make sure that they consolidate seller listings to avoid subjecting their sellers to penalties.
For more details on this new policy, including example duplicate listings, see:
- Interview with Todd Lutwak on the updates
May I Take Your Order?
One of my favorite things about coming to DevCon (besides connecting with everyone face-to-face) is the opportunity to hear speakers like ChannelAdvisor's Grant King share their eBay API best practices. Grant's session on processing eBay orders was, well...just what I ordered!
First, a definition: An eBay order contains two or more separate transactions.
Use Platform Notifications for More Timely Processing
If you want to process a purchase very quickly after the buyer has paid (especially if you handle a large number of transactions), Grant suggests using eBay's Platform Notifications, like AuctionCheckoutComplete and FixedPriceEndOfTransaction.
Here's how it works: When a buyer completes checkout, eBay calls GetItemTransactions on your behalf immediately, and then sends you the GetItemTransaction response as the payload in the notification.
In his experience, notifications are close to 100% reliable nowadays, but it's a good idea to also poll periodically to make sure you catch any transactions that were somehow missed.
Poll with Transaction, Order, and Event Calls
If you're polling, use calls like GetSellerTransactions, GetSellerEvents, GetOrders, and/or GetOrderTransactions. Be sure to build in a bit of padding in the ModTime filters, so you don't miss transactions or events.
In the transaction calls, if OrderID is returned, then use GetOrders to make sure you know about all the purchases that were in the order.
Look for PaymentMethodUsed to find out how the buyer paid, and ExternalTransactionID for the PayPal transaction ID (which the seller needs in order to look at the details on PayPal).
He talked about other fields that are also useful to look for, and suggested best practices for using these calls in combination.
When to Get Order Details
You may want to wait until the buyer has paid (completed checkout) before you import and process all the transaction details from eBay.
To figure out when the buyer has paid, look for CheckoutStatus=CheckoutComplete, and eBayPaymentStatus=NoPaymentFailure. (Ignore CompleteStatus).
If you're using Large Merchant Services, the Merchant Data API's SoldReport hs equivalent fields, like BuyerPaymentTransactionNumber for the PayPal transaction ID, and PaymentClearedTime to confirm that the buyer paid.
For more tips on monitoring the payment status, check out answer ID 1048 in eBay's developer knowledge base ("Mapping eBay Checkout & PaymentStatus with PayPal IPN PaymentStatus").
Other Checkout Tips
Grant gave advice on handling shipping, US tax and non-US VAT, and other eBay checkout features; plus things to think about when you verify that your calculations match the values you got from eBay.
Once the items have shipped, send the buyer the tracking number (good communication can help DSRs). Use CompleteSale in the Trading API or SetShipmentTrackingInfo in the Merchant Data API to send eBay the shipment tracking number. eBay needs this for a number of reasons, such as keeping the buyer informed about the status of their purchases, and enabling customer service agents to help users resolve disputes.
Finally, he recommended that you test, test, and test, and then test some more! Test single transactions, orders, and different combinations of shipping and other details.
Type Change for Values in Sold and Active Inventory Reports
Starting with release version 657, all amount values in the Merchant Data API will be returned strictly as xs:double as specified in the schema and documentation. Currently, monetary amounts in the Sold Report and the Active Inventory Report use grouping separators where applicable (e.g. the comma in 1,234.55). The new values will be returned regardless of the version passed in the request.
A conversion summary for a few currencies can be seen below for reference:
657 and Later
657 and Later
This change was deemed necessary to:
- Stay in line with the standards established across other eBay APIs and Products. Sellers often use multiple tools, the data returned should stay as consistent as possible.
- Reduce the complexity of managing different currencies when engaging in Cross Border Trade (CBT).
- Correct any outstanding inconsistencies between the Schema and the reports.
Mismatched CONTENT-TYPE Will Now Cause Call Failure
As of January 15, 2010, eBay evaluates the CONTENT-TYPE header against the request payload format. If the CONTENT-TYPE value is incorrect for the payload, the request will fail. Previously, eBay did not validate the CONTENT-TYPE header in requests.
This HTTP header is optional. If you do not submit the CONTENT-TYPE header with your request, eBay will determine the content type from the payload.
The following table lists the correct CONTENT-TYPE header values for HTTP POST request formats:
Request Payload Format
text/xml (in conjection with SOAPAction header being sent - value can be anything)
See File Transfer Service: Making An API Call for more information about the call format for the File Transfer API.
Updates to Summer 2009 Release; Part 2 of 2.
Updates to Summer 2009 Release; Part 2 of 2.
On July 29, 2009, Laurel posted an announcement about the July 2009 updates. In this entry, we highlight part 2 of the features that were released since then
For the list of calls changed with each Trading API version, see the Trading API Release Notes.
Because there are many updates, the details have been split into two entries. The first part can be found here. This is the second entry and covers the following topics:
As a reminder, the first entry included: will link to part 1 entry.
If you would like the complete details on the July 2009 Update, please refer to the following links and to the API Release Notes.
- All features are not available to all Sellers, use the Trading call GeteBayDetails to find out which features are available for your site. As part of the seller release, some listing upgrades were removed for some sites, and some will be restricted to eBay Top-Rated Sellers or PowerSellers. The listing features include bold title, border, Featured First, Featured Plus!, gift icon, highlight, Homepage Featured, and ProPack. A new type, ListingFeatureDetails, has been added to the GeteBayDetails response that returns which listing features are available to the seller for the site. Another addition to the GeteBayDetails response, UpdateTime, reports the time of the most recent modification to any Detail.
- A type has been added to the Trading call ListingStartPriceDetailsType.MinBuyItNowPricePercent, which returns the minimum percentage difference between the start price and the Buy It Now price for a listing on the specified site. There is one exception: Use category details to find the percentage requirements for Motor Vehicles (using Site ID 100 - the eBay Motors site.)
- GetSellerEvents now returns variation details in Item.Variations, including StartPrice, Quantity, and QuantitySold, plus SKU and/or VariationSpecifics. Multiple variations are returned together in the same Variations node (similar to GetItem).
- To keep the GetSellerEvents response smaller, the variation specifics are not returned if the variation has a SKU.
- With RelistFixedPriceItem and ReviseFixedPriceItem, you can now use SKU to uniquely identify an existing variation, regardless of whether the listing has inventory tracking set to SKU.
- ReviseInventoryStatus now supports modifying variations when InventoryTrackingMethod is set to ItemID.
- For the site specified in the request, GeteBayDetails now returns variation constraints, such as maximum number of variations, in VariationDetails.
- GetUser now returns QualifiesForVariations (a boolean) to indicate whether the user is eligible to list with variations on the site specified in the request.
- In SetUserNotes, you can now set private notes for variations. These notes will be visible to the user for variations that are displayed in My eBay.
- GetMyeBayBuying and GetMyeBaySelling now return PrivateNotes for applicable variations. Depending on how the notes were set (what was specified in the SetUserNotes request), the variations may be returned within Variations or within Item
-  Shipping Insurance option has been removed from many sites. If shipping insurance is included in AddItem, it will be dropped with a warning, but won't fail. See the Release Notes.
-  Using My eBay, you can create an Exclude Ship-To List of the locations to where you will not ship items. Once set up, all items that you list on eBay will, by default, use the Exclude Ship-To List to exclude the locations you specified in the list. If a buyer's primary ship-to location is a location that you have listed as an excluded ship-to location (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on your item. Use GetUserPreferences to review the default set of excluded locations that you have set up in My eBay. Use GetUserPreferences to retrieve your global exclusion list. See the Release Notes.
-  Tracking for multiple package shipment for a single item. ShippingCarrierUsed and ShipmentTrackingNumber have been moved to a repeatable ShipmentTrackingDetails container. See the Release Notes.
-  More shipping carriers supported. The type for ShipmentType.ShippingCarrierUsed has been changed from ShippingCarrierCodeType to string. This enables sellers to specify a shipping carrier (via CompleteSale) other than the ones noted in ShippingCarrierCodeType.
- With a request version lower than 627, the value you specify for CompleteSale's ShippingCarrierUsed must be a value found in ShippingCarrierCodeType. If the request version is 627 or higher, you can specify the shipping carrier of your choice, even if it is not in the ShippingCarrierCodeType list, and GetSellingManagerSaleRecord will return that value. See the Release Notes.
-  Local Pickup: Shipping Time DSRs ignored, Shipping and Handling Charges MAY be ignored.
- In the Trading API LeaveFeedback call, DSRs left for Shipping Time will be ignored for all Local Pickup transactions. DSRs left for Shipping and Handling Charges will be ignored for Local Pickup transactions where the seller did not add any special handling fees. See the Release Notes.
- This change affects the following eBay sites: AU, Mn-AT, BE-FR, BE-NL, CA, CA-FR, FR, DE, HK, IN, Mn-IE, IT, MY, Motors, NL, PH, PL, SG, ES, Mn-CH, UK, US
-  Seller Status Now Returned by GetSellerDashboard. See the Release Notes.
- Avoid 1s and 2s
- Only domestic DSRs count
- [629 ] Top-Rated Seller Details Available via GetUser and Other Calls; SellerInfo.SellerLevel to Be Removed
- When Top-Rated Seller details became available in October (see Announcement), GetUser began returning fields that identify the seller as a Top-Rated Seller and gave details about the Top-Rated Seller program. These fields are already present and documented for GetUser and other calls. They include TopRatedSeller and TopRatedSellerDetails.TopRatedProgram, which identifies the Top-Rated-Seller programs for which the seller is qualified. See the Release Notes.
- When the Top-Rated Seller feature became active on the US, DE, and UK sites, SellerInfo.SellerLevel no longer returned results for those sites. Affected calls include GetUser, GetBidderList, GetSellerList, GetItem, and GetItemTransactions.
More categories are becoming catalog-enabled
When Good Till Canceled (GTC) listings are renewed, they will be checked for Return Policy and Handling Time. If these details are not included, the GTC listing renewal will fail. For more info, see this entry in the Forum.
December 17, 2009 in Best Practices, Categories and Item Specifics, Certified Provider, Client Alerts API, Developer Community, Documentation, Finding API, Large Merchant Services, Merchandising API, Product News, Shopping API, Trading API | Permalink
Updates to Summer 2009 Release: Part 1 of 2
On July 29, 2009, Laurel posted an announcement about the July 2009 updates. In this two part entry, we highlight the features that were released since then.(For the change details with each API version, see the API Release Notes.)
Because there have been many updates, this topic will be split into two entries.
This first entry includes:
The second entry (to be published on, or around, December 17) will include:
Items with Variations
-  Multi-Variation Listings: GetSellerEvents and Other Enhancements
-  Changes to ListingFeatureDetails and Some Listing Features to Be Removed and Restricted
Selling Manager Applications
- ShippingCarrierUsed: Type Change
- LeaveFeedback and Shipping API Detailed Seller Ratings (DSRs)
- Reminder: Return Policy and Handling Time Required When You Renew GTC Listings
If you would like details on the July 2009 Update, please refer to the following links and to the API Release Notes.
Please see the BestMatchItemDetails API release notes for details.
[1.2.0] New Feature: Gallery Plus Pictures
[1.2.0] Doc changes: Updated Value for SellerBusinessType Item Filter
Reminder of what changed in Best Match (Details)
- New listing performance score for Fixed Price to replace recent sales
- New multi-quantity and single-quantity Fixed Price listings will be given exposure in Best Match
- Titles are more important than ever
- Seller performance continues to count
- Shipping cost continues to count
- No changes to Auction-style listings
- Optimized by category
- As part of the Edit Live Items feature, a new TransactionID field was added to the GetItemRequest call. This new field will allow both Sellers and Buyers to retrieve a listing as it was at the time of a given purchase by invoking GetItem with a TransactionID in the request (even if the seller has made significant revisions to the listing, following the purchase).
- Sellers are also able to make revisions to their multi-quantity fixed price listings after a purchase has been made (currently, Sellers can not change their multi-quantity fixed price listings, after at least one item in the listing has been purchased).
- Sellers are able to view the updated listing for each transaction, but Buyers are only able to view the transactional version of a listing where they are the successful buyer. Past transactional views of an item will be available for up to 90 days from the date the transaction took place.
 Platform Notification changes and client alerts
- Changes to the GetItemTransaction API call may cause a change to the behavior of the following Platform Notifications: EndOfAction, AuctionCheckoutComplete, FixedPriceEndOfTransaction, CheckoutBuyerRequestTotal, FixedPriceTransaction, Checkout, FixedPriceTransactionForSeller, FixedPriceTransactionForBuyer, ItemMarkedAsShipped, and ItemMarkedAsPaid.
- The following Client Alerts may have a behavior change as a result of this project: EndOfAuction, FixedPriceEndOfTransaction, FixedPriceTransaction, ItemSold, and ItemWon. Each notification will now be based on the state of the item (a 'snapshot' of the item) at the time the transaction was created.
Finding API - see the Finding API release notes for details.
[1.1.0] New: Gallery Plus Pictures
[1.1.0] Updated Value for SellerBusinessType Item Filter
[1.0.1] eBay Top-rated Seller
With the launch of the Top-rated Sellers program, buyers can find items listed by the highest quality sellers on eBay based on the feedback of other buyers. The sellerInfo node in the search results (searchResult.item.sellerInfo) for the "findItems" calls now includes the topRatedSeller field to indicate (true or false) whether the seller of an item qualifies as an eBay Top-rated Seller. Additionally, a new TopRatedSellerOnly item filter has been added to limit search results to items listed by Top-rated Sellers only.
Note the following site restrictions:
- The searchResult.SellerInfo.topRatedSeller field in the response for the finding calls is supported for the following sites only: US (EBAY-US), Motors (EBAY-MOTOR), DE (EBAY-DE), AT (EBAY-AT), and CH (EBAY-CH).
- The TopRatedSellerOnly item filter is supported for the following sites only: US (EBAY-US), Motors (EBAY-MOTOR), UK (EBAY-GB), IE (EBAY-IE), DE (EBAY-DE), AT (EBAY-AT), and CH (EBAY-CH).
Top-rated sellers consistently receive highest buyers' ratings, ship items quickly, and have earned a track record of excellent service. eBay regularly reviews the performance of these sellers to confirm they continue to meet the program's requirements. See the Top-rated Sellers page on the eBay site for more information.
Trading API - See the Trading API release notes for details.
 Clarifications in Documentation for Unpaid Item Disputes
- Version 639 release notes surveyed various process changes for Unpaid Item Disputes.
- Support for the old process will be removed around March 2010, so please migrate your UPI dispute code to work with the new process.
- How do you know whether the newer or older process applies to your disputes or not? It is all about the request version. If you created a UPI dispute with a request version lower than 637, the old timelines apply and the various platform notifications for messaging are still supported. But if the request version is 637 or greater, the new timelines apply.
- Further, since AddDisputeResponse can no longer be used (for 637 or greater) for buyer or seller communication, these notifications are no longer triggered: BuyerResponseDispute, SellerRespondedToDispute.
- See Newer versus Older Unpaid Item Disputes Process - a before/after table of facts.
 New Features for 639
- Multiple-Package Details for a Single Item
- Selling Manager Calls: No Integration with eBay.com Is Required
- Unpaid Item Disputes: Process Change
GetSellerEvents now returns variation details in Item.Variations, including StartPrice, Quantity, and QuantitySold, plus SKU and/or VariationSpecifics. Multiple variations are returned together in the same Variations node (similar to GetItem).
December 2, 2009 in Best Practices, Categories and Item Specifics, Client Alerts API, Developer Community, Developer Education, Documentation, Feedback API, Finding API, Large Merchant Services, Platform Notifications API, Shopping API, Trading API | Permalink