Using the SOAP version of the Trading API

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. For additional information, refer to XML SOAP.

<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope" xmlns="urn:ebay:apis:eBLBaseComponents">
<soap:Header/>
<soap:Body>
<GetItemRequest>
<ItemID>1***********2</ItemID>
</GetItemRequest>
</soap:Body>
</soap:Envelope>

The call response for SOAP requests is in SOAP format only.

Gateways

All Trading API requests must be sent to either the Sandbox or Production Gateway for the API using the appropriate URI:

Sandbox Gateway URI: https://api.sandbox.ebay.com/wsapi
Production Gateway URI: https://api.ebay.com/wsapi

Note: The service locator in the WSDL specifies eBay's Production SOAP gateway URI (i.e., 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.

A query string is then appended to the URI that instructs the system how to route the request.

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.

Refer to Understand the Sandbox and Production environments for general information about working in the Sandbox and Production environments.

SOAP query parameters

Refer to the following table for URL query string information that must be passed in to properly route a SOAP API request to the appropriate destination within eBay:

Key	Value
`version`	This is the version of the payload schema you are using. The version should match the version you pass in the message body.
`callname`	This is the canonical name of the request (e.g., `AddItem`). The routing service cannot look within the message body to determine the request type. Therefore, although the message itself will identify the request you're making, this information is also required in the URL.
`siteid`	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. Refer to Specify the target site for more information about sending requests to international sites and special sites.
`Routing`	Specify `Routing=new` to direct the call to a single namespace server.

A typical SOAP request should resemble the following:

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

SOAP headers

SOAP headers should only be used when issuing the following four token-related calls:

When making these calls, a developer's keyset values (i.e., devid, appid, and certid,) or an Auth'n'Auth token must be provided using SOAP headers.

The following code sample illustrates how to pass in an Auth'n'Auth token using a SOAP header:

<soapenv:Header>
  <urn:RequesterCredentials>
    <urn:eBayAuthToken>h*****************7</urn:eBayAuthToken>
  </urn:RequesterCredentials>
</soapenv:Header>

The following code sample illustrates the proper method of passing in keyset values (i.e., DevId, AppId, and AuthCert,) using a SOAP header.

<soap:Envelope xmlns:soap="http://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>1131</Version>
  </FetchTokenRequest>
</soap:Envelope>

Routing information

The following example illustrates one method of specifying routing information. The query parameters are hard-coded for illustration purposes only. This example is in Java, but the logic is similar for any programming language.

Specify Routing Information in the Request URL

// 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);

Specify the schema/WSDL version

The version of the schema/WSDL being used must be specified in each request using the version query parameter.

eBay returns the version of the schema used in each response's Version field. This allows developers to confirm that the version in use is the version that is 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 to resolve technical issues.

Download a WSDL file

Specific release versions of ebaySvc.wsdl may be downloaded by navigating to the following location:

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

where {VERSION} is:

A numeric value (e.g., 1131)

This is the version/release number of the specific WSDL file that is to be downloaded.
latest

Use this to download the current/most recent WSDL release.

All releases have odd version numbers. Older versions are periodically deprecated, which means they are no longer supported.

Each time a new version of the eBay schema/WSDL is released:

A new directory is added and named for the new version number
The target of the latest indicator is updated to point to this newly-created version's directory.

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

Refer to 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.

Generate interfaces and proxies from a WSDL

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 one method of generating 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, is used to disable the timeout for this command.

In practice, this information is entered on a single line.

java org.apache.axis2.wsdl.WSDL2Java -o src -O -1
https://developer.ebay.com/webservices/1131/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.