Standard Data for All Calls

Regardless of whether you are listing an item, browsing listings, or performing some other business task, some data is handled in a standard way for all requests. Some of this data is required with all requests. Other data is applicable only to certain calls, but the way you use it is standardized. This section describes this standard data.

Topics:

Standard Input Data

Controlling the Amount of Data Returned

Security

Standard Output Data

Also, for information about standard data that you need to append to the Gateway URL see Routing the Request.

Standard Input Data

A given API call has two fundamental kinds of information you need to send: Data that is common to all API calls, and data that is used only in a particular call to fulfill that call's purpose.

In some cases, you pass this data by using input fields that are defined on AbstractRequestType. In other cases, you pass this data in the URL or an HTTP header. The input data common to all calls, the standard input data, is described in the following sections.

The tags you use in an API call must match the API schema. For example, the letters in an input tag must have the case that matches the case defined for the tag in the API schema.

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 Developers Program Knowledge Base for additional information:

https://developer.ebay.com/DevZone/support/knowledgebase/

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.

Site IDs

http://developer.ebay.com/DevZone/XML/docs/Reference/eBay/types/SiteCodeType.html

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 Routing the Request). 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.
  3. 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:

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:

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:

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.

Figure: The Version Element in a SOAP Response Message
Version Element

 

Specifying a Message ID to Correlate the Request and Response

The message ID is used to associate the response message with the particular request message that triggered it. This correlating message ID is an optional input that an application can use to enable strict tracking of request and response messages—especially important if an application has to contend with many such message pairings. Pass the message ID value in the MessageID property of the call's request object. The value should be unique across the eBay site and cannot exceed 64 characters.

A unique message ID should consist of a universally unique identifier (UUID) or your InvocationID value (see Specifying Unique Identifiers (UUID) for Write Calls) followed by a dash and an application-specific value.

UUID-ApplicationSpecificValue

The UUID or invocation ID can only contain digits from 0-9 and letters from A-F and must be 32 characters long.

Note: The AddItem object also accepts an Item.UUID value as input. When executing this call, we recommend that you use the same UUID in both the MessageID and the Item.UUID.

The value passed in MessageID (if any) is returned verbatim in the CorrelationID property of the response object. This provides the connection between a particular request and its response. (The value is not read or used in any other way by eBay, and its actual value only has meaning to the application.)

The application can use this information to definitively associate a particular response with the request that triggered it. For example, if the application serves multiple customers and has some internal identifier for each user (like the serial customer number from a table of customers) and the message ID, then the application would be able to associate responses with particular customers.

Of course, an application could use a combination of these approaches, such as passing the customer identifier within the application-specific value. That would serve to both link the request and response to each other and to associate the response with a particular customer. For example, the application might pass a value like "9CEBD9A6825644EC8D06C436D6CF494B-00451", where the characters to the left of the hyphen are a UUID and the characters to the right are an application-specific customer ID. The maximum length is 64 characters (including the UUID and hyphen).

Many programming languages provide classes or modules that generate UUIDs.

Some calls are designed to retrieve large sets of meta-data that only change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). In these cases, the correlation ID is not applicable. However, if you specify an input filter to reduce the amount data returned, you can use MessageID and CorrelationID for these meta-data calls. See the eBay Trading API Reference for a list of calls that can return cached data.

Specifying an Error Language

An application can specify the language in which error messages are returned. This is done through the value passed in the ErrorLanguage property of the request. Specify the standard RFC 3066 language identification tag for the language in which error messages should be returned. For example, specify en_US to have error messages returned in US English. Error language is an optional input which, if not specified, defaults to US English. See http://developer.ebay.com/Devzone/finding/CallRef/Enums/GlobalIdList.html for the language identification tag you should enter, along with the associated country and eBay site ID.

Specifying Detail Levels and Granularity Levels

With many data retrieval calls that return multiple results (e.g., multiple items), you can reduce the volume of the response payload for a single API call by reducing the number of fields returned in each result.

A standard way to do this is to use a detail control or, for some calls, a granularity level. For example, a particular level might cause the response to include buyer-related data in every result, but no seller-related data. Specify a detail level using the DetailLevel property (or the equivalent outputSelector property) in the call request. Similarly, for calls that support granularity levels, use the GranularityLevel property of the call request.

Using a detail control (or granularity level) is just one way to reduce the size of the response payload for a single API call. For other ways, see Controlling the Amount of Data Returned.

The schema includes a global list of detail levels. You use GranularityLevel for the GetBidderList and GetSellerList calls and DetailLevel for all other calls. See the eBay Developers Program API References for information about the filters each call supports.)

If DetailLevel or GranularityLevel applies to a call, the definitions of the levels are consistent across all request types (although the list of fields returned varies per call). For example, if DetailLevel or GranularityLevel applies to a call:

Additional detail level values are also available. See the detail level code list in the schema documentation for a list of the available detail levels.

The DetailLevel property is defined on the abstract type (AbstractRequestType). The GranularityLevel property is defined on a call's request type (e.g., GetSellerListRequestType) rather than on the abstract type.

Note that not all calls support detail levels to vary the output. Most calls only support certain detail levels or none:

If you pass a detail level that exists in the schema but that is not valid for a particular request, eBay ignores it and the request is processed normally. Note that you can specify multiple detail levels in a single request, but you can only specify one granularity level in a single request.

To determine whether a particular call supports detail levels and/or granularity levels (and if so, what the effects are), see the page for that call in the appropriate eBay Developers Program API Reference.

Specifying Unique Identifiers (UUID) for Write Calls

Some API calls that send data to eBay support the use of the Item.UUID or InvocationID input parameters. These parameters uniquely identify a given call for a particular application/user combination. The parameters must be exactly 32 characters long, and contain only digits from 0-9 and letters from A-F. The parameters are not case-sensitive.

Use Item.UUID or InvocationID with supported calls to prevent the submission of duplicate data. If it is not clear whether or not the call succeeded, such as when there is a network error, you can submit the same data again with the same Item.UUID or InvocationID. If the previous call did succeed, then the second call will not go through, and the same data will not be submitted twice.

Item.UUID is recommended for use with calls that write item data. If a duplicate UUID is used for a call, an error (code 488) will be returned with the item ID of the item previously listed with the same UUID and a Boolean value indicating whether the duplicate UUID was sent by the same application.

Use Item.UUID to uniquely identify the following calls:

If a duplicate InvocationID is used for a call, an error (code 21060) will be returned along with the DuplicateInvocationDetails container.

Example: Duplicate InvocationID Error Structure
 <DuplicateInvocationDetails>
  <DuplicateInvocationID>AAAAAAAA11111111BBBBBBBB22222222</DuplicateInvocationID>
  <Status>Success</Status>
  <InvocationTrackingID>9202918767</InvocationTrackingID>
</DuplicateInvocationDetails>

The Status property indicates whether the previous call succeeded (Success), or is still in progress (InProgress). The InvocationTrackingID property provides a call-specific tracking number.

The following calls currently support the use of InvocationID:

Controlling the Amount of Data Returned

Some responses can potentially contain a large payload. A number of mechanisms are available to help you control the amount of data returned:

Various topics in this documentation refer to these mechanisms in the context of performing particular tasks. Please see Retrieving Items for examples.

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 authentication token. For more detailed information on getting and renewing authentication tokens, see Getting Tokens.

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:

Example: Passing Token Authentication (SOAP)
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xs="http://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.:

Example: Passing Token Authentication (XML)
<?xml version="1.0" encoding="utf-8"?>
<GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken> Token goes here </eBayAuthToken>
  </RequesterCredentials>
  <Version>383</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

http://developer.ebay.com/developercenter/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.

Example: Passing Token Authentication (C#)
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://go.developer.ebay.com/developers/ebay/documentation-tools/sdks/dotnet

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.

Example: Passing Token Authentication (C#)
// 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:

Figure: Passing the Keyset in the Header (SOAP)
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xs="http://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>613</Version>
  </FetchTokenRequest>
</soap:Envelope>
Figure: Passing the Keyset in the Header Element (XML)
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>613</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://go.developer.ebay.com/developers/ebay/documentation-tools/sdks/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 (mDevID, mAppID, and mCert) and for the eBay Developer's Program credentials. The variables are all of type String.

eBay SDK for .NET

https://go.developer.ebay.com/developers/ebay/documentation-tools/sdks/dotnet

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.

Standard Output Data

All API calls return certain fields, and some calls may return additional call-specific data that you requested.

The standard fields are defined on AbstractRequestType. For information on the call-specific input tags, see the eBay Trading API Reference. The output data common to all calls is described in the next few sections.

Time Stamp

All responses return the official eBay time stamp in UTC/GMT (see eBay Types for information about UTC/GMT values).

The time stamp indicates the time when eBay processed the request; it does not necessarily indicate the current eBay official eBay time. In particular, calls like GetCategories can return a cached response, so the time stamp may not be current.

Version and Build

Use the Version and Build fields to determine the version of the schema and the specific software build that eBay used when processing the request and generating the response. In particular, Developer Technical Support may ask you for the Build value when you work with them to troubleshoot issues.

See Release Versions for details about working with different schema versions.

Acknowledgement

All responses return a standard Ack field that indicates the success, failure, or partial failure of a call.

Some calls that you use to submit data or instructions to eBay return an Ack status of Success, and no call-specific data. For example, when you use CompleteSale to change an item's paid or shipped status in My eBay, all you need to know is that your request succeeded.

Other data-submission calls return Success and include other fields that you need in order to perform subsequent tasks. For example, when you use AddItem to list an item, it returns the item ID, the start and end times, and other useful data.

When a call is successful, it can also return useful warnings. For example, a warning could indicate that your authentication token is about to expire, you passed in an unrecognized field, some data in your request was dropped, or other useful information. Please see Error Handling for more information about working with warnings.

If the Ack field returns Failure, it means your request could not be processed. In this case, one or more errors are returned to explain the cause of the failure, and no other call-specific data is returned. Please see Error Handling for more information about handling errors.

A very limited number of calls can return an Ack status of PartialFailure. This means some portion of your request succeeded and another portion failed. See CompleteSale for an example.

Correlation ID

If you pass a MessageID in a request, we will return the same value as the CorrelationID in the response. This may be useful for tracking that a response is returned for every request and to match particular responses to particular requests. See Specifying a Message ID to Correlate the Request and Response for more information.

Message

The AddItem family of calls (VerifyAddItem, etc.), EndItem, PlaceOffer, and certain other calls can return a Message field that provides the seller with information critical to the listing's success. This can include listing hints, policy violation explanations, or other details. (See the Field Index in the eBay Trading API Reference for a complete list of calls that return this field.)

Applications must recognize whenever the Message field is returned and provide a means to display the message to the user.

These messages provide these key benefits to the end user:

For listing use cases, we strongly recommend that you use VerifyAddItem to surface these messages to sellers before they submit their listings. (You should still check the AddItem response for any additional messages.) By ensuring that sellers receive policy messaging and other information in a timely matter, you can help to improve a seller's experience on eBay. Neglecting to surface this information may lead to items being ended and general seller dissatisfaction.

When errors are returned, the Message field may be surfaced for both blocking (failure) and warning scenarios (in addition to the Errors.LongMessage and Errors.ShortMessage fields). In this case, the Message field typically contains a more detailed explanation of why the error occurred and how to fix the problem.

Important: If a request succeeds with a warning instead of failing with a severe error, this doesn't mean the message is less important. For example, if a listing appears to violate a zero-tolerance policy, but the certainty is less than 100% at the time of submission, the listing request may succeed with a warning. In this case, the Message field might return a policy message with guidance and education related to the issue. If the seller doesn't revise the listing with the required changes soon, eBay may still administratively end the listing a short time later due to the policy violation.

The Message value may return HTML, such as <TABLE> and <IMG> tags and URLs. If your application doesn't support HTML, you can parse the tags and then translate the data into UI elements particular to the programming language you use.

Errors and Warnings

For any request, one or more errors or warnings may be returned. Please see Error Handling for more information about working with errors.

Hard Expiration Warning

If the user's authentication token is about to expire, all calls using that token will return a HardExpirationWarning field with the expiration date. See About Tokens.

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.