Product API
 

Making a Call

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

Supported Request and Response Formats

The Product and Product Metadata 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 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. 

https://svcs.sandbox.ebay.com/services/marketplacecatalog/ProductService/v1?OPERATION-NAME=findProducts
   &SERVICE-VERSION=1.3.0
   &SECURITY-APPNAME=YourAppID
   &GLOBAL-ID=EBAY-MOTOR
   &RESPONSE-DATA-FORMAT=XML
   &productSearch.invocationId=1234567890
   &productSearch.categoryId=170583
   &productSearch.keywords=brakes
   &productSearch.dataset=DisplayableSearchResults

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.

{"jsonns.xsi":"https://www.w3.org/2001/XMLSchema-instance",
"jsonns.xs":"https://www.w3.org/2001/XMLSchema",
"jsonns.tns":"https://www.ebay.com/marketplace/marketplacecatalog/v1/services",
"tns.findProductsRequest":
   {
   "productSearch":
      {
      "invocationId":"1234567890",
      "categoryId":"170583",
      "keywords":"brakes"
      }
   }
}

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.

<?xml version="1.0" encoding="UTF-8"?>
<findProductsRequest
xmlns="https://www.ebay.com/marketplace/marketplacecatalog/v1/services">
   <productSearch>
      <invocationId>1234567890</invocationId>
      <categoryId>170583</categoryId>
      <keywords>brakes</keywords>
      <dataset>DisplayableSearchResults</dataset>
   </productSearch>
</findProductsRequest>

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.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-
instance">
  <soapenv:Body>
    <findProductsRequest xmlns="https://www.ebay.com/marketplace/marketplacecatalog/v1/services">
      <productSearch>
        <invocationId>1</invocationId>
        <categoryId>170583</categoryId>
        <keywords>brakes</keywords>
        <dataset>DisplayableSearchResults</dataset>
      </productSearch>
    </findProductsRequest>
  </soapenv:Body>
</soapenv:Envelope>

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

Call Structure

Each Product and Product Metadata API call consists of the following elements:

Service Endpoints

The eBay Product and Product Metadata APIs are supported in both the eBay Production (live eBay site) and eBay Sandbox (test site) environments. You specify the gateway URI in the request.

Product Service Production Endpoint:

https://svcs.ebay.com/services/marketplacecatalog/ProductService/v1

Product Metadata Service Production Endpoint:

https://svcs.ebay.com/services/marketplacecatalog/ProductMetadataService/v1

Product Service Sandbox Endpoint:

https://svcs.sandbox.ebay.com/services/marketplacecatalog/ProductService/v1

Product Metadata Service Sandbox Endpoint:

https://svcs.sandbox.ebay.com/services/marketplacecatalog/ProductMetadataService/v1

Note: The service endpoint contains the major version for the service (e.g., v1). When updating to subsequent major releases, you must update the version in the service endpoint, as well.

Standard URL Parameter or HTTP Header Values

When you make a Product and Product Metadata 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. 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 Product and Product Metadata API, no URL parameters or HTTP headers, including X-EBAY-SOA-SECURITY-APPNAME can be specified in the SOAP header.

The following table contains descriptions of the standard Product and Product Metadata 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:
XML text/xml
SOAP12 application/soap+xml
SOAP11 text/xml (together with SOAPAction header being sent - value can be anything)
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.
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.
REQUEST-DATA-FORMAT X-EBAY-SOA-REQUEST-DATA-FORMAT No The Product and Product Metadata 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).
OPERATION-NAME X-EBAY-SOA-OPERATION-NAME Yes The name of the call you are using (for example, findItemsAdvanced or getHistograms).
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 JSON, XML, or NV (Name-Value Pair). 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-APPNAME X-EBAY-SOA-SECURITY-APPNAME Yes This is the application ID (AppID) for the service consumer. You obtain an AppID by joining the eBay Developers Program.
SERVICE-VERSION X-EBAY-SOA-SERVICE-VERSION No The API version your application supports (e.g., 1.0.0).

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

Name-value requests/responses follow 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.

Using Array Syntax

When specifying an array of fields in a name-value request, such as multiple itemFilter entries, you must use parenthetic notation to enumerate the entries in the array. 

...
&itemFilter(0).name=MaxPrice
&itemFilter(0).value=25
&itemFilter(0).paramName=Currency
&itemFilter(0).paramValue=USD
&itemFilter(1).name=FreeShippingOnly
&itemFilter(1).value=true
&itemFilter(2).name=ListingType
&itemFilter(2).value(0)=AuctionWithBIN
&itemFilter(2).value(1)=FixedPrice
&itemFilter(2).value(2)=StoreInventory
...

Specifying Attributes

Attributes require a special syntax when used in name-value requests. The findItemsByProduct call requires the use of an attribute to specify the Product and Product Metadata ID (e.g., <productId type=ISBN>1234567890</productId>). In URL/NV requests (and responses) are attributes preceded by an at sign ("@"). For example, the Product and Product Metadata ID would be specified as in the following example: 

...&productId.@type=ISBN&productId=1234567890...

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 ampersands ("&"), must be encoded in URL requests when used in string values for fields like keywords or aspectValueName.

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 ("%"), for that matter.

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 following sample shows a URL-encoded keywords value that you could use to search for items matching "Bang & Olufsen" on eBay:

...&keywords=Bang%20%26%20Olufsen...

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.

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 a field has both an attribute and a value, the value requires a special representation. For example, the findItemsByProduct call requires the use of an attribute to specify the Product and Product Metadata ID (e.g., <productId type=ISBN>1234567890</productId>). In JSON requests (and responses) attributes are preceded by an at sign ("@") and the Product and Product Metadata ID value is represented with a "__value__" name.

Here's an example of how to specify the Product and Product Metadata ID: 

..."productId":{"@type":"ISBN","__value__":"1234567890"}...

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

The eBay Product and Product Metadata APIs can be tested in either the Production or Sandbox environments. These APIs do not change data on the site, they retrieve product data only. The product data is not available in all categories. You must use GetCategoryFeatures in the Trading API to determine which categories are enabled for product data.

Schema Location

You can download the latest version of the WSDL for the Product and Product Metadata API with the following links:

    https://developer.ebay.com/webservices/product/latest/ProductService.wsdl

    https://developer.ebay.com/webservices/product-metadata/latest/ProductMetadataService.wsdl

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

   https://developer.ebay.com/webservices/product/VERSION/ProductService.wsdl

   https://developer.ebay.com/webservices/product-metadata/VERSION/ProductMetadataService.wsdl

The version identifier is the version number of a particular schema (a release number).

For example, you can access version 1.3.0 of the Product WSDL version of the schema at the following URL:

    https://developer.ebay.com/webservices/product/1.3.0/ProductService.wsdl