Making a Trading API Call
To perform a particular task with the Trading API (e.g., list an item), you need to send a request using a call. The call names are fairly self-explanatory, like AddItem — which lists an item. The schema defines the messages that you can use to access the eBay database. The API uses request-response style operations.
This document explains how to make a Trading API call. It provides an overview of the formats and parameters you can use with the Trading API.
Supported Client Environments
The eBay APIs have been tested with the Java and Microsoft .Net environments. For information and downloads, please see the following sites.
For Java development:
The Apache Software Foundation
Note: If you use Apache Axis, you only need the .jar files that are necessary for consuming Web services (i.e., on the client side). However, it may be convenient to install the product on an application server so that you can test your ability to post SOAP messages to a server other than eBay's SOAP API gateway. The standard installation instructions for Apache Axis assume you are installing the product on an application server and include information about where to find a free application server.
For .NET development:
If you choose to try a different client, please be sure it supports document-style messaging (as we do not use RPC-style messaging). Also, eBay APIs only support the UTF-8 encoding scheme.
For information about programming using the Java, .NET or Python eBay SDKs, see eBay SDKs.
Call Structure and Routing
UTF-8 Character Set
Applications must use the UTF-8 encoding scheme (not ISO-8859-1). All applications must validate text strings specified in the body of each request to make sure the characters are UTF-8 compliant. It is not enough to simply transmit information to eBay in UTF-8 format; you must convert the characters provided by users (e.g. in item descriptions, street addresses, names of persons) to UTF-8 if they were received in a non-UTF-8 charset (e.g. from a browser for which the encoding was not UTF-8) or stored in your database in a non-UTF-8 charset.
See the article "Working with UTF-8: charsets, conversion, tools" in the Knowledge Base for additional information
The Trading API expects calls to use the HTTP POST call method.
The HTTP POST call method supports the use of XML format requests. The XML request/response format follows standard XML syntax conventions. Please see w3schools.com XML Syntax Rules for more information.
<GetItemRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <ItemID>110043671232</ItemID> </GetItemRequest>
The call response for XML requests is in XML format only.
The HTTP POST call method also supports the use of SOAP format requests. SOAP versions 1.1 and 1.2 are both supported. The SOAP request/response format follows standard SOAP syntax conventions. Please see w3schools.com SOAP Tutorial for more information.
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope" xmlns="urn:ebay:apis:eBLBaseComponents"> <soap:Header/> <soap:Body> <GetItemRequest> <ItemID>110043671232</ItemID> </GetItemRequest> </soap:Body> </soap:Envelope>
The call response for SOAP requests is in SOAP format only.
All Trading API requests that you execute must be sent to the Sandbox or Production Gateway for the API. You specify the gateway URI (endpoint) in the request. If you are using the SOAP API, you append a query string that tells eBay how to route your request.
The Gateway URIs for Sandbox data and API calls are:
XML API Sandbox Gateway URI
SOAP API Sandbox Gateway URI
The Gateway URIs for live, production data and API calls are:
XML API Production Gateway URI
SOAP API Production Gateway URI
eBay requires that you use HTTPS/SSL when you execute calls in the Production environment. This ensures that data can be transferred securely between your application and the eBay platform. Although Sandbox data is simulated, you also need to use HTTPS/SSL when you execute calls in the Sandbox.
Note that although some of your developer keys are optional for certain calls, the full set of developer keys is required for GetTokenStatus and RevokeToken API calls. The tables in this section will give you more information about when specific information is required for a call.
See The Production and Sandbox Environments for general information about working in the Sandbox and Production environments.
Note: In the WSDL for the SOAP API, the service locator specifies eBay's Production SOAP gateway URI (the physical location of the service endpoint). In the service clause of the WSDL, you can see that the name of the service locator will be derived from
eBayAPIInterfaceService. However, as the same WSDL is used both in the Sandbox and in Production, you should pass in the service endpoint yourself rather than obtaining it from the service locator.
HTTP Headers (XML API Only)
To properly route an XML API request to the appropriate destination within eBay, pass the following information in the HTTP headers. (If you're using the SOAP API, .NET SDK, or Java SDK, see SOAP URL Parameters (SOAP API and SDKs Only).)
Required if you do not supply an eBay Authentication token using the RequesterCredentials field.
This header supports the use of OAuth tokens for user authorization. To authorize the request, supply a valid User access token for the value of this header. For details on User access tokens, see OAuth access tokens.
||Always||The eBay release version that your application supports. See the eBay Schema Versioning Strategy for information about how the version affects the way eBay processes your request.|
||Conditionally||Your Developer ID (DevID), as registered with the eBay Developers Program. The developer ID is unique to each licensed developer (or company). This value is only required for calls that set up and retrieve a user's authentication token (these calls are: GetSessionID, FetchToken, GetTokenStatus, and RevokeToken). In all other calls, this value is ignored.. If you lose your keys you can retrieve them using the View Keys link on your My Account page. Here is the direct link to the Keys page (requires signin): https://developer.ebay.com/DevZone/account/keys.asp|
||Conditionally||Your application ID (AppID), as registered with the eBay Developers Program. This value is only required for calls that set up and retrieve a user's authentication token (e.g., FetchToken). In all other calls, this value is ignored. Do not specify this value in AddItem and other calls that list items. The application ID is unique to each application created by the developer. The application ID and certificate ID are issued in pairs. Multiple application/certificate ID pairs can be issued for a single developer ID.|
||Conditionally||Your certificate ID (CertID), as registered with the eBay Developers Program. This value is only required for calls that set up and retrieve a user's authentication token (e.g., FetchToken). In all other calls, this value is ignored. Do not specify this value in AddItem and other calls that list items. The certificate ID is unique to each application created by the developer.|
Canonical name of the call you are using (e.g., AddItem). To be routed correctly, the value must match the request name. For example, if you are using
eBay site to which you want to send the request. See SiteCodeType for a list of valid site ID values.
This is usually the eBay site an item is listed on or that a user is registered on, depending on the purpose of the call. See Specifying the Target Site to understand how the site ID may affect validation of the call and how it may affect the data that is returned. For calls like AddItem, the site that you pass in the body of the request must be consistent with this header. Note: In AddItem, you specify the 2-letter site code. In this header, you specify the numeric site ID.
||Recommended||Specify "text/xml". Sending any other value might cause the call to fail. Note: If you use a library that sets the ContentType header by default, make sure it uses "text/xml".|
||Recommended||The length of the XML request string you are sending. Used by eBay to determine how much data to read from the stream.|
SOAP URL Parameters (SOAP API and SDKs Only)
To properly route a SOAP API request to the appropriate destination within eBay, pass the following information in the URL query string.
A set of Sandbox Keys (AppId, DevId, CertId) is issued to you by Developer Relations when you first join the Developers Program. The application ID (
||This is the version of the payload schema you are using. The version should match the version you pass in the message body. See Release Versions for details.|
This is the canonical name of the request (e.g.,
||This is the site that item of interest is (or will be) listed on or (for requests that get/set user information) that the requesting or target user is registered on. See Specifying the Target Site for more information about sending requests to international sites and special sites. See Field Differences for eBay Sites for current site IDs.|
||Specify Routing=new to direct the call to a single namespace server.|
Header recommendations: set Content-Type to "application/soap+xml", and set SOAPAction to "".
Theoretically, the URL resulting from the SOAP request would look something like this (if hard-coded in your application):
Note: If you use a third-party tool for monitoring or logging message data, the tool may require you to pass the URL into your application in a different manner. Please refer to the tool's documentation for instructions.
The following example applies to the SOAP API and shows one way to specify the routing information. The query arguments are hard-coded here for illustration purposes only. This example is in Java, but the logic would be similar for any programming language.
// Define the endpoint (e.g., the Sandbox Gateway URI) String endpoint = "https://api.sandbox.ebay.com/wsapi"; // Define the query string parameters. String queryString = "?callname=AddItem" + "&siteid=0" + "&appid=myappid" + "&version=1081"; + "&Routing=new"; String requestURL = endpoint + queryString; EBayAPIInterfaceServiceLocator sl = new EBayAPIInterfaceServiceLocator(); EBayAPIInterface privBinding = sl.geteBayAPI(new URL(requestURL)); ((EBayAPISoapBindingStub)privBinding).setTimeout(60000);
Note: The eBay WSDL defines the message signatures along with the service location information. See the eBaySvc.wsdl file for more information. In the WSDL, the message elements define the request and response messages and the data types to use in the body of those messages. The message names are the same as the data type element names (e.g.,
AddItemRequest). In the portType clause, you'll see the name of the service definition interface (the interface you'll use to access operations) will be derived from
eBayAPIInterface. This interface specifies each logical operation (e.g.,
AddItem) and indicates that they are bidirectional (request-response). In the
binding clause, you'll see that the name of the proxy that implements the service definition interface will be derived from
eBayAPISoapBinding. The binding indicates that each operation needs to be transmitted using the SOAP document-literal style. In the
service clause, you'll see that the name of the service locator in the Production environment will be derived from
eBayAPIInterfaceService. The service locator specifies the physical location of the service endpoint (i.e., the URI of the service provider—eBay's Production SOAP API gateway). You will need to override this value when executing calls in the Sandbox. It is therefore a good idea to set the endpoint yourself in general, rather than obtaining it from the service locator.
Specifying the Target Site
The eBay site you specify in your requests affects the business logic and validation rules that are applied to the request. For example, the eBay US site and eBay Germany site follow different rules due to differences between US and EU law, buyer behavior, and other factors.
Where to Specify the Target Site (XML and SOAP)
For some requests, you need to specify the site twice:
- (All requests) Use the numeric site ID to route the request to the correct site (see Service Endpoints). This is usually the site that the item is listed on or that the user is registered on (depending on the purpose of the call).
- To route the request in the XML API, specify the numeric ID of the target site in the X-EBAY-API-SITEID HTTP header.
- To route the request in the SOAP API, specify the numeric ID of the target site in the URL.
SiteCodeType) in the body of the request as appropriate for the type of call you're using.
For example, in AddItem, specify the target site by using the Item.Site input field. The site you specify for the item should match the site you specify in the HTTP header or URL.
Where to Specify the Target Site (eBay SDK)
If you are using an SDK, specify the ID of the target site in the Site property of the ApiContext object that is used to make the call. The ApiContext object is reusable. An application will typically create and configure an ApiContext object once and then use it for all API calls made for the duration of an application session. This means the site ID usually only needs to be set once if you are using an SDK. Use a value in the site code list (
SiteCodeType). You can change the site ID for a particular call using the ApiContext.setSite( ) method (in the eBay SDK for Java) or using the value of the ApiContext.Site property (in the eBay SDK for .NET).
For some calls, such as AddItem, you need to specify the target site when you list an item (in the Item.Site property). The site you specify for the item should match the site you specified in the ApiContext.Site property. When you set Item.Site, use a value in the site code list (
Why the Target Site Matters
The site you specify in your requests affects the business logic and validation rules that are applied to the request. For example, the site can affect data like the following:
- The list of available categories (including the availability of categories that support item specifics, product details, and VAT/business items)
- International business requirements (e.g., whether a listing is subject to VAT)
- Values returned in converted prices (e.g., Item.ListingDetails.ConvertedStartPrice)
- Shipping cost calculations
- Default units of measure (e.g., pounds vs. kilograms)
- Item-related time stamps that are displayed on the eBay Web site
For example, item revision times might use localized time stamps such as PDT. These time stamps are not necessarily apparent via the API, which expresses time values in GMT (see About GMT)
- Localization of certain standardized string values within listing details
- The language of error and warning strings that are returned (see ErrorLanguage below)
- Other data (which varies by the call you are using)
In some cases, the rules are determined by a combination of the site, the user's registration address, and other information. (The documentation explains these dependencies on a case-by-case basis.)
The site you specify when using AddItem can also affect the visibility of the listing in some types of searches. For example, if you call GetItem for the US site, you don't see listings that appear in categories of the UK site.
The site you specify does not necessarily act as a filter for limiting the data returned. It depends on the nature of the request:
- Item IDs are unique across all sites (i.e., an item ID on the UK site would not be re-used for a different listing on the US site). This means calls that filter data by the item ID (e.g., GetItem) retrieve the same listing no matter which site you specify. (This is important, because sometimes you'll only know the item ID, but you might not happen to know which site the item was listed on.) In such cases, the site value you pass only affects site-specific data like ConvertedStartPrice (as described above).
- Similarly, user IDs are unique across all sites. This means that calls that retrieve data by a user ID (e.g., GetUser and GetSellerList) retrieve the data no matter which site the user is registered on and which site you specify in the request. (Again, this is important because you may not know which site the user is actually registered on.)
- Site-specific user information (such as a subscription to Selling Manager Pro on the US site) depends on the site you specify in the request.
- As indicated earlier, category IDs are not unique across all sites, and each site has variations in the category hierarchy. Therefore, the site information has a filtering effect when retrieving category-based data and an impact on validation when you list items. Calls like AddItem will fail if you specify a category ID that is incorrect for the specified site. Calls that filter results by category ID (e.g., GetCategories) generally only retrieve data that is applicable to the site that you specify in the request.
- Other types of user information (such as registration date) does not depend on the site you specify in the request.
While the usefulness of including the Item.Site field in addition to the HTTP header or URL may not be externally apparent for some calls, other calls may fail or may not behave as expected if you do not pass the site data in the body or if the value you pass does not match the value in the HTTP header or URL.
Therefore, we strongly recommend that you always specify the site when you list an item. For some applications, it may be convenient to rely on reusable classes, modules, or functions to set the site ID in the HTTP header or URL and the Item.Site field the same time so that they always match each other.
Specifying the Schema Version
In each request, you need to pass the version of the schema you are using. How you do this depends on which format you're using:
- In the SOAP API, the version is defined on the abstract request and response types. Pass the version in the Version field of the request payload.
- In the XML API, the version is defined in the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header (see HTTP Headers (XML API Only)).
See the eBay Schema Versioning Strategy for information about how the version affects the way eBay processes your request.
Note: To distinguish the current international version from the US version, this documentation sometimes appends the letter "i" to the release number. Please do not include the "i" when passing the version number to eBay. The
AbstractRequestType defines a
Version element. However, that input element is only used by the SOAP API; it is ignored by the XML API.
eBay returns the version of the schema we used in each response's Version field. This lets you confirm that we used the version you expected.
Each response also contains a Build field. This refers to the specific software build that eBay used when processing the request and generating the response. Developer Support may request the build information when helping you resolve technical issues.
The following subsections describe how to make secure API requests.
Before a user on the eBay site can perform any operation of significance (list an item, bid on an item, etc.), that user must log in to the site using an eBay user name and a password. Similarly, for the user of an application to make an API call, it must be determined that application end-user is authorized to do so. Making this determination is called authentication. On the eBay site, authentication is accomplished by the user signing in. When an application is acting on a user's behalf, authentication is accomplished by the application passing authenticating data in the API call's request. eBay uses the user authentication data passed with the call's request to identify the requesting user and authenticate the user before performing the requested action.
For many API calls (as is the case with many user activities on the eBay site) this user authentication is merely a verification that the user is a registered eBay user. For instance, anyone who is a registered user may retrieve and view item data with GetSellerList. However, some operations require that the user in question is also verified to be a particular user. For example, only an item's seller is authorized to re-list a particular item. So authentication for an item re-list operation using RelistItem both verifies that the requester is a registered eBay user and is the item's seller.
There are two types of authentication data that an application may pass to eBay in a call's request. One is a user's authentication token, as shown in the samples in Authenticating with an Authentication Token.
The other is a pairing of a user's session ID and the full keyset of your developer credentials, but this is only required for FetchToken, the call that you use to obtain the user's authentication token in the first place. The full set of developer keys is also required for the GetTokenStatus, RevokeToken, and GetSessionID API calls. See Authenticating with a Full Keyset and Session ID.
Authenticating with an Authentication Token
An application can authenticate a requesting user by passing with an API call's request an eBay Authentication token. For more detailed information on getting and renewing Authentication tokens, see Getting Tokens.
Note: In addition to Authentication tokens, the Trading API also supports OAuth as a way to authorize requests. To use OAuth, supply a User access token in the X-EBAY-API-IAF-TOKEN, as described above in HTTP Headers. If you do authorize requests with OAuth tokens, do not include the RequesterCredentials field in your requests as described in the rest of this section.
In the SOAP API, to authenticate the requester for a call using an authentication token, pass the token in the header for the request. The example below shows the header element that contains the token, as well as the Developers Program keys:
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="https://www.w3.org/2001/XMLSchema" xmlns:ebl="urn:ebay:apis:eBLBaseComponents"> <soap:Header> <ebl:RequesterCredentials soapenv:mustUnderstand="0"> <eBayAuthToken>
In the XML API, to authenticate the requester for a call using an authentication token, pass the token in the
eBayAuthToken element within the
RequesterCredentials element in the request XML.:
<?xml version="1.0" encoding="utf-8"?> <GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <RequesterCredentials> <eBayAuthToken>
A sample delivered with the eBay SDK for Java shows how to add this element in Java and populate it with an authentication token. Specifically, see the
Global.java file in the
signingredirect folder in the eBay SDK for Java:
eBay SDK for Java
The following example, which applies to the SOAP API, shows how to add this header child element in C# and populate it with an authentication token.
service.RequesterCredentials = new CustomSecurityHeaderType(); // Specify the authentication token for the requesting user service.RequesterCredentials.eBayAuthToken = UserToken;
If you are using the eBay SDK for Java, pass the authentication token for the requesting user in the ApiCredential property of the ApiContext object used for the call. The ApiContext.ApiCredential.eBayToken property holds the authentication token for a call. The authentication token is conveyed in the variable
token, which is of type
string. For an example in Java, see the
Global.java file in the
signingredirect folder of the eBay SDK for Java:
eBay SDK for .NET
In the eBay SDK for .NET, pass the authentication token for the requesting user in the ApiCredential property of the ApiContext object used for the call. The ApiContext.ApiCredential.eBayToken property holds the authentication token for a call. In the example below, the authentication token is conveyed in the variable
token, which is of type
// Create the ApiContext object and specify the credentials ApiContext context = new ApiContext(); context.ApiCredential.ApiAccount.Application = "YourAppId"; context.ApiCredential.ApiAccount.Certificate = "Your"; context.ApiCredential.ApiAccount.Developer = "YourDevID"; context.ApiCredential.eBayToken = "ABC...123";
Authenticating with a Full Keyset and Session ID
The use of a full application keyset (
AuthCert) to authenticate the requester of a call is not required for most calls.
However, a few calls do require the full keyset. These exceptional calls are all associated with authentication and tokens: FetchToken, RevokeToken, GetTokenStatus, and GetSessionID.
For these calls, you pass the application's full keyset along with the request.
For SOAP and XML, you pass the keyset in the header for the request. The FetchToken examples for SOAP and XML below show header elements that contain the keyset-based authentication data:
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="https://www.w3.org/2001/XMLSchema" xmlns:ebl="urn:ebay:apis:eBLBaseComponents"> <soap:Header> <ebl:RequesterCredentials soapenv:mustUnderstand="0"> <Credentials> <DevId>MyDevId</DevId> <AppId>MyAppId</AppId> <AuthCert>MyCertId</AuthCert> </Credentials> </ebl:RequesterCredentials> </soap:Header> <FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <
SessionID> <Version>1081</Version> </FetchTokenRequest> </soap:Envelope>
X-EBAY-API-COMPATIBILITY-LEVEL: 613 X-EBAY-API-DEV-NAME:YourDevID X-EBAY-API-APP-NAMEYourAppID X-EBAY-API-CERT-NAME:YourCertID X-EBAY-API-CALL-NAME:FetchToken X-EBAY-API-SITEID:0 Content-Type:text/xml Request Payload: <?xml version="1.0" encoding="utf-8"?> <FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents"> <Version>1081</Version> <SessionID>MySessionID</SessionID> </FetchTokenRequest>
A sample delivered with the eBay SDK for Java shows how to pass authentication data based on your eBay Developer's Program credentials in Java. Specifically, see the
ClientAuthenticationHandler.java file in the
handler folder of the eBay SDK for Java:
eBay SDK for Java
If you are using the eBay SDK for Java, pass your eBay Developer's Program credentials within an API call request in the ApiCredential property of the ApiContext object. The ApiCredential object has an ApiAccount property to contain the application's credentials and an eBayAccount property to hold the requesting user's eBay Developer's Program credentials. These are used to authenticate the user for the call. Variables are used for the application's credentials (
mCert) and for the eBay Developer's Program credentials. The variables are all of type
eBay SDK for .NET
If you are using the eBay SDK for .NET, pass your eBay Developer's Program credentials within an API call request in the ApiCredential property of the ApiContext object. The ApiCredential object has an ApiAccount property to contain the application's credentials and an eBayAccount property to hold the requesting user's eBay Developer's Program credentials, which are used to authenticate the user for the call. The variables used to express the application's credentials (
cert) and the variables containing the eBay Developer's Program credentials are all of type
Using the eBay Schema Files
The XML and SOAP versions of the Trading API are based on the same schema. If you are using the XML API, you can use the ebaySvc.xsd file for request validation and in conjunction with some XML tools that recognize the format. If you are using the SOAP API, you will need to generate eBay API interfaces and proxies from the ebaySvc.wsdl file.
URLs for the eBay Schema Files
You can access a particular version of the eBay schema using an URL with the following format, where
VERSION is the version identifier of the release:
The version identifier can be:
- A number (for example,
835) — This is the version number of a particular schema file (a release number).
latest— This always points to the schema with the highest version number.
For example, you would use the following URLs to access version 1081 of the schema. Note: Only the last 8 versions of the schema are available.
URL for the ebaySvc.xsd
URL for the ebaySvc.wsdl
If 1081 were the latest version, it would also be available here:
All releases have odd-numbered versions. Older versions are periodically deprecated, which means they are no longer supported. See the eBay Trading API Schema Versioning Strategy for details about how deprecation works for the Trading API and a list of supported versions.
Each time we release a new version of the eBay schema, we add a new directory with a new version number, and point the "latest" URL to the new version. That is, the schema file in the "latest" directory changes for every release, and the schema files in the numbered directories do not change.
If you are using the SOAP API and you do not plan to update your application each time a new version of the WSDL becomes available, you should use the URL with the numbered version identifier. If you plan to always retrieve the latest changes available, it may be more convenient to use the URL with the "latest" version identifier.
See Release Versions and, for the SOAP API, see When to Update the Schema for additional information about versioning. If you use an IDE that recognizes WSDL files and displays the annotations, you may find it useful to browse the eBay WSDL file. You can also find the type annotations in the Type Reference (see Related Documentation).
Generating Interfaces and Proxies from a WSDL
If you are using the SOAP API, please refer to your SOAP client documentation for information about how to generate eBay API interfaces and proxies from the eBay WSDL.
The following example shows a simple way to generate Java source files from the eBay WSDL (using a Windows command prompt). In this example, the command-line arguments are wrapped to fit the width of the page. Because the eBay WSDL is so large, the timeout for the command is disabled with -O -1 (Note: the letter O, not the number 0). In practice, the information would all be entered on one line.
java org.apache.axis.wsdl.WSDL2Java -o src -O -1 https://developer.ebay.com/webservices/835/eBaySvc.wsdl
If you are using Microsoft Visual Studio .NET, follow the application's instructions to add a Web Reference to your solution. Specify the eBaySvc.wsdl URL as the Web service URL.