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.

Subtopics

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

Any traditional API call has two fundamental kinds of information you need to send: data that is common to all calls in that API, and data that is specific to that particular call to fulfill that call's purpose.

In some cases, you pass this data by using input fields that are defined in AbstractRequestType. In other cases, you pass this data in through the endpoint or through an HTTP header. The common input data is described in the following sections.

The tags you use in a traditional API call must exactly match the API schema and are case-sensitive.

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 Working with UTF-8 checklist article in the Developers Program Knowledge Base for additional information.

Specifying the Target Site

The eBay marketplace you specify in your requests affects the business logic and validation rules that are applied to the request. For example, the eBay US marketplace and the eBay Germany marketplace 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 marketplace 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 enumeration value (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 appropriate site enumeration value 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 value usually only needs to be set once if you are using an SDK. Use one of the enumeration values in (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 (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 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 enumeration value in the request payload, or if the value you pass in 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.

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:

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.

Version Element
 The Version Element in a SOAP Response Message

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 InvocationID values can only contain digits from 0-9 and letters from A-F and must be exactly 32 characters long.

The AddItem call 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 same value passed in MessageID (if any) is returned in the CorrelationID element of the response payload. 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 metadata that change infrequently. To improve performance, these calls return cached responses when you request all available data (with no filters). In these cases, the CorrelationID is not applicable. However, if you specify an input filter to reduce the amount data returned, you can use MessageID and CorrelationID for these metadata calls.

Specifying an Error Language

An application can specify the language in which error and warning messages are returned. This is done by setting a value 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 https://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 objects (e.g., multiple items), you may want to reduce the volume of the response payload by reducing the number of fields (or details within this fields) that are returned in each response.

Three filter types you can use are DetailLevel, OutputSelector, and GranularityLevel. The following table shows the Trading API calls that support these filter types:

Trading API calls that support DetailLevel Trading API calls that support OutputSelector Trading API calls that support GranularityLevel
GetAdFormatLeads GetAccount GetBidderList
GetBestOffers GetAdFormatLeads GetSellerList
GetCategories GetAllBidders  
GetCategoryFeatures GetBestOffers  
GetCategoryMappings GetBidderList  
GetFeedback GetCategories  
GetItem GetCategoryFeatures  
GetItemTransactions GetFeedback  
GetMyeBayBuying GetItem  
GetMyeBaySelling GetItemsAwaitingFeedback  
GetMyMessages GetItemShipping  
GetOrders GetItemTransactions  
GetOrderTransactions GetMemberMessages  
GetSellerEvents GetMyeBayBuying  
GetSellerList GetMyeBaySelling  
GetSellerTransactions GetMyMessages  
GetTaxTable GetNotificationPreferences  
GetUser GetOrders  
GetUserDisputes GetOrderTransactions  
  GetSellerEvents  
  GetSellerList  
  GetSellerTransactions  

Using any of these three filter types is just one way to reduce the size of the response payload. For information on other ways to control the data that is returned, see Controlling the Amount of Data Returned.

Both DetailLevel or GranularityLevel have associated code types that define the enumeration values that can be used for each of these filters. The Trading API calls that can use each of the enumeration values, and how they use each value, differs with each call. See DetailLevelCodeType and GranularityLevelCodeType for more information on the different filter values available. You can also read the call reference documentation for each call for more information on how these values are used for each supported API call.

Some more notes on using DetailLevel or GranularityLevel is shown below:

The DetailLevel property is defined (AbstractRequestType) (used by many Trading API calls), and the GranularityLevel property is defined in the base request types of the two Trading API calls that support it, so GetBidderListRequestType and GetSellerListRequestType).

Generally, if you pass in a DetailLevel or a GranularityLevel value that is not supported by a particular Trading API call, the filter and its value will just be ignored, and a error/warning message will not be triggered.

For all calls that support DetailLevel and/or GranularityLevel, a DetailLevel and/or GranularityLevel section is added to the Detail Controls section of the call reference page. These sections contain tables which tell users exactly which fields are returned based on the DetailLevel and/or GranularityLevel values that are set.

The OutputSelector filter works quite differently than DetailLevel and GranularityLevel. With OutputSelector, a specific response container/field to return is specified through an OutputSelector field. Multiple OutputSelector fields can be used in one call. If a container is specified, all of that container's children will also be returned. For example, If you a GetItem call and set the OutputSelector field to ListingDetails, all fields within the ListingDetails container are returned. Developers should read the call reference documentation for a specific API call to get more information about using OutputSelector with that call.

Specifying Unique Identifiers (UUID) for Write Calls

Some Trading API calls support the use of a UUID or InvocationID request parameters. These parameters uniquely identify a specific instance of an API 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 UUID or InvocationID values 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 UUID or InvocationID value. If the previous call did succeed, then the second call will not go through, and the same data will not be submitted twice.

UUID is recommended for use with calls that write item data. If a duplicate UUID value is used for a call, 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.

A UUID can be useful to uniquely identify specific instances of the following Trading API calls:

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

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 traditional API call requests.

Before a user on an eBay marketplace can perform any operation of significance (list an item, bid on an item, etc.), that user must be logged 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 relist a particular item. So authentication for an item relist 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:

Authenticating with an Authentication Token

An application can authenticate a requesting user by passing in an authentication token into the eBayAuthToken request field. For more detailed information on getting and renewing authentication tokens, see Getting Tokens.

The example below shows the eBayAuthToken field under the header element in the SOAP version of the Trading API.

Passing Token Authentication (SOAP)

<?xml version="1.0" encoding="utf-8"?>
<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">
      <eBayAuthToken>
          ... AUTHENTICATION TOKEN GOES HERE ...
      </eBayAuthToken
    </ebl:RequesterCredentials>
  </soap:Header>
... Call body ...
</soap:Envelope>

In the XML version of the Trading API, the eBayAuthToken element is found within the RequesterCredentials element, as shown below:

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>1201</Version>
</GeteBayOfficialTimeRequest>

A sample delivered with the Trading API 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/tools/javasdk

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.

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 Trading API 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/tools/netsdk

In the Trading API 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.

Passing Token Authentication (C#)

// Create the ApiContext object and specify the credentials
ApiContext context = new ApiContext();
context.ApiCredential.ApiAccount.Application = "MyAppId";
context.ApiCredential.ApiAccount.Certificate = "MyCertId";
context.ApiCredential.ApiAccount.Developer = "MyDevID";
context.ApiCredential.eBayToken = "ABC...123";

Authenticating with a Full Keyset and Session ID

The use of a full application keyset (DevId, AppId, and CertId) 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, GetSessionID, GetTokenStatus, and RevokeToken.

For these calls, you pass the application's full keyset along with the request.

For the SOAP and XML versions of the Trading API, 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:

Passing the Keyset in the Header (SOAP)

<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>613</Version>
  </FetchTokenRequest>
</soap:Envelope>

Passing the Keyset in the Header Element (XML)

X-EBAY-API-COMPATIBILITY-LEVEL: 613
X-EBAY-API-DEV-NAME:MyDevID
X-EBAY-API-APP-NAME:MyAppID
X-EBAY-API-CERT-NAME:MyCertID
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/javasdk

If you are using the Trading API 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/netsdk

If you are using the Trading API 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

The standard output fields are defined in AbstractResponseType. The output fields common to all Trading API calls are shown below, and also briefly discussed over the next several sections

Timestamp

All responses return a timestamp (in UTC/GMT) to indicate when the response was generated. See eBay Types for information about UTC/GMT values.

The timestamp indicates the time when eBay processed the request; it does not necessarily indicate the current time. For example, some calls like GetCategories can return a cached response, so the timestamp may not be current.

Version and Build

The Version and Build fields respectively show the version of the schema and the specific software build that eBay used when processing the request and generating the response. Developer Technical Support may ask a developer for the Build value when troubleshooting issues.

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

CorrelationID

If you pass in a MessageID value in a request, we will return the same value in the CorrelationID field 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 and certain other Trading API 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.

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 field may contain HTML elements, 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 under the Errors container. 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.