Resolution Case Management API

eBay Resolution Case Management API Users Guide



Note: The Resolution Case Management API is no longer recommended. Instead, current users of the Resolution Case Management API should make plans to migrate to, and use the Return, Inquiry, and Case Management operations of the Post-Order API. New users interested is programmatically managing and resolving Item Not Received (INR) and Return/SNAD (Significantly Not as Described) cases, should also make plans to integrate with the Post-Order API. Since the Resolution Case Management API was first released, there have been many changes made to post-order flows, and Resolution Case Management API does not support all features and logic of the new flows. This API will be deprecated in the near future.

Introduction

The Resolution Case Management API is primarily used by US, UK, and DE sellers to retrieve, track, manage, and resolve all eBay Buyer Protection cases that are opened by buyers in the Resolution Center. Some of the functionality offered to the seller through this API include retrieving summary and detailed information on open cases, issuing full refunds or partial refunds (only for Significantly Not As Described items) to the buyer, providing shipping, item tracking, return, or refund information to the buyer, and escalating or appealing a case.

The eBay Buyer Protection program protects buyers when they purchase items that are not received or items that are significantly not as described. Currently, the eBay Buyer Protection program is only available on the US, UK, and DE eBay sites at: http://resolutioncenter.ebay.com/ , http://resolutioncentre.ebay.co.uk/, and http://resolutioncenter.ebay.de/ .

On the UK and DE sites, the buyer has the option of returning and requesting a refund for an item as long as they open a case in Resolution Center within 7 business days after receiving the item. This is assuming that the seller had a Returns Accepted policy on the item. Buyers in the US must arrange a return with the seller or go through the new US managed return process.

For information on the Return process in the UK and Germany, see the following links:

For more information on the eBay US Return process, see the Using the managed return process help topic.

Service Overview

Resolution Case Management is a SOA service that is intended to be consumed by US, UK, and DE sellers who are interested in retrieving, tracking, managing, and resolving all eBay Buyer Protection cases opened by buyers in the eBay Resolution Center. Older disputes, disputes created through PayPal, and Unpaid Item disputes created through the Trading API can only be retrieved with the Resolution Case Management API. These disputes must be managed and resolved through other means, such as through the Trading API dispute calls or through the PayPal system. The Resolution Case Management API is currently only available on the US, UK and DE eBay sites.

Due to the eBay seller ratings policy, it is crucial that sellers are aware of all open cases against them, so they can respond and resolve these cases as soon as possible. The Resolution Case Management API will assist in this endeavor.

Below is a high-level summary of the 16 calls of the Resolution Case Management API:

Refer to the eBay Resolution Case Management API API Reference for detailed information on each call, including input fields, output fields, and samples.

Retrieving Cases and Disputes

In addition to retrieving Item Not Received, Significantly Not As Described, and Return (UK and DE only) cases created by buyers through the Resolution Center, the getUserCases call of the Resolution Case Management API can retrieve all other cases and disputes as well, including older disputes, buyer claims filed through PayPal, and Unpaid Item disputes created by the seller through the Trading API. getUserCases returns summary information on all cases and disputes in which the authenticated user is involved as a seller or buyer.

If a seller is only interested in investigating and resolving eBay Buyer Protection cases, the following two initial calls should be made. First, the seller should call getUserCases, using three case type filters to restrict the results to Item Not Received, Significantly Not As Described, and Return cases (UK and DE only) opened by buyers in the Resolution Center. For more information on case type filters, see the getUserCases API Reference. To get more detailed information on a specific eBay Buyer Protection case, the seller makes a call to getEBPCaseDetail. This call's response always includes information on the current status of the case, a log of activities in the case, the monetary amount involved in the case, and the buyer's initial expectation from the seller in order to resolve the case. Based on the status and results of the case, details on monetary transactions, case decisions, case appeals, uploaded proof documents (UK and DE only), Return Merchandise Authorization number (UK and DE only), refund amounts, and shipping information is also returned.

If a seller is interested in all cases and disputes, a case type filter should not be used in the getUserCases call. For all case types other than eBay Buyer Protection cases, a second call to GetDispute of the Trading API will be required to get detailed information about a specific case or dispute.

Currently, a seller is not in control of where a buyer opens a case or files a dispute (through Resolution Center, PayPal, or other online dispute console). Due to this fact, it is advised that they make periodic calls to getUserCases, and then subsequently make an additional call to getEBPCaseDetail or GetDispute, depending on the type of case(s) that have been opened against them.

Calling getUserCases

To retrieve eBay Buyer Protection cases or other cases or disputes, a call to getUserCases is necessary. There are no required input parameters for getUserCases, and a call with no parameters in the request will retrieve all open and closed cases and disputes created within the last 90 days. To retrieve cases and disputes older than 90 days, a date range filter and an item filter must be used. Based on the seller's activity, the number of cases returned can be very large. Due to the possibility of a large result set, the caller should consider using filtering and/or pagination, which are discussed in the next two sections.

Using Filtering in getUserCases

The following four filter types are available to use in the getUserCases request:

See the getUserCases API Reference for more information on case filtering.

Using Pagination in getUserCases

If you expect the response payload of a getUserCases call to be large, pagination can be used to control the number of cases returned per page of data. If there are multiple pages of cases to view, you can programmatically "scroll" through the pages by making subsequent calls, incrementing the paginationInput.entriesPerPage value by 1 each time until all pages have been viewed and/or handled.

See the getUserCases API Reference for more information on pagination.

The getUserCases Response

The getUserCases response provides the seller a snapshot of the cases in which they are involved. Each case is wrapped in a caseSummary node under the cases container. The following are three key fields in the caseSummary node:

See the getUserCases API Reference for more information on the getUserCases response. See the Trading API Reference for more information on GetDispute and other dispute-related calls in the Trading API.

Common Errors for getUserCases Call

The following are some common errors that can occur when using filtering with the getUserCases call:

Calling getEBPCaseDetail

The getEBPCaseDetail call is used to retrieve detailed information on an open or closed eBay Buyer Protection case. This call may be used by the seller numerous times during the duration of a case to track the status of the case.

Only the case ID and case type are required in the getEBPCaseDetail request. The case ID can be obtained with the getUserCases call. The case type will either be "EBP_INR", "EBP_SNAD", or "RETURN", based on whether it is an Item Not Received, a Significantly Not As Described item, or a Return (UK and DE only) case. If the caseId.id and caseId.type values don't match, the request is processed (if caseId.id is valid) but a warning message is returned.

The two containers returned at the root level of the getEBPCaseDetail response are caseSummary and caseDetail.

The caseSummary container consists of static information such as case ID, case type, case creation date, the user IDs of parties involved, item information, and monetary amount involved in the case.

The caseDetail container consists mostly of dynamic information, including a log of case activity and a log of money movement transactions (if any). Depending on the status of the case, case decisions, case appeals, refund amounts, uploaded proof documents (UK and DE only), Return Merchandise Authorization number, and shipping information is also returned in this container.

See the getEBPCaseDetail API Reference for more information on the getEBPCaseDetail response.

Determining Next Action with getActivityOptions

The getActivityOptions call returns a list of the next possible actions that a seller can make on a case. For sellers, the next possible action(s) may be apparent just by looking at the getEBPCaseDetail response, but calling getActivityOptions can confirm the possible action(s).

Based on the status of the case, the following activity options may be returned to the seller under a separate activityOptions container:

Providing Shipping Information

There are three Resolution Case Management calls available to the seller to provide shipping information to the buyer. The provideTrackingInfo and provideShippingInfo calls are typically used by the seller when an original item, a replacement item, or a missing/replacement part is en route to the buyer. The provideReturnInfo call (available to German sellers only) is used by the seller to provide a return address to the buyer who is returning a Significantly Not As Described item to the seller.

Overview of provideTrackingInfo

The provideTrackingInfo call requires the case ID and case type (EBP_INR or EBP_SNAD only), as well as the shipping carrier and tracking number. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. eBay checks to verify that the specified tracking number is consistent with the numbering scheme used by the specified shipping carrier, but eBay cannot verify that the tracking number is accurate. Accuracy of the tracking number is the responsibility of the seller. The optional comments field can be used to provide additional information if necessary or applicable.

Overview of provideShippingInfo

The provideShippingInfo call requires the case ID and case type (EBP_INR or EBP_SNAD only), as well as the shipping carrier and shipped date. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. The optional comments field can be used to provide additional information if necessary or applicable.

Overview of provideReturnInfo

The provideReturnInfo call requires the case ID and case type (EBP_SNAD only), as well as the seller's shipping address. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. The optional returnMerchandiseAuthorization field can be used by the seller to provide a Return Merchandise Authorization number to the buyer.

Issuing Full and Partial Refunds to the Buyer

There are five Resolution Case Management calls related to offering and issuing full and partial refunds to a buyer. All five of these calls are discussed in this section.

Issuing a Full Refund

To help resolve an open case, a seller can call issueFullRefund to issue a refund to the buyer. For a Significantly Not As Described case, the seller will typically use the offerRefundUponReturn call to remind the buyer that a Significantly Not As Described item must be returned before a full refund is given.

Overview of issueFullRefund

The issueFullRefund call requires the case ID and case type. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. Sellers should be very careful about providing the correct case ID, so a refund is issued to the right buyer in the right case. The optional comments field can be used to provide additional information if necessary or applicable.

The possible results of the call are SUCCESS, FAILED, or AGREED. A SUCCESS value in the response indicates that the refund has been processed by the PayPal system. A FAILED value in the response indicates that the refund failed and does not indicate that the call request failed. If the call request does fail, The errorMessage container should contain the error(s) that caused the refund request to fail. An AGREED value in the response indicates that the refund will be processed in a non-PayPal system. If the fullRefundStatus value is AGREED, a refundDate field is also returned in the response which indicates the approximate date in which the non-PayPal refund will be processed. Non-PayPal refunds cannot be tracked or confirmed by eBay.

Overview of offerRefundUponReturn

The offerRefundUponReturn call requires the case ID and case type (EBP_SNAD only). If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. This call is only applicable to Significantly Not As Described cases, and is used to remind the buyer that a Significantly Not As Described item must be returned before a full refund is given. The offerRefundUponReturn call also allows sellers to specify a specific return address, to specify a Return Merchandise Authorization number, or to include additional return instructions.

Issuing a Partial Refund

To help resolve a Significantly Not As Described case, a seller can issue a partial refund to a buyer. The two required calls to issue a partial refund are offerPartialRefund and issuePartialRefund. Both calls can only be used if the item was purchased with PayPal as the payment method.

Overview of offerPartialRefund

The offerPartialRefund call is used by the seller to propose a partial refund amount to the buyer in order to resolve a Significantly Not As Described case. In the request, the seller is required to pass in the case ID and case type (EBP_SNAD only), as well as the amount field. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. The optional comments field can be used to provide additional information if necessary or applicable.

Overview of issuePartialRefund

The issuePartialRefund call is used by the seller to issue a partial refund amount to the buyer in order to resolve a Significantly Not As Described case. In the request, the seller is required to pass in the case ID and case type (EBP_SNAD only), as well as the amount field. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. The optional comments field can be used to provide additional information if necessary or applicable. This call can only be used if the partial refund amount was accepted by the buyer, and the amount value must match the value in the offerPartialRefund call.

Overview of provideRefundInfo

The provideRefundInfo call can be used by German sellers to provide a customized message to the buyer regarding a full or partial refund. In the request, the seller is required to pass in the case ID and case type, as well as the refundMessage field. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned.

Uploading Proof of Shipping/Refund Documents

This call can be used by German sellers to upload one to five documents that act as proof that an item was shipped or proof that an order was fully or partially refunded. In the request, the seller is required to pass in the case ID and case type, the document container, and the proofType field. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned.

The binary representation of the proof document is passed into the document container. The two supported proof document types are PROOF_OF_SHIPPING and PROOF_OF_REFUND. The supported file types are JPEG, GIF, and PNG. The file size limit for each document is 1 MB.

Overview of offerOtherSolution

The offerOtherSolution call requires the case ID and case type (EBP_INR or EBP_SNAD only), as well as the messageToBuyer field to provide a customized message to the buyer. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned.

Escalating an Open Case

The escalateToCustomerSupport call requires the case ID and case type (EBP_INR or EBP_SNAD only), as well as the escalation reason. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. Based on whether it is an Item Not Received or Significantly Not As Described case, the seller will include either the sellerINRReason or sellerSNADReason field under the escalationReason container. See the escalateToCustomerSupport API Reference for more information on the applicable escalation reasons. The optional comments field can be used to provide additional information if necessary or applicable.

Appealing a Case Decision

The appealToCustomerSupport call requires the case ID and case type (EBP_INR or EBP_SNAD only), as well as the appeal reason. If the case ID and case type don't match, the request is processed (if case ID is valid) but a warning message is returned. The appealReason value will either be DISAGREE_WITH_FINAL_DECISION, NEW_INFORMATION, or OTHER. See the appealToCustomerSupport API Reference for more information on the appeal reasons. The optional comments field can be used to provide additional information if necessary or applicable. If 'OTHER' is used as the appeal reason, it is recommended that the seller use the comments field to justify and support the appeal reason.

Platform Notifications for eBay Buyer Protection Cases

Using the SetNotificationPreferences call of the Trading API, users can subscribe to the following platform notifications related to the activity of eBay Buyer Protection Cases. To enable and receive eBay Buyer Protection notifications, you must pass in 'eBP notification' as a string in the UserData.ExternalUserData field of the SetNotificationPreferences request.

For more information on these notifications and the Platform Notification process, see the Trading API Guide.

Back to top

Working with the Resolution Case Management API

API Call Limits

Please refer to the API Call Limits page on the eBay Developers Program site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.

Sandbox Environment

For more information about testing, refer to Testing Overview in the Making a Resolution Case Management API Call document.

API Reference

Refer to the API Reference for a list of calls in the Resolution Case Management API. The API Reference includes the following information:

Back to top

Additional Resources

You can get more information about the eBay Resolution Case Management API at these locations:

Copyright © 2009–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.