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.
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.
- UTF-8 Character Set
- Specifying the Target Site
- Specifying the Schema Version
- Specifying a Message ID to Correlate the Request and Response
- Specifying an Error Language
- Specifying Detail Levels and Granularity Levels
- Specifying Unique Identifiers (UUID) for Write Calls
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.
Where to Specify the Target Site (XML and SOAP)
For some requests, you need to specify the marketplace 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).
- 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.
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 list of available categories and category hierarchy
- International business requirements (e.g., whether a listing is subject to VAT)
- Currency used for prices/fees
- Shipping cost calculations
- Default units of measure (e.g., pounds vs. kilograms)
- Item-related time stamps that are displayed on the eBay Web site
For example, item revision times might use localized timestamps such as PDT. These timestamps are not necessarily apparent via the API, which expresses time values in GMT (see About GMT)
- Localization of certain standardized string values within listing details
- The language of error and warning strings that are returned
- Other data (which varies by the call you are using)
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.)
- Similarly, eBay 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 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:
- 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)).
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.
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 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|
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:
- GetMyMessages is the only Trading API call that requires a DetailLevel to be set in the request payload. For all other Trading API calls, not setting a DetailLevel may cause the response payload to be bigger or smaller than it would be if you had set a DetailLevel value.
- A DetailLevel value of
ReturnAll, supported by all calls that support DetailLevel (except GetMyMessages), will ensure that all possible and applicable data will be returned in the response. Depending on the API call and amount of data involved, setting DetailLevel to
ReturnAllcan affect client and server-side performance, so developers should use this DetailLevel with caution.
- Some Trading API calls support multiple DetailLevel values, and if used, the developer will include a DetailLevel field for each specified value.
- Just like the field name suggests, the supported values for GranularityLevel sets the granularity (or scale) of the returned details in the response. The three values are
Fine(more results), and what this exactly means varies by API call.
- Only one GranularityLevel value may be set for each API call.
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:
- DetailLevel, GranularityLevel, and OutputSelector are three request filter fields that can define the subsets of data to return within a call response. See Selecting Fields to Retrieve.
- Date/time filters let you specify date/time ranges to limit the amount of data that is returned. For example, the GetSellerList call has EndTimeFrom and EndTimeTo fields that allow the seller to only retrieve listing that ended within that specified time range.
- Pagination filters let you specify the quantity of records (such as orders) that you want to retrieve per page of data. PaginationType is used to control the pagination of the call response, and the user sets two values - an EntriesPerPage value and a PageNumber value. The EntriesPerPage value sets the number of records to return per page of data, and the PageNumber value sets the page of data to return. The maximum EntriesPerPage value can vary by API call, and the PageNumber value would be set to 1 to return the first page of data. The user can uptick the PageNumber value by 1 to see each successive page of records. Each API call that supports pagination will return a container that shows the TotalNumberOfEntries and TotalNumberOfPages(See PaginationResultType). Based on these two values, the user can adjust the EntriesPerPage and PageNumber values in the request during subsequent calls to that API.
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 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:
- One is a user's authentication token, as shown in the samples in Authenticating with an Authentication Token.
- The other is the full keyset of your developer credentials, which is required for the Trading API's FetchToken, GetTokenStatus, RevokeToken, and GetSessionID API calls. See Authenticating with a Full Keyset.
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
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
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
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 (
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
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 (
mCert) and for the eBay Developer's Program credentials. The variables are all of type
eBay SDK for .NET
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 (
cert) and the variables containing the eBay Developer's Program credentials are all of type
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
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.
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.
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.
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:
- 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 more 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.
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
<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.