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.
Standard Input Data
Controlling the Amount of Data Returned
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:
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
Where to Specify the Target Site (XML and SOAP)
For some requests, you need to specify the site twice:
- (All requests) Use the numeric site ID to route the request to the correct site (see 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).
(Some requests) Use the site name (see
- To route the request in the XML API, specify the numeric ID of the target site in the X-EBAY-API-SITEID HTTP header.
- To route the request in the SOAP API, specify the numeric ID of the target site in the URL.
SiteCodeType) in the body of the request as appropriate for the type of call you're using.
For example, in AddItem, specify the target site by using the Item.Site input field. The site you specify for the item should match the site you specify in the HTTP header or URL.
Where to Specify the Target Site (eBay SDK)
If you are using an SDK, specify the ID of the target site in the Site property of the ApiContext object that is used to make the call. The ApiContext object is reusable. An application will typically create and configure an ApiContext object once and then use it for all API calls made for the duration of an application session. This means the site ID usually only needs to be set once if you are using an SDK. Use a value in the site code list (
SiteCodeType). You can change the site ID for a particular call using the ApiContext.setSite( ) method (in the eBay SDK for Java) or using the value of the ApiContext.Site property (in the eBay SDK for .NET).
For some calls, such as AddItem, you need to specify the target site when you list an item (in the Item.Site property). The site you specify for the item should match the site you specified in the ApiContext.Site property. When you set Item.Site, use a value in the site code list (
Why the Target Site Matters
The site you specify in your requests affects the business logic and validation rules that are applied to the request. For example, the site can affect data like the following:
In some cases, the rules are determined by a combination of the site, the user's registration address, and other information. (The documentation explains these dependencies on a case-by-case basis.)
The site you specify when using AddItem can also affect the visibility of the listing in some types of searches. For example, if you call GetItem for the US site, you don't see listings that appear in categories of the UK site.
The site you specify does not necessarily act as a filter for limiting the data returned. It depends on the nature of the request:
- Item IDs are unique across all sites (i.e., an item ID on the UK site would not be re-used for a different listing on the US site). This means calls that filter data by the item ID (e.g., GetItem) retrieve the same listing no matter which site you specify. (This is important, because sometimes you'll only know the item ID, but you might not happen to know which site the item was listed on.) In such cases, the site value you pass only affects site-specific data like ConvertedStartPrice (as described above).
- Similarly, user IDs are unique across all sites. This means that calls that retrieve data by a user ID (e.g., GetUser and GetSellerList) retrieve the data no matter which site the user is registered on and which site you specify in the request. (Again, this is important because you may not know which site the user is actually registered on.)
- Site-specific user information (such as a subscription to Selling Manager Pro on the US site) depends on the site you specify in the request.
- As indicated earlier, category IDs are not unique across all sites, and each site has variations in the category hierarchy. Therefore, the site information has a filtering effect when retrieving category-based data and an impact on validation when you list items. Calls like AddItem will fail if you specify a category ID that is incorrect for the specified site. Calls that filter results by category ID (e.g., GetCategories) generally only retrieve data that is applicable to the site that you specify in the request.
- Other types of user information (such as registration date) does not depend on the site you specify in the request.
While the usefulness of including the Item.Site field in addition to the HTTP header or URL may not be externally apparent for some calls, other calls may fail or may not behave as expected if you do not pass the site data in the body or if the value you pass does not match the value in the HTTP header or URL.
Therefore, we strongly recommend that you always specify the site when you list an item. For some applications, it may be convenient to rely on reusable classes, modules, or functions to set the site ID in the HTTP header or URL and the Item.Site field the same time so that they always match each other.
Specifying the Schema Version
In each request, you need to pass the version of the schema you are using. How you do this depends on which format you're using:
- In the SOAP API, the version is defined on the abstract request and response types. Pass the version in the Version field of the request payload.
- In the XML API, the version is defined in the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header (see HTTP Headers (XML API Only)).
See the eBay Schema Versioning Strategy for information about how the version affects the way eBay processes your request.
Note: To distinguish the current international version from the US version, this documentation sometimes appends the letter "i" to the release number. Please do not include the "i" when passing the version number to eBay. The
AbstractRequestType defines a
Version element. However, that input element is only used by the SOAP API; it is ignored by the XML API.
eBay returns the version of the schema we used in each response's Version field. This lets you confirm that we used the version you expected.
Each response also contains a Build field. This refers to the specific software build that eBay used when processing the request and generating the response. Developer Support may request the build information when helping you resolve technical issues.
Figure: 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.
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:
- Specifying no detail level causes the call to return a brief set of data. This is the default detail level and is recommended for all applicable calls.
- Specifying a granularity level returns more results. You can specify one of three filters:
Coarse (fewer results),
Fine (more results).
- A detail level value of
ReturnAll causes the call to return all data, with no filtering. Requesting more data can affect client and server-side performance, so you should use this detail level less often. As the extra data returned using this detail may change less often than other data, you can generally specify this detail level when you first request a particular set of data, and then specify no detail level in subsequent requests for the same data.
- A detail level value of
ItemReturnDescription causes the call to return descriptive information. The exact list of data returned varies depending on the object being returned.
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:
- Calls that submit data to eBay, such as AddItem, generally do not support varying detail levels, so you do not need to specify the detail level in these requests.
- Several data-retrieval functions, such as GetSellerList and GetItem, support two or more detail levels.
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
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:
- Detail levels, granularity levels (used by GetBidderList and GetSellerList calls), and the output selector—These define subsets of data to return within a call response. For example, a particular detail level might cause the response to include buyer-related data in every result, but not seller-related data. See Selecting Fields to Retrieve.
- Time filters—These let you specify that you only want to retrieve records that fall within a particular time window. For example, for GetSellerList, EndTimeFrom and EndTimeTo are time filters that limit the response to only those items that end between two specified time stamps. Specifying time filters is like specifying conditions in the WHERE clause of an SQL query.
- Pagination filters—These let you specify the quantity of records that you want to retrieve per call. Each set of records is returned as a page. For calls that support (or require) pagination, you can specify the maximum number of results per page you want. When you retrieve the first page, the response indicates what the total number of pages will be, assuming you would continue to specify the same number of results per page in each subsequent call. Once you have this information, you can determine how many more calls you need to make to retrieve all the data, and you can specify which page you want to retrieve next.
- Business data filters—In some cases, you can also reduce the amount of data returned by restricting the response to only those items that meet other business criteria (e.g., only items that support PayPal as a payment method). The choice of data filters allowed varies per call.
Various topics in this documentation refer to these mechanisms in the context of performing particular tasks. Please see Retrieving Items for examples.
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"?>
... AUTHENTICATION TOKEN GOES HERE ...
... Call body ...
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"?>
Token goes here </eBayAuthToken>
A sample delivered with the eBay SDK for Java shows how to add this element in Java and populate it with an authentication token. Specifically, see the
Global.java file in the
signingredirect folder in the eBay SDK for Java:
eBay SDK for Java
The following example, which applies to the SOAP API, shows how to add this header child element in C# and populate it with an authentication token.
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
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
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 (
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)
Figure: Passing the Keyset in the Header Element (XML)
<?xml version="1.0" encoding="utf-8"?>
A sample delivered with the eBay SDK for Java shows how to pass authentication data based on your eBay Developer's Program credentials in Java. Specifically, see the
ClientAuthenticationHandler.java file in the
handler folder of the eBay SDK for Java:
eBay SDK for Java
If you are using the eBay SDK for Java, pass your eBay Developer's Program credentials within an API call request in the ApiCredential property of the ApiContext object. The ApiCredential object has an ApiAccount property to contain the application's credentials and an eBayAccount property to hold the requesting user's eBay Developer's Program credentials. These are used to authenticate the user for the call. Variables are used for the application's credentials (
mCert) and for the eBay Developer's Program credentials. The variables are all of type
eBay SDK for .NET
If you are using the eBay SDK for .NET, pass your eBay Developer's Program credentials within an API call request in the ApiCredential property of the ApiContext object. The ApiCredential object has an ApiAccount property to contain the application's credentials and an eBayAccount property to hold the requesting user's eBay Developer's Program credentials, which are used to authenticate the user for the call. The variables used to express the application's credentials (
cert) and the variables containing the eBay Developer's Program credentials are all of type
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
- Correlation ID
- Message (not to be confused with the MessageID input field)
- Hard expiration warning
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.
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.
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.
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:
- Sellers can review and resolve potential policy violations to reduce the likelihood that their item will be ended administratively by eBay.
- Sellers can take advantage of the hints as tools to increase their sales. For example, a hint could advise newer sellers that including pictures has been shown to increase the success of listings by a certain percentage.
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
<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.