How to develop a selling application
This guide describes the tasks you need to complete in order to create an eBay Selling Application. While the descriptions assume you've never developed any eBay application, the guide is also geared towards the experienced eBay app developer.
This guide describes how to use the Selling APIs, a set of RESTful APIs. For details on making eBay REST calls, see Using eBay RESTful APIs.
Register as an eBay developer
If you are already registered, you can skip this section.
To be an eBay developer, you need to be a member of the eBay Developers Program. Membership is free, and is how you get permission to make eBay API calls, can use the Sandbox test environment, have access to eBay documentation and tech support, etc.
To register do:
- Go to the eBay Developers Program site at developer.ebay.com.
- In the top menu bar, click Sign In / Join (if the window is too narrow to show the menu, click on the box containing three horizontal lines where the menu would be):
- At the top of the content column, click Register.
- Fill out the basic registration information and confirm you've read the eBay API License Agreement.
- When registered, you're asked to enter an Application Title to register an application. You don't have to do this now; if you haven't registered an application, the registration page appears whenever you sign in. For now, just leave it blank. Application registration details are given later in this document.
You're now a member of the eBay Developers Program.
The eBay RESTful APIs
The latest eBay APIs are all RESTful. The short version of what that means is that you communicate with an eBay service by putting an API command inside of an HTTP request, sending the request to the service, and getting back an HTTP response that both states if the operation was successful and, if so, contains its results, if any.
Even if you are already familiar with REST and RESTful APIs, you need to read Using eBay RESTful APIs before writing your application. eBay's APIs have several unique aspects, such as authentication and how to get OAuth access tokens, error and warning handling, and so on. You cannot write a successful app without knowing how eBay APIs do these things.
Using eBay Using eBay RESTful APIs contains individual documents for its core topics. These are:
- Request Components: What makes up a REST request, and how you put one together.
- OAuth Access Tokens: eBay's REST interfaces use OAuth 2.0 access tokens for application authentication and user authorization. This topic tells you how to get, use, and refresh access tokens.
- Response Components: What makes up a REST response, and how you parse and interpret it.
- Handling Error Messages: This topic describes eBay's common format for how HTTP responses return error and warning messages.
- Testing in the Sandbox: How to test your application in the eBay Sandbox, a self-contained testing environment that doesn't affect live listings, user accounts, or bank accounts.
- Security and Your eBay Apps: What data needs to be secured, both on the client and service sides, and how it is secured on the service side and how you should secure it on the client side.
- Support for Application Development: Where and how to get help if you have problems developing your application.
Register your application
Registering your application is how you get its various ID values, client secret for authentication, and scopes.
- Go to the eBay Developers Program site at developer.ebay.com and sign in.
- If you haven't previously registered an application, you'll see an Application Title field to enter your application's name. Otherwise, you'll see the keyset you were previously issued for your registered application. If you only have a keyset for either the Sandbox or Production, click on Create a keyset under the other type to get a keyset for that environment. The rest of this list assumes you are registering your first application.
- Enter the name of your application in the Application Title field.
- When you hit Return, "Sandbox" and "Production" appear under the title, with both giving you the option to create a keyset. Your application will have separate ids/keys for the Sandbox test environment and the Production environment. You can get both now, or just the Sandbox and return later for the Production keys.
- When you click Create a keyset, you're asked to confirm the primary contact information. Once you do this, you'll see the application's App ID, Dev ID, and Cert ID for whichever of the Sandbox or Production keys you created.
- Store these values in a secure location. You can also see them by going to the Developers Program top right menu bar and clicking on Hi <eBay Developer id> and then, in the pull-down menu, clicking on Application access keys.
Familiarize yourself with the eBay Checklist for Going Live
Go through the eBay Checklist for Going Live. While you'll go through it again after writing your application, you should write your application in compliance with its items and requirements. Note that it includes being familiar with other documents, such as the eBay API License Agreement, that also specify constraints on how and what your application can do.
Now that you've done the prep work, and familiarized yourself with the various constraints on your code from the Checklist For Going Live and Using eBay RESTful APIs, it's time to start writing your application.
With respect to eBay, you'll need to write:
- Code that authenticates the user and application with eBay.
- Code that calls an API command (i.e. creates and makes an HTTP request).
- Code that deals with an API command's response (i.e. receives and parses an HTTP response).
- Code that logs your API calls and responses.
- Code that conforms to eBay's standards and practices.
User and application authentication
Your code has to handle authenticating both your application and its users with eBay. The OAuth access tokens section of the Using eBay RESTful APIs document explains how to do this.
Calling an eBay API command
First, look at the documentation for the specific API command you want to call and determine its URL and HTTP headers.
You can use the API Test Tool to more fully understand a particular command. It allows you to select an API, then a call from that API, and run a sample version of the call in either the Sandbox or Production. It shows you both the complete call, including endpoint, headers, and payload, and the complete response, again including both headers and the results payload.
Receiving an HTTP response for an eBay API command
First, you need to write general code to unpack the HTTP response into its component status code, headers, and content. You probably want to do different things depending on whether the status code indicates success or not.
Your code must also be able to detect and handle errors and warnings. For details about the eBay API error/warning system, see the Handling error messages section in Using eBay RESTful APIs. Each API call's reference documentation lists the possible error ids (called "Error Codes" there) the call can return. You should also write default code to handle the case of a new or mistakenly undocumented error occurring, just to be safe.
Note that specific warnings are not listed in the API call documentation. Your code will need to handle warnings as a general condition.
Logging for eBay
In the event of a problem with eBay APIs, we strongly urge you to log the following for each request and response. If you ever need to contact eBay Support, they will want this information.
- HTTP request: The URL, the HTTP headers, and the payload.
- HTTP response: The HTTP status code, the HTTP headers, and results content.
Essentially, you want to log all of both every request and every response.
Conforming to eBay standards and requirements
Remember, your application's overall code must comply with what's specified in the eBay Checklist for Going Live and the documents it references, the Security section of Using eBay RESTful APIs, and so on.
Testing in Sandbox
Before your application goes live, you should thoroughly test it in eBay's Sandbox, a self-contained virtual testing environment that mimics eBay Production.
The Sandbox is a shielded space that processes mock eBay transactions generated by your eBay API requests without touching any live eBay listings, user accounts, or bank accounts. The Sandbox lets you fully test and debug your application before running it in eBay's live Production environment.
For details on using Sandbox, see the Testing in the Sandbox section in Using eBay REST APIs.
Check your application against the Checklist for Going Live
If you followed this document's development flow, you should've been developing your application in consideration of the items on the eBay Checklist for Going Live. If you've not been keeping track that you fulfilled the checklist items, go through them and make sure your application is in compliance with them.
Run AppCheck on your application
In order to increase the number of eBay API calls your application can make per day beyond the default values, you need to run the Compatible Application Check (AppCheck) on your application.
Much of what AppCheck is looking for is compliance with the eBay Checklist for Going Live and the API License guidelines and prerequisites. You'll also need to know your application's estimated call peak (both hourly and daily) for each API call it could make.
When you submit the AppCheck form, you should hear back from eBay within 3-5 business days. While we may have further questions, the process should be finished in 5-7 business days.
Passing AppCheck also authorizes you to use the eBay Compatible Application logo.
Technical support from eBay
If you need technical support for an eBay-related aspect of your application, the various types of support (both free and premium) and how to use them, are described in Using eBay RESTful APIs in its Support for Application Development topic.