eBay Merchandising API
|
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.
The Merchandising API supports the following request and response formats.
Each Merchandising API call consists of the following elements:
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.Some Merchandising API input values are standard and others are call-specific, as in the following HTTP GET example:
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):
http://svcs.ebay.com/MerchandisingService
Sandbox Gateway URL (endpoint):
http://svcs.sandbox.ebay.com/MerchandisingService
When you make a Merchandising API call, you choose whether to specify a standard value in a URL parameter or in the HTTP header. For example, you could specify the following getMostWatchedItems call (wrapped for readability) to search for "most watched" items within category "397," which is "Clocks" on the US site. The URL parameters are used to specify the call name, service name, service version, AppID, and response format.
http://svcs.ebay.com/MerchandisingService?OPERATION-NAME=getMostWatchedItems &SERVICE-NAME=MerchandisingService &SERVICE-VERSION=1.1.0 &CONSUMER-ID=YourAppIDHere &RESPONSE-DATA-FORMAT=XML &categoryId=397
Note: If you specify both a URL parameter and a 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, and the order of the parameters is not important. The values you provide in your call (such as the value you provide for your AppID) are case sensitive.
The following table contains descriptions of standard Merchandising API parameters and the corresponding headers:
| URL Parameter | Header Value | Required? | Description |
|---|---|---|---|
| callback | N/A | N | Applies only in cases where the response data is in JSON format. The response data is wrapped in a call to the specified function, to make the response data easier to use. This parameter specifies the name of the function that is returned. For example, if you use the getMostWatchedItems call and you specify callback=cb_getMostWatchedItems, then the response data will be wrapped in a call to a cb_getMostWatchedItems() function. |
| 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. Note: This value and other standard values cannot be specified in a SOAP header. |
| 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 getTopSellingProducts). |
| N/A | X-EBAY-SOA-REQUEST-DATA-FORMAT | No | 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). If you use the HTTP POST method, input can be in the following formats: XML (used for XML or SOAP) or NV. |
| RESPONSE-DATA-FORMAT | N/A | No | If you use a URL, 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) will be in the same format as the input data. |
| 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. |
Each call supports the standard input fields, such as the affiliate fields (e.g., affiliate.customId and affiliate.networkId) and maxResults. These fields are optional. For more information, refer to the Merchandising API Call Reference.
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.
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 shows standard Merchandising API parameters. The RESPONSE-DATA-FORMAT header specifies NV for Name-Value Pair output, and can be changed to XML for XML output.
http://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
If you are using the HTTP POST method, use the X-EBAY-SOA-REQUEST-DATA-FORMAT header to specify your input is in one of the following formats: XML or SOAP. The output (response data) will be in the same format as the input by default, so there is no need to specify a X-EBAY-SOA-RESPONSE-DATA-FORMAT (or RESPONSE-DATA-FORMAT) value. If you want an output format that is different from your input format, however, use X-EBAY-SOA-RESPONSE-DATA-FORMAT to specify the response format.
The following example shows standard Merchandising API headers for an HTTP POST call (which uses the same
http://svcs.ebay.com/MerchandisingService? endpoint as a GET call). The X-EBAY-API-REQUEST-ENCODING 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 (which uses the same
http://svcs.ebay.com/MerchandisingService endpoint as a GET call). The X-EBAY-API-REQUEST-ENCODING 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
You can test calls using the Production environment (that is,
using the http://svcs.ebay.com/MerchandisingService? endpoint).
You also can test calls using the Sandbox environment (that is,
using the http://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.
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:
http://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:
http://developer.ebay.com/webservices/merchandising/1.0.0/MerchandisingService.wsdl
Alternatively, you can use the following link to download the latest WSDL for the Merchandising API:
http://developer.ebay.com/webservices/merchandising/latest/MerchandisingService.wsdl