XML Trading API Guide Version 817 Contents 2 Contents Copyright Notice 33 Release Notes 34 Welcome 35 Feedback and Support 35 Free Technical and Business Resources 35 Developer Technical Support 38 Other Contacts and Resources 39 About the Documentation 39 Intended Audience 40 How this Documentation is Organized 40 Related Documentation 41 Typographic Conventions 42 Diagram Conventions 43 Part I: Getting Started 44 Chapter 1: Product Overview 45 eBay Trading Web Services 45 eBay SDKs 46 Supported Use Cases 47 Types of Applications You Can Build 48 Listing Application 48 Seller Application 49 Gallery List Tool 49 API License Agreement and Usage 49 Chapter 2: System Requirements 50 Supported Client Environments 50 Where to Find the eBay Schema Files 51 URLs for the eBay Schema Files 51 Generating Interfaces and Proxies from a WSDL 52 URL for the API Gateway 52 Database Storage 53 Commonly Used Database Systems 53 Hardware Requirements 53 Next Steps 54 Version 817 Contents 3 Chapter 3: Executing Your First API Call 55 Chapter 4: Developing an eBay-Enabled Application 56 Planning Ahead 56 Planning for the Compatible Application Check 57 Following Best Practices 58 Selecting Fields to Retrieve 59 Working with the Output Selector 60 Best Practices for the Output Selector 61 Testing Applications 61 About eBay Login Credentials 62 Using the Sandbox 62 Creating a Test User 63 Generating Auth Tokens for Test Users 65 Testing Your Application’s API Access 66 Creating Stores in the Sandbox 67 Checklist for Going Live 67 Compatible Application Check 67 Supporting Compatibility Levels 71 Sandbox and Production Keys 71 Chapter 5: Invoking eBay Trading Web Services 74 Overview of the API Schema 75 Message Types 75 Core Components 78 Base Components 79 Release Versions 84 Interoperability Considerations 86 Routing the Request (Gateway URLs) 87 HTTP Headers (XML API Only) 87 SOAP URL Parameters (SOAP API and SDKs Only) 89 Standard Data for All Calls 92 Standard Input Data 92 Controlling the Amount of Data Returned 100 Security 101 Standard Output Data 104 Error Handling 107 Error Types 108 Customizing Your Application’s Error Handling Abilities 113 Compatible Application Check Requirements for Error Handling115 Getting Help When You Cannot Identify the Source of an Error115 The Object Model of the eBay SDK for Java 115 Version 817 Contents 4 eBay SDK for Java Libraries 115 Call Class Basics in the eBay SDK for Java 116 Chapter 6: Getting Tokens 117 Single-User Applications 117 Configuring the Consent Flow for Applications with Multiple Users117 Setting Up an Application to Receive Tokens 118 Set Application-Level Settings 118 Generate an RuName for Your Application 119 Set RuName-Level Settings 120 Getting Tokens for Applications with Multiple Users 121 Option 1: Client/Desktop Applications 122 Option 2: Web/Server Applications 123 Preparing the URL for User Sign-in 125 The Form of the Accept Redirect URL 125 Getting a Token via FetchToken 125 Using Tokens 127 About Tokens 127 What is a Token? 127 Life Span and Uniqueness 128 Watching for Token Expiration 128 Watching for Token Expiration 129 Token Expiration Causes 131 Part II: eBay Features Overview 132 Chapter 7: eBay Concepts 133 Basic Building Blocks 134 Summary of Building Blocks 134 Items and Listings 136 Categories (Introduction) 138 Choosing a Listing Option (Standard Way or with Product Details) 139 Users 145 Order Line Items 145 Feedback 145 eBay User Roles 147 Registered eBay Users 147 Application Developers 147 Sellers 148 Store Owners 148 Bidders and Buyers 148 Version 817 Contents 5 eBay Sites and Environments 149 The Sandbox and Production Environments 149 The US and International eBay Sites 150 PayPal 153 eBay Motors 153 eBay Stores 154 Shopping.com 154 Half.com 155 Affiliate Tracking Concepts 155 Earn Commissions 155 Affiliate Tracking Enabled for Several Trading API Calls 156 Part III: Selling Items on eBay 157 Chapter 8: Categories 158 Retrieving the Category Hierarchy for a Site 158 Maintaining Category Data 161 Checking the Category Hierarchy Version 163 Mapping Old Category IDs to Current IDs 163 Determining Category Support for Certain Features 168 Determining Whether a Category Supports Reserve Prices 169 Determining Whether a Category Supports Item Specifics 170 Determining Whether a Category Supports Product Details 170 URLs for Category Lists for Global eBay Sites 170 Retrieving Suggested Categories Based on Keywords 171 Specifying a Query for Suggested Categories 172 Chapter 9: Listing Items 174 Listing Policies 174 Seller Limits 174 Listing an Item 176 Required Information for eBay Listings 177 Optional Information for eBay Listings 181 Considering Best Match When Listing Items 184 Considering Best Match When Revising and Relisting Items 184 Specifying a Payment Method 184 Determining the Payment Methods Allowed for a Category 185 Using Integrated Merchant Credit Card (IMCC) 186 Site Visibility 187 Requiring Immediate Payment 187 Requirements for Using Immediate Payment with AddItem 187 Testing the Immediate Payment Feature 188 Version 817 Contents 6 Changing the Immediate Payment Requirement for an Item 189 Fees Resulting from Listing an Item 189 Fees Associated with Listing Features 189 Promotional Discounts 193 Chapter 10: Using PayPal 195 PayPal Overview 195 Offering PayPal Buyer Protection 196 Integrating PayPal With Your eBay Applications 197 Obtaining the PayPal ExternalTransactionID 197 The PayPal APIs 198 Using Instant Payment Notification 198 PayPal Transaction Reconciliation Report 199 Setting Up the PayPal Sandbox 199 Creating a PayPal Sandbox account199 Logging in to the Sandbox 200 Using test accounts 200 Linking PayPal Test Account to eBay Sandbox 205 Chapter 11: Describing Items in a Listing 206 Introduction to Pictures in Item Listings 206 Working with Pictures in an Item Listing 208 Uploading Pictures to EPS 209 Associating Pictures with an Item 209 Using a Stock Photo in an Item Listing 210 Including Pictures in the Description and Using a Camera Icon 211 Retrieving Picture Data 212 Copy of a Self-Hosted Picture To eBay Picture Services 212 Photo Fees 213 Including Pictures in the Search Results Gallery 213 Gallery, Gallery Plus, and Gallery Featured 213 Using an eBay Stock Photo as a Gallery Picture 214 Using Gallery Features on Sites with Free Gallery 215 Specifying an Item’s Condition 218 Using ConditionID to Specify an Item’s Condition 218 Describing Details About the Condition of Items That Are Not New 221 Adding or Changing ConditionID When Revising or Relisting 222 Retrieving a Listing’s Item Condition 223 Offering a Clear Return Policy 223 Listing an Item with a Return Policy 225 Retrieving an Item’s Return Policy 225 Version 817 Contents 7 Enabling Best Offer 225 Counteroffer Rules and Restrictions 226 Automatically Declining or Accepting an Offer 227 Anonymous Best Offer 228 Sellers’ Use of Best Offer 230 Additional Help for Best Offer 231 Enabling Multi-jurisdiction Sales Tax 231 Overview 231 Using Tax Tables 232 How Tax Tables Are Applied 232 Enabling Get It Fast 233 Identifying Listings that Benefit Nonprofits 234 API Support for eBay Giving Works 234 Benefits of Retrieving Giving Works Information 236 Other Ways to List Charitable Items 236 Listing Items as Private 237 Adult Only Listings 238 Listing Adult Only Items 238 Retrieving Adult Items 238 Featuring Vehicles on the Mobile.de Site 239 Using a SKU Identifier with Items 239 Using Feature Packs to Save on Upgrade Fees 240 Making Listings Available by Default on Another Site 241 Prerequisites for the International Site Visibility Listing Upgrade 242 Chapter 12: DE/AT New eBay Payment Process 244 Setting Payout Preferences on Site 244 Changes to Listing Calls in Trading API 244 Specifying Payment Methods No Longer Required 244 Changes to Order Retrieval Calls in Trading API 245 Using GetOrders to Distinguish New Payment Process Orders 245 Retrieving eBay Seller Payout Information 245 Limitations of Order Update Calls 246 New Payment Process APIs 247 Payout Details API 247 Order Adjustment API 247 Unmatched EFT Payments 248 GetOrders Changes Related to Over/Under EFT Payments 248 Refunds 249 Refunds Through the Site 249 Refunds Through the Order Adjustment API 249 Version 817 Contents 8 GetOrders Changes Related to Refunds 250 New Platform Notifications 250 ReadyToShip Notification 250 ReadyForPayout Notification 250 Unmatched EFT Payment Platform Notifications 251 Setting the API Compatibility Level 251 Categories Excluded from New Payment Process 251 Categories With Long Handling Time and/or Down Payments 252 Chapter 13: Using Description Templates 253 Layout Templates 254 Theme Templates 254 Theme Groups 255 Listing Designer Effects on the eBay API 256 Retrieving a List of Available Listing Designer Templates 257 Listing Items Using Listing Designer Templates 257 Retrieving Items that Have Assigned Listing Designer Templates 259 Displaying Item Descriptions with Layout Templates 259 Displaying Item Descriptions with Theme Templates 260 Revising and Relisting Items Using Listing Designer Templates 263 Chapter 14: Multi-Variation Listings 264 Overview of Multi-Variation Listings 265 Qualifications for Listing with Variations 267 Describing Variations in a Listing 268 Defining a Variation 269 Configuring Variation-Selection Widgets for Buyers (View Item) 273 Defining Pictures for Variations 275 Revising and Relisting with Variations 277 Changing the Category 277 Adding Variations 277 Deleting Individual Variations 277 Deleting All Varations 278 Modifying Existing Variations 278 Retrieving a Listing’s Variations 280 Buying Items in Multi-Variation Listings 280 Retrieving Order Line Items with Variations 281 Monitoring Listings and Orders with Variations 281 Identifying Variations in Member Messages 281 Chapter 15: Listing Items with Parts Compatibility 282 Parts Compatibility Supported Categories 282 Version 817 Contents 9 Checking Individual Leaf Categories 283 Identifying All Categories that Support Parts Compatibility 284 Parts Compatibility Listing Flow 285 Specifying Parts Compatibility by Product 286 Specifying Parts Compatibility Manually 289 Revising Parts Compatibilities for an Item 297 Retrieving Parts Compatibilities for Listed Items 299 Parts Compatibility Search Flow 302 Searching By Application 303 Searching By Specification 305 APIs for Parts Compatibility 306 Trading API 306 Product Services 307 Search API 308 Chapter 16: Want It Now 309 Retrieving Want It Now Posts 309 Searching for Posts with a Query 309 Searching for Posts by Category 310 Searching All eBay Sites for Posts 310 Paginating Search Results 310 Retrieving All Data for a Single Post 311 Responding to Want It Now Posts 311 Chapter 17: Shipping 312 Introduction to Shipping 312 Domestic and International Shipping 312 Shipping Carriers and Services 314 Shipping Types 315 Shipping Costs 316 Participation in the Global Shipping Program 317 Additional Resources 319 Working with Shipping in API Calls 319 Setting Versus Retrieving Shipping Details 319 Specifying Global Shipping in an Item Listing 320 Specifying Global Shipping-Related Item Attributes 320 Revising Shipping Details 321 Using Global Shipping Information After Checkout 322 Retrieving a Seller’s Global Shipping Records 323 Specifying Locations to Where You Ship 324 Using Shipping Rate Tables for Finer Control of Shipping Location Charges 325 Version 817 Contents 10 ShipToLocation(s) 325 Excluding Locations 326 US Listings and Package Size Limitations 326 Specifying Shipping Locations with the Global Shipping Program 327 Specifying Shipping Services 327 Required Domestic Shipping Service 327 Handling Time and Estimated Delivery Time 329 Enabling Get It Fast 331 Deprecated Shipping Services 334 Specifying Shipping Types and Costs 336 Mixing Shipping Types 336 Specifying Flat Rate Shipping 336 Specifying Calculated Shipping 341 Package Dimensions and Weight 342 Specifying Freight Shipping 346 UPS Rate Scales 349 Search Results and Shipping Costs 350 Specifying Other Costs 350 Packaging and Handling Cost 350 Shipping Surcharge 351 Taxes 351 Determining Shipping Costs for a Listing 352 Key Calls for Determining Shipping Costs 352 Determining Flat Rate Shipping Costs 353 Determining Calculated Shipping Costs 354 Determining Freight Shipping Cost 355 Other Shipping Features 355 Ensuring PayPal Seller Protection 355 Shipping Cost Discount Profiles 356 Specifying the Cash on Delivery Option in Shipping Details 361 Shipping Insurance 362 Chapter 18: Specialty Categories and Listings 366 Classified Ad Listings 366 eBay Real Estate Listings 367 Digital (Downloadable File) Listings 368 Ticket Listings 370 Basic Ticket Listing Requirements 371 Listing Tickets with Product Details 371 Filling in All Ticket Item Specifics Manually 373 Version 817