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.

Topics:

Supported Client Environments

Call Structure and Routing

Call Parameters

Security

Using the eBay Schema Files

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:

Oracle Corporation
https://www.oracle.com/technetwork/indexes/downloads/index.html

The Apache Software Foundation
https://axis.apache.org/axis2/java/core/

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:

Microsoft Corporation
https://www.microsoft.com/net/downloads

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

Topics:

UTF-8 Character Set

Call Formats

Service Endpoints

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

Call Formats

The Trading API expects calls to use the HTTP POST call method.

XML

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.

SOAP

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.

Service Endpoints

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

https://api.sandbox.ebay.com/ws/api.dll

SOAP API Sandbox Gateway URI

https://api.sandbox.ebay.com/wsapi

The Gateway URIs for live, production data and API calls are:

XML API Production Gateway URI

https://api.ebay.com/ws/api.dll

SOAP API Production Gateway URI

https://api.ebay.com/wsapi

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 Understand 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.

Call Parameters

Topics:

HTTP Headers (XML API Only)

SOAP URL Parameters (SOAP API and SDKs Only)

Specifying the Target Site

Specifying the Schema Version

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).)

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.

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):

https://api.ebay.com/wsapi?callname=AddItem&siteid=0&appid=myappid&version=1081&Routing=new

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.

For a list of valid site names and IDs, call GeteBayDetails or see the SiteCodeType documentation.

Where to Specify the Target Site (XML and SOAP)

For some requests, you need to specify the site twice:

1. (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.
2. (Some requests) Use the site name (see 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 (SiteCodeType).

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.
• See Base Components.
• See SOAP URL Parameters (SOAP API and SDKs Only).
• 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.

Security

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 Working with token/authentication calls.

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>
          ... AUTHENTICATION TOKEN GOES HERE ...
      </eBayAuthToken
    </ebl:RequesterCredentials>
  </soap:Header>
... Call body ...
</soap:Envelope>

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> Token goes here </eBayAuthToken>
  </RequesterCredentials>
  <Version>1081</Version>
</GeteBayOfficialTimeRequest>

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

https://developer.ebay.com/develop/ebay-sdks/java-sdk

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

https://developer.ebay.com/develop/ebay-sdks/net-sdk

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 string.

// 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 (DevID, AppID, and 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>MySessionID</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

https://developer.ebay.com/develop/ebay-sdks/java-sdk

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 (mDevID, mAppID, and mCert) and for the eBay Developer's Program credentials. The variables are all of type String.

eBay SDK for .NET

https://developer.ebay.com/develop/ebay-sdks/net-sdk

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 (devID, appID, and cert) and the variables containing the eBay Developer's Program credentials are all of type string.

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:

ebaySvc.xsd

https://developer.ebay.com/webservices/VERSION/ebaysvc.xsd

ebaySvc.wsdl

https://developer.ebay.com/webservices/VERSION/ebaysvc.wsdl

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

https://developer.ebay.com/webservices/1081/ebaysvc.xsd

URL for the ebaySvc.wsdl

https://developer.ebay.com/webservices/1081/ebaysvc.wsdl

If 1081 were the latest version, it would also be available here:

Latest ebaySvc.xsd

https://developer.ebay.com/webservices/latest/ebaysvc.xsd

Latest ebaySvc.wsdl

https://developer.ebay.com/webservices/latest/ebaysvc.wsdl

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.

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.