Making a Call
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.
This document explains how to make Resolution Case Management API calls. It provides an overview of the formats and parameters you can use with the Resolution Case Management API.
- Introduction to Service
- Supported Request and Response Formats
- Call Structure
- Testing Overview
- Schema Location
Introduction to Service
Resolution Case Management API is a SOA service that is intended to be consumed by sellers who are interested in retrieving, tracking, managing, and resolving all eBay Buyer Protection Item Not Received and Significantly Not As Described cases opened by buyers in the eBay Resolution Center. High-level information for the service are covered below, including service endpoints, HTTP headers and URL parameters, naming conventions, and versioning scheme.
- Service Endpoints—The Resolution Case Management API has unique gateway
URLs (service endpoints) for the Production environment and the Sandbox environment. The
service endpoint includes the service version (e.g.,
v1). When updating to a new major version of the service, you must update to a new service endpoint as well.
- HTTP headers and URL parameters—The Resolution Case Management API uses
eBay's Service Oriented Architecture (SOA) framework and requires that an eBay
authorization token is passed in through a (
X-EBAY-SOA-SECURITY-TOKEN) header or (
SECURITY-TOKEN) URL parameter.
- Schema and data type notes—The Resolution Case Management API does not
share schema or data types with other eBay APIs. In the API, you will find the following
differences from other eBay APIs:
- No site ID! Instead, we provide globalId, a unique identifier for a combination of site, language, and territory. See the Global ID Values table for a list of global IDs that map to site IDs. The global ID you use must map to an eBay site with a site ID.
- XML namespace is versioned. To prevent type collisions associated with backward incompatible service changes, the XML namespace is versioned. As with the service endpoint, when updating to a new major version of the service, note that the XML namespace will change as well.
- Naming conventions—The naming conventions for the Resolution Case Management API are slightly different than the Trading API. Most notably, call names and fields in the Resolution Case Management API begin with lowercase letters.
- Versioning scheme—The version numbering scheme for the Resolution Case Management API is different from the scheme used by the eBay Shopping and Trading APIs. The Resolution Case Management API version consists of three digits (e.g., 1.2.3):
- The first digit indicates the major release version. Major releases are not backward compatible. eBay supports the two most recent major versions of the service. The service endpoints and target namespace include the major version of the service.
- The second digit indicates the minor release version. Minor releases consist of feature additions or behavior changes that are backward compatible.
- The third digit indicates the maintenance, or micro release version. Maintenance releases are used to correct minor problems. Maintenance releases have minimal impact on the features or functionality of the API. These changes may or may not have associated schema changes.
This call returns eBay Buyer Protection cases, older disputes, disputes created through PayPal, and Unpaid Item disputes created through the Trading API. Without using filters in the request, the call returns all cases and disputes from the last 90 days. The authenticated caller has the choice to filter by date range, by case type, or by case status. Additionally, the caller has the option of returning cases for a specific item or transaction. For more information on the getUserCases call, see the Users Guide.
This call returns the details of a single eBay Buyer Protection case. The caseID that is returned in the getUserCases call is passed into the caseID field of the getEBPCaseDetail request. For more information on the getEBPCaseDetail call, see the Users Guide.
This call returns a list of the next possible actions that a seller can make on a case. A case ID is passed into the request. For more information on the getActivityOptions call, see the Users Guide.
This call allows the seller to escalate an open case to eBay customer support. A case ID and the escalation reason is passed into the request.
This call is used by sellers to inform the buyer that the Significantly Not As Described item must be returned before a full refund can be issued. A case ID is passed into the request. Optionally, the seller can include a Return Merchandise Authorization number, a return address (if different from seller's default shipping address), and additional return instructions.
This call allows the seller to issue a full refund to the buyer in order to resolve an open case. A case ID is passed into the request.
This call allows a seller to offer a partial refund to a buyer to help resolve an eBay Buyer Protection Significantly Not As Described case. A case ID and the partial refund amount is passed into the request.
This call allows a seller to issue a partial refund to a buyer to help resolve an eBay Buyer Protection Significantly Not As Described case. The partial refund amount must have approval from the buyer before issuePartialRefund is used. A case ID and the partial refund amount is passed into the request. The partial refund amount must match the amount proposed to and accepted by the buyer. This call can only be used if the payment method is PayPal.
This call allows the seller to provide the shipping carrier and shipped date to a buyer if the seller is sending the original item, a replacement item, or missing/replacement parts to the buyer. A case ID, the shipping carrier, and the shipped date is passed into the request. If a German seller has any supporting documents that will act as proof that an item was shipped to the buyer, the seller can upload one to five documents using the uploadDocuments call.
This call allows the seller to provide tracking information to a buyer if the seller is sending the original item, a replacement item, or missing/replacement parts to the buyer. A case ID, the shipping carrier, and the tracking number is passed into the request.
This call is used by the seller to provide an alternative shipping address to the buyer who is returning an item. In this case, an "alternative" shipping address is one other than the default shipping address listed for the seller. A case ID and a shipping address is passed into the request. Optionally, the seller can supply a Return Merchandise Authorization number to the buyer.
This call allows the seller to offer the buyer a customized solution in order to resolve an open case. A case ID and a message to the buyer is passed into the request.
This call is used by a seller (Germany only) to provide a customized message to the buyer regarding an item refund. A case ID and a refund message is passed into the request. If a German seller has any supporting documents that will act as proof that a refund was issued to the buyer, the seller can upload one to five documents using the uploadDocuments call.
This call is used by a seller (Germany only) to upload one or more documents that act as proof that an item was shipped or proof that an order was fully or partially refunded. A case ID, a binary representation of a document, and the document type is passed into the request.
This call allows the seller to make an appeal to eBay customer support after an unfavorable case decision. A case ID and the appeal reason is passed into the request.
This call returns the current version of the Resolution Case Management service. This call has no input parameters.
Supported Request and Response Formats
The Resolution Case Management API supports XML and SOAP request and response formats.
The HTTP POST call method supports the use of XML format requests.
<getEBPCaseDetail xmlns="https://www.ebay.com/marketplace/resolution/v1/services"> </getEBPCaseDetail>
The HTTP POST call method also supports the use of SOAP format requests. SOAP versions 1.1 and 1.2 are both supported.
<soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope" xmlns="https://www.ebay.com/marketplace/resolution/v1/services"> <soap:Header/> <soap:Body> <getEBPCaseDetail> </getEBPCaseDetail> </soap:Body> </soap:Envelope>
The call response for SOAP requests is in SOAP format only.
Each Resolution Case Management API call consists of the following elements:
- Service Endpoint—Resolution Case Management API requests can be sent to either the Production API Gateway (endpoint) or the Sandbox endpoint for the Resolution Case Management API.
- HTTP Headers or URL Parameters—Each Resolution Case Management API call requires a
X-EBAY-SOA-SECURITY-TOKENheader or a
SECURITY-APPNAMEURL parameter. Similarly, you must always specify the call name in the
OPERATION-NAMEURL parameter. Other headers are optional or conditionally required.
- Standard Input Fields—The ExtensionType field and its four child elements are the only standard input fields for calls in the Resolution Case Management API. These fields are optional.
- Call-specific Fields—The input fields that are specific to a particular API call.
Resolution Case Management API requests may be sent to either the eBay Production API Gateway URI (endpoint) or the eBay Sandbox endpoint. You specify the endpoint in the request.
|Note: The service endpoint contains the major version for the service (e.g.,
Standard URL Parameter or HTTP Header Values
When you make a Resolution Case Management API call, you choose whether to specify the standard values in URL parameters or in the HTTP header. URL parameters are provided as name-value pairs in the query part of the URI.
|Note: If you specify both a URL parameter and an HTTP header for the same value in the same call, the URL parameter takes precedence. The values you provide in your call are case-sensitive.|
The following table contains descriptions of the standard Resolution Case Management API parameters and the corresponding header values:
|URL Parameter||Header Value||Required?||Description|
|N/A||CONTENT-TYPE||No||If you use this header, you must specify the content format exactly as shown, or your call may fail. The allowable values are:
|GLOBAL-ID||X-EBAY-SOA-GLOBAL-ID||No||The unique identifier for a combination of site, language, and territory. For example, EBAY-US (the default) is the global ID that corresponds to the eBay US site. The global ID you specify must correspond to an eBay site with a valid site ID. Refer to eBay Site ID to Global ID Mapping. In addition, Global ID Values contains a complete list of the eBay global IDs.|
|MESSAGE-ENCODING||X-EBAY-SOA-MESSAGE-ENCODING||Conditionally||Specifies the message encoding (e.g., ISO-8859-1). The default encoding is UTF-8. When submitting requests in any format other than UTF-8, you must specify the message encoding.|
|N/A||X-EBAY-SOA-MESSAGE-PROTOCOL||Conditionally||If you make a SOAP request, you must use this header to specify the protocol you are using. Allowable values are "SOAP11" for SOAP Version 1.1 and "SOAP12" for SOAP Version 1.2.|
|SERVICE-NAME||X-EBAY-SOA-SERVICE-NAME||No||The name of the service you are using. Specify "ResolutionCaseManagementService" for all Resolution Case Management API calls.|
|OPERATION-NAME||X-EBAY-SOA-OPERATION-NAME||Yes||The name of the call you are using (for example, getUserCases or getEBPCaseDetail).|
|REQUEST-DATA-FORMAT||X-EBAY-SOA-REQUEST-DATA-FORMAT||No||The Resolution Case Management API supports XML and SOAP request formats with the HTTP POST method. Input can be in XML or SOAP formats. The default value for HTTP POST requests is XML.
For SOAP requests, you must specify the protocol version in the
|RESPONSE-DATA-FORMAT||X-EBAY-SOA-RESPONSE-DATA-FORMAT||No||If you use a URL (HTTP GET) request, use this parameter to specify the output format as XML. URL requests do not support SOAP responses. If you use a URL, and you do not specify RESPONSE- DATA-FORMAT, the output format will be XML. If you use the HTTP POST method, the output data (response data) will be in the same format as the input data.|
|REST-PAYLOAD||N/A||No||If you use a URL, use this parameter to separate the payload part of the URL from the standard headers. Requires no value; anything appearing after this header will be considered part of the call payload. This parameter is ignored in HTTP POST requests.|
|SECURITY-TOKEN||X-EBAY-SOA-SECURITY-TOKEN||Yes||This header is used to pass in the eBay authorization token, unique to the user's application. You obtain an eBay authorization token by joining the eBay Developers Program.|
|SERVICE-VERSION||X-EBAY-SOA-SERVICE-VERSION||No||The API version your application supports (e.g., 1.1.0).|
URL Parameter Examples
If you are using a URL (and the HTTP GET method), input must be in the NV (Name-Value Pair)
format. Use the
RESPONSE-DATA-FORMAT header to specify that data is returned in one
of the following formats: NV or XML. The following example (wrapped for readability) shows
standard Resolution Case Management API parameters.
RESPONSE-DATA-FORMAT specifies XML
for XML output.
https://svcs.ebay.com/services/resolution/ResolutionCaseManagementService/v1?OPERATION-NAME=getUserCases &SERVICE-NAME=ResolutionCaseManagementService &SERVICE-VERSION=1.0.0 &SECURITY-TOKEN=<eBayAuthToken> &RESPONSE-DATA-FORMAT=XML &REST-PAYLOAD &Standard input fields &Call-specific input fields
HTTP Header Examples
The following example shows standard Resolution Case Management API headers for an HTTP POST call using XML:
X-EBAY-SOA-SERVICE-NAME: ResolutionCaseManagementService X-EBAY-SOA-OPERATION-NAME: getUserCases X-EBAY-SOA-SERVICE-VERSION: 1.1.0 X-EBAY-SOA-SECURITY-TOKEN: <eBayAuthToken> X-EBAY-SOA-REQUEST-DATA-FORMAT: XML
The following example shows standard Resolution Case Management API headers for an HTTP POST call. In the
X-EBAY-SOA-REQUEST-DATA-FORMAT header specifies XML. The example also includes
X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12, specifying that you are using
SOAP Version 1.2. Without the
X-EBAY-SOA-MESSAGE-PROTOCOL header, the
service would expect XML input.
X-EBAY-SOA-SERVICE-NAME: ResolutionCaseManagementService X-EBAY-SOA-OPERATION-NAME: getUserCases X-EBAY-SOA-SERVICE-VERSION: 1.1.0 X-EBAY-SOA-GLOBAL-ID: EBAY-US X-EBAY-SOA-SECURITY-TOKEN: <eBayAuthToken> X-EBAY-SOA-REQUEST-DATA-FORMAT: XML X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12
Refer to the Resolution Case Management API Reference for the input and output fields supported by the Resolution Case Management API calls.
This section spells out the syntax requirements for the supported request and response formats. In most cases, the syntax for the various formats is standard and only the rules that aren't standard or are potentially tricky are explained.
UTF-8 Encoding for Special Characters
All parameter values should be encoded in UTF-8 format. UTF-8 is the default encoding for API requests.
Once the parameter value is UTF-8 encoded, it should be URL-encoded to take care of spaces and quotation marks (" ") and other characters in the string that are pertinent to the URL request.
When submitting requests in any format other than UTF-8, you must specify the message encoding with the
MESSAGE-ENCODING URL parameter or the
X-EBAY-SOA-MESSAGE-ENCODING HTTP header.
URL Encoding for String Values
Name-value requests must be constructed using the ASCII character-set only. Most ASCII characters (e.g., the numbers from 0-9 and the uppercase and lowercase English letters from A to Z) can be used as is. Some special characters, however, such as spaces, ampersands ("
&") and quotation marks, must be encoded in URL requests when used in string values for fields.
Special characters that must be URL-encoded include (but are not limited to) characters used in URL request syntax, such as ampersands ("
&"), the equals sign ("
="), the pound sign ("
#"), the "at" symbol ("
@"), or the percent sign ("
URL-encoded characters are in the form %HH, where HH is a hexadecimal number. For example, the URL-encoded value for an ampersand is
%26 and the URL-encoded value for a space is
%20. The plus sign ("+") can also be used in place of spaces.
Many languages provide functions or methods to do the URL encoding for you. For example, PHP provides the
rawurlencode function and Java provides
URLEncoder class. For more information about URL encoding, see RFC 1738.
The XML request/response format follows standard XML syntax conventions. Please see XML Syntax Rules on w3schools.com for more information.
The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on w3schools.com for more information.
You can use the Sandbox environment (with the
https://svcs.sandbox.ebay.com/services/resolution/v1/ResolutionCaseManagementService endpoint) to test calls to the Resolution Case Management API.
You can download the latest version of the WSDL for the Resolution Case Management API with the following link:
Alternatively, you can access a particular version of the Resolution Case Management schema using a URL with the following format (where VERSION is the version identifier of the release):
The version identifier is the version number of a particular schema (a release number).
For example, you can access version 1.0.0 of the WSDL version of the schema at the following URL: