The standard output fields are defined in AbstractResponseType and are briefly described below.
Timestamp
All responses return a timestamp (in UTC/GMT) to indicate when the response was generated. Refer to Time values for additional information about UTC/GMT values.
Version and Build
The Version and Build fields return the version of the schema and the specific software build that was used when processing the request and generating the response, respectively. Developer Technical Support may ask a developer for the Build value when troubleshooting issues.
Acknowledgement
All responses return a standard Ack field that indicates the success, failure, or partial failure of a call.
Some calls that submit data or provide instructions to eBay return an Ack status of Success with no call-specific data. For example, when issuing a CompleteSale call 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 issuing an AddItem call 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. Refer to Error handling for additional information about working with warnings.
If the Ack field returns Failure, it means the 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. Refer to Error handling for additional information about handling errors.
A very limited number of calls can return an Ack status of PartialFailure. This means some portion of your request succeeded and another portion failed.
CorrelationID
If you pass in a MessageID value in a request, the same value is returned 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. Refer to Message IDs for more information.
Message
The AddItem family of calls and certain other Trading API calls can return a Message field that provides sellers with information critical to their listings' success. This can include listing hints, policy violation explanations, or other details.
Refer to the Field Index for a list of calls that return this field.
Applications must recognize whenever the Message field is returned and provide a means of displaying the message to the user.
These messages provide key benefits to the end user including:
- 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.
In addition to reviewing the response for an AddItem call for any messages, sellers are encouraged to issue a VerifyAddItem call to review any messages before submitting their listings. By ensuring that sellers receive policy messaging and other information in a timely matter, a seller's experience on eBay can be improved. Neglecting to display 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 does not 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 does not revise the listing with the required changes in a timely manner, eBay may still administratively end the listing a short time later due to the policy violation.
The Message field may contain HTML elements such as <TABLE> and <IMG> tags and URLs. If an application does not support HTML, parse the tags and then translate the data into UI elements specific to the programming language in use.
Errors and Warnings
For any request, one or more errors or warnings may be returned within the Errors container. For additional information about working with errors, refer to Error handling
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. For additional information refer to Understand Auth'n'Auth tokens.