Making a Call

This document explains how to make Return Management API calls. It provides an overview of the formats and parameters you can use with the Return Management API.

• Introduction to Service
  • getActivityOptions Call
  • getReturnDetail Call
  • getReturnMetadata Call
  • getUserReturns Call
  • getVersion Call
  • issueRefund Call
  • provideSellerInfo Call
  • provideTrackingInfo Call
  • setItemAsReceived Call
• Supported Request and Response Formats
  • XML
  • SOAP
• Call Structure
  • Service Endpoints
  • Standard URL Parameter or HTTP Header Values
  • Call-Specific Values
• Syntax
  • UTF-8 Encoding for Special Characters
  • URL Encoding for String Values
  • XML Syntax
  • SOAP Syntax
• Testing Overview
• Schema Location

Introduction to the Return Management API

Return Management API is a SOA service that provides US and UK sellers a programmatic way to retrieve and manage buyer returns initiated through the eBay Return 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 Return 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 or URL Parameters—For XML and SOAP requests, each Return Management API call requires an X-EBAY-SOA-SECURITY-TOKEN header or a SECURITY-TOKEN URL parameter. Similarly, you must always specify the call name in the X-EBAY-SOA-OPERATION-NAME header or OPERATION-NAME URL parameter. For XML requests, the CONTENT-TYPE:text/xml is also required. All other headers (covered below) are either optional or conditionally required.
• Schema and data type notes—The Return 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 Return Management API are slightly different than the Trading API. Most notably, call names and fields in the Return Management API begin with lowercase letters.
• Versioning scheme—The version numbering scheme for the Return Management API is different from the scheme used by the eBay Shopping and Trading APIs. The Return 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.

getActivityOptions Call

This call is used by the seller to retrieve one or more actions that can be performed based on the status of the return. For more information on the getActivityOptions call, see the Users Guide.

getReturnDetail Call

This call is used by the seller to retrieve detailed information about a specific return. For more information on the getReturnDetail call, see the Users Guide.

getReturnMetadata Call

This call is used by the seller to retrieve all applicable return reasons, the maximum number of business days a seller has to issue a refund to the buyer after the seller receives the returned item, and the maximum number of business days a seller has to provide a Return Merchandise Authorization number (if an RMA is requested) to the buyer once a return is opened. For more information on the getReturnMetadata call, see the Users Guide.

getUserReturns Call

This call is used by the seller to retrieve returns in which the eBay member is involved as a buyer or seller. For more information on the getUserReturns call, see the Users Guide.

getVersion Call

This call returns the current version of the Return Management service. This call has no input parameters.

issueRefund Call

This call is used by the seller to issue a refund to the buyer. For more information on the issueRefund call, see the Users Guide.

provideSellerInfo Call

This call is used by a seller to provide a Return Merchandise Authorization number and/or update the return shipping address. For more information on the provideSellerInfo call, see the Users Guide.

provideTrackingInfo Call

This call is used by a seller to provide shipment tracking information to the buyer regarding a replacement item. For more information on the provideTrackingInfo call, see the Users Guide.

setItemAsReceived Call

This call is used by a seller to mark a replacement item as received. For more information on the setItemAsReceived call, see the Users Guide.

Supported Request and Response Formats

The Return Management API supports XML and SOAP request and response formats.

XML

The HTTP POST call method supports the use of XML format requests.

<getUserReturns xmlns="https://www.ebay.com/marketplace/search/v1/services">
</getUserReturns>

SOAP

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://schemas.xmlsoap.org/soap/envelope" xmlns="https://www.ebay.com/marketplace/returns/v1/services">
   <soap:Header/>
   <soap:Body>
      <getUserReturns>
      </getUserReturns>
   </soap:Body>
</soap:Envelope>

The call response for SOAP requests is in SOAP format only.

Call Structure

Each Return Management API call consists of the following elements:

• Service Endpoint—Return Management API requests can be sent to either the Production API Gateway (endpoint) or the Sandbox endpoint for the Return Management API.
• HTTP Headers or URL Parameters—For XML and SOAP requests, each Return Management API call requires an X-EBAY-SOA-SECURITY-TOKEN header or a SECURITY-TOKEN URL parameter. Similarly, you must always specify the call name in the X-EBAY-SOA-OPERATION-NAME header or OPERATION-NAME URL parameter. For XML requests, the CONTENT-TYPE:text/xml is also required. All other headers (covered below) are either 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 Return Management API. These fields are optional.
• Call-specific Fields—The input fields that are specific to a particular API call.

Service Endpoints

Return 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.

Production Endpoint:

https://svcs.ebay.com/services/returns/v1/ReturnManagementService

Sandbox Endpoint:

https://svcs.sandbox.ebay.com/services/returns/v1/ReturnManagementService

Standard URL Parameter or HTTP Header Values

When you make a Return 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.

The following table contains descriptions of the standard Return Management API parameters and the corresponding header values:

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 Return Management API parameters. RESPONSE-DATA-FORMAT specifies XML for XML output.

https://svcs.ebay.com/services/returns/v1/ReturnManagementService?OPERATION-NAME=getUserReturns
  &SERVICE-NAME=ReturnManagementService
  &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 Return Management API headers for an HTTP POST call using XML:

CONTENT-TYPE: text/xml
X-EBAY-SOA-SERVICE-NAME: ReturnManagementService
X-EBAY-SOA-OPERATION-NAME: getUserReturns
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
X-EBAY-SOA-SECURITY-TOKEN: <eBayAuthToken>
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML

The following example shows standard Return Management API headers for an HTTP POST call. In the example, 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: ReturnManagementService
X-EBAY-SOA-OPERATION-NAME: getUserReturns
X-EBAY-SOA-SERVICE-VERSION: 1.0.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

Call-Specific Values

Refer to the Return Management API Reference for the input and output fields supported by the Return Management API calls.

Syntax

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.

• XML Syntax
• SOAP Syntax

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.

XML Syntax

The XML request/response format follows standard XML syntax conventions. Please see XML Syntax Rules on w3schools.com for more information.

SOAP Syntax

The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on w3schools.com for more information.

Testing Overview

You can use the Sandbox environment (with the https://svcs.sandbox.ebay.com/services/returns/v1/ReturnManagementService endpoint) to test calls to the Return Management API.

Schema Location

You can download the latest version of the WSDL for the Return Management API with the following link:

    https://developer.ebay.com/webservices/return-management/latest/ReturnManagementService.wsdl

Alternatively, you can access a particular version of the Return Management schema using a URL with the following format (where VERSION is the version identifier of the release):

   https://developer.ebay.com/webservices/return-management/VERSION/ReturnManagementService.wsdl

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:

    https://developer.ebay.com/webservices/return-management/1.0.0/ReturnManagement.wsdl

Back to top