Making a Call

Note: All calls in the Merchandising API have been deprecated as of July 29, 2024, and will be decommissioned on January 6, 2025.

This document explains how to make a Merchandising API call. It provides an overview of the formats and parameters you can use with the Merchandising API.

Supported Request and Response Formats
Call Structure
Syntax
Testing Overview
Schema Location

Supported Request and Response Formats

The Merchandising API supports a variety of request and response formats. Here's a list of the supported request formats and the response formats supported by each:

Name-Value Pairs

The HTTP GET call method passes values in the URL using name-value (NV) pairs. The HTTP POST method can also be used with name-value pairs, but the HTTP GET method is the often the preferred method for calls that simply retrieve information. If you pass a name-value request using HTTP POST, you must specify the request data format.

Here's an example of a URL-style name-value pair request (wrapped for readability):

https://svcs.ebay.com/MerchandisingService?OPERATION-NAME=getMostWatchedItems
   &SERVICE-NAME=MerchandisingService
   &SERVICE-VERSION=1.1.0
   &CONSUMER-ID=YourAppID
   &RESPONSE-DATA-FORMAT=XML
   &REST-PAYLOAD
   &categoryId=267

By default, the call response for NV requests is in XML format, but you can specify NV or JSON as a response format, if desired.

JSON

JSON requests can be submitted using HTTP POST. Name-value requests using the HTTP GET (URL) method support responses in JSON format. JSON format requests are supported via HTTP POST, as well.

Here's an example of a JSON request that can be submitted via HTTP POST:

{"jsonns.xsi":"https://www.w3.org/2001/XMLSchema-instance",
"jsonns.xs":"https://www.w3.org/2001/XMLSchema",
"jsonns.tns":"https://www.ebay.com/marketplace/services",
"tns.getMostWatchedItemsRequest":
	{
	"categoryId":"267"
	}
}

By default, the call response for JSON requests is in XML format, but you can specify NV or JSON as a response format, if desired.

XML

The HTTP POST call method supports the use of XML format requests. The default response format for XML requests is also XML.

<getMostWatchedItemsRequest xmlns="https://www.ebay.com/marketplace/services">
   <categoryId>267</categoryId>
</getMostWatchedItemsRequest>

By default, the call response for XML requests is in XML format, but you can specify NV or JSON as a response format, if desired.

SOAP

The HTTP POST call method also supports the use of SOAP format requests. The default response format for SOAP requests is also SOAP. 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/services">
   <soap:Header/>
   <soap:Body>
      <getMostWatchedItemsRequest>
         <categoryId>267</categoryId>
      </getMostWatchedItemsRequest>
   </soap:Body>
</soap:Envelope>

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

Call Structure

Each Merchandising API call consists of the following elements:

Service Endpoint—all Merchandising API requests must be sent to eBay's Sandbox or Production API Gateway (endpoint)
HTTP Headers or URL Parameters—each Merchandising API call requires some HTTP headers or URL parameters. For example, you must specify your AppID in the EBAY-SOA-CONSUMER-ID header or CONSUMER-ID URL parameter. Similarly, you must always specify the call name in the X-EBAY-SOA-OPERATION-NAME header or X-EBAY-SOA-OPERATION-NAME URL parameter. Other headers are optional or conditionally required.
Standard Input Fields—each Merchandising API call supports the affiliate field and related fields for specifying affiliate information and the maxResults input field for limiting the size of the result set. The standard input fields are optional.
Call-specific Fields—some input fields, such as keywords or categoryId are specific to a particular Merchandising API call

Some Merchandising API input values are standard and others are call-specific, as in the following HTTP GET example:

Call Structure

Service Endpoints

All Merchandising API requests must be sent to either the eBay Sandbox or Production API Gateway. You specify the gateway URI in the request.

Production Gateway URL (endpoint):

https://svcs.ebay.com/MerchandisingService

Sandbox Gateway URL (endpoint):

https://svcs.sandbox.ebay.com/MerchandisingService

Standard HTTP Header or URL Parameter Values

When you make a Merchandising API call, you choose whether to specify a standard value, such as call name or response format, in a URL parameter or in the HTTP header. When you make an HTTP GET (URL format) request, you always use URL parameters. When you make an HTTP POST request, you can use either URL parameters or HTTP headers or a combination.

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. In most cases it is easier to use URL parameters rather than HTTP headers. The order of the parameters is not important, however, the values you provide in your call (such as the value for your AppID) are case sensitive.

Note: In the Trading API, SOAP users specify their user credentials in the SOAP header of the request. For the Merchandising API, no URL parameters or HTTP headers, including EBAY-SOA-CONSUMER-ID can be specified in the SOAP header.

The following table contains descriptions of standard Merchandising API parameters and the corresponding headers:

URL Parameter Header Value Required? Description

CONSUMER-ID EBAY-SOA-CONSUMER-ID Yes This is the application ID (AppID) for the service consumer. You obtain an AppID by joining the eBay Developers Program.

N/A

CONTENT-TYPE

Specifies the media type of the request. This HTTP header is optional. If you do not submit the CONTENT-TYPE header with your request, eBay will determine the content type from the payload.

The following values can be used with the supported HTTP POST request formats:

Request Payload Format	CONTENT-TYPE Value
XML	text/xml
SOAP11	text/xml (together with the SOAPAction header, for which the value can be anything)
SOAP12	application/soap+xml

GLOBAL-ID X-EBAY-SOA-GLOBAL-ID No The unique identifier for a combination of site, language, and territory. For example, EBAY-US 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 (see eBay Site ID to Global ID Mapping). See Global ID Values for a complete list of the eBay global IDs.

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.

OPERATION-NAME X-EBAY-SOA-OPERATION-NAME Yes The name of the call you are using (for example, getMostWatchedItems for getMostWatchedItems).

REQUEST-DATA-FORMAT X-EBAY-SOA-REQUEST-DATA-FORMAT Conditionally The Merchandising API supports NV, JSON, XML, and SOAP request formats with the HTTP POST method. Input can be in the following formats: NV, JSON, or XML (used for XML or SOAP). The default value for HTTP POST requests is XML.
For SOAP requests, you must specify the protocol version in the X-EBAY-SOA-MESSAGE-PROTOCOL header. If you use a URL for an HTTP GET request, REQUEST-DATA-FORMAT is unnecessary because the only valid value is NV (Name-Value Pair).

RESPONSE-DATA-FORMAT X-EBAY-SOA-RESPONSE-DATA-FORMAT No Use this parameter to specify the output format as JSON, XML (used for XML or SOAP), or NV (Name-Value Pair). If you use a URL, and you do not specify REQUEST-DATA-FORMAT, the output format will be XML. If you use the HTTP POST method, the output data (response data) for SOAP requests will be in SOAP format. The default for other request formats will be XML.

REST-PAYLOAD N/A No If you use a URL, use this header 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 header is ignored for HTTP POST requests.

SERVICE-NAME X-EBAY-SOA-SERVICE-NAME No The name of the eBay API you are using. Specify "MerchandisingService" for all Merchandising API calls.

SERVICE-VERSION X-EBAY-SOA-SERVICE-VERSION No The API version your application supports.

URL 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, JSON, or XML. The following example shows standard Merchandising API parameters. The RESPONSE-DATA-FORMAT header specifies NV for Name-Value Pair output.

https://svcs.ebay.com/MerchandisingService?OPERATION-NAME=getMostWatchedItems
   &SERVICE-NAME=MerchandisingService
   &SERVICE-VERSION=1.0.0
   &CONSUMER-ID=YourAppID
   &RESPONSE-DATA-FORMAT=NV
   &REST-PAYLOAD
   &maxResults=3
   &category=267

HTTP Header Examples

The following example shows standard Merchandising API headers for an HTTP POST call (which uses the same endpoint as an HTTP GET call). The X-EBAY-API-REQUEST-DATA-FORMAT header specifies XML for XML input (this is also used for SOAP requests).

X-EBAY-SOA-OPERATION-NAME: getMostWatchedItems
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
EBAY-SOA-CONSUMER-ID: YourAppIDHere
X-EBAY-SOA-GLOBAL-ID: EBAY-US
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML

The following example shows standard Merchandising API headers for an HTTP POST call. The X-EBAY-API-REQUEST-DATA-FORMAT header specifies XML for XML or SOAP input, and the example includes X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP11 to specify you are using SOAP Version 1.1.

X-EBAY-SOA-OPERATION-NAME: getMostWatchedItems
X-EBAY-API-VERSION: 1.0.0
EBAY-SOA-CONSUMER-ID: YourAppIDHere
X-EBAY-SOA-GLOBAL-ID: EBAY-US
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML
X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP11

Standard Input Values

Each call in the Merchandising API supports the standard input fields:

affiliate—Container for specifying affiliate details. eBay uses the specified affiliate information to build a View Item URL and Product URL string with correctly formatted affiliate tracking information, which it returns in the response.
maxResults—Specifies the maximum number of entries to return in a single call response.

These fields are optional. For more information, refer to the Merchandising API Call Reference.

Call-Specific Values

In addition to standard and affiliate-related fields, most calls have call-specific input fields. For example, the getRelatedCategoryItems call requires either categoryId or itemId as input.

If you are using the HTTP GET method, you always are specifying standard and call-specific input fields in a URL. If you are using the HTTP POST method, standard and call-specific input fields are specified in your HTTP message.

Refer to the Merchandising API Call Reference for comprehensive documentation of the input and output fields supported by the Merchandising 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.

Name-value Syntax
JSON Syntax
XML Syntax
SOAP Syntax

Name-value Syntax

Name-value requests/responses follows the syntax rules for the query string part of a URI. The query string is the portion of the URI that follows the endpoint. The query string is separated from the endpoint by a question mark ("?"). The query string consists of a series of name-value pairs separated by ampersands ("&"). The name always precedes the value and they are separated by an equals sign ("=").

The following sections outline syntax rules specific to the name-value request/response format.

Array Syntax

In an array of fields in a name-value response, such as multiple item entries in an itemRecommendations container, parenthetic notation is used to enumerate the entries in the array.

...
&itemRecommendations(0).item(0).itemId(0)="3**********7"
&itemRecommendations(0).item(0).title(0)="3X Color Hard Case Skin Cover for Apple iPhone 3G / 3GS"
...
&itemRecommendations(0).item(1).itemId(0)="3**********2"
&itemRecommendations(0).item(1).title(0)="3X Color Hard Case Skin Cover for Apple iPhone 3G / 3GS"
...
&itemRecommendations(0).item(2).itemId(0)="3**********1"
&itemRecommendations(0).item(2).title(0)="3x Rubber Hard Case Cover Skin For Apple iPhone 3G 3GS"
...

Specifying Attributes

Attributes require a special syntax when used in name-value requests, such as to specify the currency for the maxPrice field in a getSimilarItems request (e.g., <maxPrice currencyId="USD">15.0</maxPrice>). In URL/NV requests (and responses) are attributes preceded by an at sign ("@"). For example, the maximum price would be specified as in the following example:

...&maxPrice.@currencyId=USD&maxPrice=15.0...

JSON Syntax

The JSON request/response format follows standard JSON grammar rules. Please see RFC 4627 for more information.

Specifying Attributes

Attributes follow standard JSON grammar rules, but when an field has both an attribute and a value, the value requires a special representation. For example, the getSimilarItems call requires the use of an attribute to specify the currency for the maximum price (e.g., <maxPrice currencyId=UDS>15.0</maxPrice>). In JSON requests (and responses) attributes are preceded by an at sign ("@") and the maximum price value is represented with a "__value__" name.

Here's an example of how to specify the maximum price:

..."maxPrice":{"@currencyId":"USD","__value__":"15.0"}...

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 test calls using the Production environment (that is, using the https://svcs.ebay.com/MerchandisingService? endpoint).

You also can test calls using the Sandbox environment (that is, using the https://svcs.sandbox.ebay.com/MerchandisingService? endpoint). In the Sandbox environment, an application can perform the same operations it would in the Production environment, except that the users, items, and payments are just test data. The test data cannot be accessed from, or used in, the Production environment.

Some functionality that is available in the Production environment is not available in the Sandbox environment.

For the Merchandising API, the Production environment usually is for testing because the Production environment has live data and the Merchandising calls do not alter item or user data. However, if an application uses both the Merchandising API and the Trading API together (e.g., to use PlaceOffer), the Sandbox environment must be used for testing.

Schema Location

You can use the following link to download the latest WSDL for the Merchandising API:

https://developer.ebay.com/webservices/merchandising/latest/MerchandisingService.wsdl

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

https://developer.ebay.com/webservices/merchandising/VERSION/MerchandisingService.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/merchandising/1.0.0/MerchandisingService.wsdl