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 only applicable for some calls, but the way you use it is standardized. This section describes this standard data.

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

Release Versions

Standard Input Data

Controlling the Amount of Data Returned

Security

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 only used 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. For information on the call-specific input tags, see the chapters for the various calls in API Call Reference Guide. The input data common to all calls is described in the next few sections.

Target eBay site
Schema version
Message ID
Error language
Detail level

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.

Specifying the Target Site

When you invoke a call, you need to identify the eBay site to route the request to. 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).

For a list of valid site IDs, do a GeteBayDetails call or see the SiteCodeType documentation.

Site IDs

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

In the XML API, at a minimum, you need to specify the ID of the target site in the X-EBAY-API-SITEID HTTP header.

In the SOAP API, at a minimum, you need to specify the ID of the target site in the URL (see Routing the Request (Gateway URLs)).

For some calls, such as AddItem, you also need to specify the target site when you list an item (by using the Item.Site input field). The site you specify for the item must match the site you specify in the URL.

In the SOAP API, you identify the site with a numeric ID in the URL. In contrast, in the XML API, you identify the site with a numeric ID in the HTTP header. For setting the Item.Site field, you use a value in the site code list (SiteCodeType). Call responses that return site information also use values in the site code list.

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, you need to specify the target site when you list an item (in the Item.Site property). The site you specify must match the site you specified in the ApiContext.Site property. When you set Item.Site, use a value in the site code list (SiteCodeType). The response of a call that returns site information also uses a value in the site code list (SiteCodeType).

The site ID or code you specify affects the business logic and validation rules that are applied to the request. For example, the site can affect the list of available categories (including the availability of categories that support Item Specifics, Pre-filled Item Information, and VAT/business items), international business requirements (e.g., whether a listing is subject to VAT), values returned converted prices (e.g., Item.ListingDetails.ConvertedStartPrice), and other information. In some cases, the rules are determined by a combination of the site, the user's registration address, and other information.

The site you specify when using AddItem affects the visibility of the item in some types of searches. Using GetCategoryListings can show that items listed on the US site do not appear in the categories of the UK site.

Several calls share the same data as AddItem: RelistItem, ReviseItem, and VerifyAddItem. These calls are collectively known as "the AddItem family of calls." Usually, if a change is made to AddItem, the same change will apply to these other calls and to GetItem.

With the AddItem family of calls, the site also controls the item-related time stamps that are displayed on the eBay Web site. These localized time stamps are not necessarily apparent via the API, as it returns most time values in GMT or your local time (see eBay Types). Some functions that locate a listing by its item ID (e.g., GetItem) can find the listing correctly regardless of the site value you specify in those requests. However, to ensure the application uses the correct business rules and localization, the site value you pass (particularly when you are revising or re-listing an item) should match the site where the item was originally listed.

For calls made to international sites, the site information can control the language of the error and warning strings that are returned (see ErrorLanguage below).

The site information 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.) However, site-specific information (such as a subscription to SellingManagerPro) depends on the site you specify in the request. Non-site- specific information (such as registration date) does not depend on the site you specify in the request.
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 and GetCategoryListings) generally only retrieve data that is applicable to the site that you specify in the request.

While the usefulness of including the Item.Site field in addition to the header 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 header. Therefore, we 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 URL and the Item.Site field the same time so that they always match each other.

Specifying the Schema Version in the Message Payload 

In each request, you need to pass the version of the schema you are using. In the SOAP API, the version is defined on the abstract request and response types (see Base Components). The value is passed in the Version field of the request. In the XML API, the version is defined in the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header.

See the eBay Schema Versioning Strategy for information about how the version affects the way eBay processes your request.

The following example in the SOAP API shows how to specify the payload version for a GetItem request.

Example 5-8 Specifying the Payload Version

GetItemRequestType theRequest = new GetItemRequestType(); theRequest.setVersion(version); // Version set from a variable

Note: To distinguish the current international version from the US version, this documentation appends the letter "i" to the release number. Please do not include the "i" when passing the version number to eBay. The AbstractRequestType also 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 5-3 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 Unique Identifiers for Write Calls) followed by a dash and an application-specific value.

UUID-ApplicationSpecificValue

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

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

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

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

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

Many programming languages provide classes or modules that generate UUIDs.

Some calls are designed to retrieve large sets of meta-data that only change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). In these cases, the correlation ID is not applicable. However, if you specify an input filter to reduce the amount data returned, you can use MessageID and CorrelationID for these meta-data calls. See the eBay Trading API Call 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. The following table provides the language identification tag you should enter, along with the associated country and eBay site ID

Table 5-3 Error Language Codes 

Language Identification Tag	Country	eBay Site ID
de_AT	Austria	16
de_CH	Switzerland	193
de_DE	Germany	77
en_AU	Australia	15
en_CA	Canada	2
en_IE	Ireland	205
en_GB	United Kingdom	3
en_US	United States	0
es_ES	Spain	186
fr_BE	Belgium (French)	23
fr_CA	Canada (French)	210
fr_FR	France	71
it_IT	Italy	101
nl_BE	Belgium (Dutch)	123
nl_NL	Netherlands	146
en_IN	India	203

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 level 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 in the call request. Similarly, for calls that support granularity levels, use the GranularityLevel property of the call request.

Using a detail level (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. Some calls also support an alternative GranularityLevel property. Typically, you can use either DetailLevel or GranularityLevel, but not both at the same time. (Some calls may support passing both in the same request. See the API Call Reference Guide 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), Medium, and 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 chapter for that call in API Call Reference Guide.

In the SOAP API, this example shows how to specify detail levels in a request. For an example in Java, see the GetSellerListCall.java file in the call folder of the eBay SDK for Java:

eBay SDK for Java

http://developer.ebay.com/community/featured_projects/?name=eBay+SDK+for+Java

Unique Identifiers 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 may happen 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:

AddItem
RelistItem

If a duplicate InvocationID is used for a call, an error (code 21060) will be returned along with the following XML structure:

Example 5-9 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:

AddOrder
AddToItemDescription
PlaceOffer
ReviseCheckoutStatus
ReviseItem

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, 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 Specifying Detail Levels and Granularity Levels and 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.

Security

The following subsections describe how to make secure API requests.

Before a user on the eBay site can perform any operation of significance (list an item, bid on an item, etc.), that user must log in to the site using an eBay user name and a password. Similarly, for the user of an application to make an API call, it must be determined that application end-user is authorized to do so. Making this determination is called authentication. On the eBay site, authentication is accomplished by the user signing in. When an application is acting on a user's behalf, authentication is accomplished by the application passing authenticating data in the API call's request. eBay uses the user authentication data passed with the call's request to identify the requesting user and authenticate the user before performing the requested action.

For many API calls (as is the case with many user activities on the eBay site) this user authentication is merely a verification that the user is a registered eBay user. For instance, anyone who is a registered user may retrieve and view item data with GetSellerList. However, some operations require that the user in question is also verified to be a particular user. For example, only an item's seller is authorized to re-list a particular item. So authentication for an item re-list operation using RelistItem both verifies that the requester is a registered eBay user and is the item's seller.

There are two types of authentication data that an application may pass to eBay in a call's request. One is a user's authentication token, as shown in the samples in Authenticating with an Authentication Token.

The other is a pairing of a user's session ID and the full keyset of your developer credentials, but this is only required for FetchToken, the call that you use to obtain the user's authentication token in the first place. The full set of developer keys is also required for the GetTokenStatus, RevokeToken, and GetSessionIDAPI 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 developer program keys:

Example 5-10 Passing Token Authentication (SOAP)

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"                xmlns:xs="http://www.w3.org/2001/XMLSchema"                xmlns:ebl="urn:ebay:apis:eBLBaseComponents">   <soap:Header>     <ebl:RequesterCredentials soapenv:mustUnderstand="0">       <eBayAuthToken>           ... AUTHENTICATION TOKEN GOES HERE ...       </eBayAuthToken     </ebl:RequesterCredentials>   </soap:Header> ... Call body ... </soap:Envelope>

In the XML API, to authenticate the requester for a call using an authentication token, pass the token in the eBayAuthToken element within the RequesterCredentials element in the request XML.:

Example 5-11 Passing Token Authentication (XML)

<?xml version="1.0" encoding="utf-8"?> <GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">   <RequesterCredentials>     <eBayAuthToken> Token goes here </eBayAuthToken>   </RequesterCredentials>   <Version>383</Version> </GeteBayOfficialTimeRequest>

A sample delivered with the eBay SDK for Java shows how to add this element in Java and populate it with an authentication token. Specifically, see the Global.java file in the signingredirect folder in the eBay SDK for Java:

eBay SDK for Java

http://developer.ebay.com/community/featured_projects/?name=eBay+SDK+for+Java

Example 5-12, which applies to the SOAP API, shows how to add this header child element in C# and populate it with an authentication token.

Example 5-12 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 Java

http://developer.ebay.com/community/featured_projects/?name=eBay+SDK+for+Java

In the eBay SDK for .NET, pass the authentication token for the requesting user in the ApiCredential property of the ApiContext object used for the call. The ApiContext.ApiCredential.eBayToken property holds the authentication token for a call. In the example below, the authentication token is conveyed in the variable token, which is of type string.

Example 5-13 Passing Token Authentication (C#)

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

Authenticating with a Full Keyset and Session ID

The use of a full application keyset (DevID, AppID, and AuthCert) to authenticate the requester of a call is not required for most calls.

However, a few calls do require the full keyset. These exceptional calls are all associated with authentication and tokens: FetchToken, RevokeToken, GetTokenStatus, and GetSessionID.

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

For SOAP and XML, you pass the keyset in the header for the request. The FetchToken examples for SOAP and XML below show header elements that contain the keyset-based authentication data:

Example 5-14 Passing the Keyset in the Header (SOAP) 

<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"                xmlns:xs="http://www.w3.org/2001/XMLSchema"                xmlns:ebl="urn:ebay:apis:eBLBaseComponents">   <soap:Header>     <ebl:RequesterCredentials soapenv:mustUnderstand="0">       <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>

Example 5-15 Passing the Keyset in the Header Element (XML)

Headers: X-EBAY-API-COMPATIBILITY-LEVEL: 613 X-EBAY-API-DEV-NAME:YourDevID X-EBAY-API-APP-NAMEYourAppID X-EBAY-API-CERT-NAME:YourCertID X-EBAY-API-CALL-NAME:FetchToken X-EBAY-API-SITEID:0 Content-Type:text/xml Request Payload: <?xml version="1.0" encoding="utf-8"?> <FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents">   <Version>613</Version>   <SessionID>MySessionID</SessionID> </FetchTokenRequest>

A sample delivered with the eBay SDK for Java shows how to pass authentication data based on your eBay Developer's Program credentials in Java. Specifically, see the ClientAuthenticationHandler.java file in the handler folder of the eBay SDK for Java:

eBay SDK for Java

http://developer.ebay.com/community/featured_projects/?name=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 (mDevID, mAppID, and mCert) and for the eBay Developer's Program credentials. The variables are all of type String.

If you are using the eBay SDK for .NET, pass your eBay Developer's Program credentials within an API call request in the ApiCredential property of the ApiContext object. The ApiCredential object has an ApiAccount property to contain the application's credentials and an eBayAccount property to hold the requesting user's eBay Developer's Program credentials, which are used to authenticate the user for the call. The variables used to express the application's credentials (devID, appID, and cert) and the variables containing the eBay Developer's Program credentials are all of type string.

Standard Output Data

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

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

Time stamp
Version
Build
Acknowledgement
Correlation ID
Message (not to be confused with the MessageID input field)
Hard expiration warning
Errors

Time Stamp

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

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

Version and Build

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

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

Acknowledgement

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

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

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

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

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

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

Correlation ID

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

Message

The AddItem family of calls (VerifyAddItem, etc.), EndItem, PlaceOffer, and certain other calls can return a Message field that provides the seller with information critical to the listing's success. This can include listing hints, policy violation explanations, or othe details. (See the Field Index in the eBay Trading API Call 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 <TABLE> and <IMG> tags and URLs. If your application doesn't support HTML, you can parse the tags and then translate the data into UI elements particular to the programming language you use.

Errors and Warnings

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

Hard Expiration Warning

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

User-Contributed Notes