Shopping API

Making an API Call

This document is an overview of the formats and parameters you can use with the Shopping API. You can obtain data in the JSON, XML, NV (Name-Value Pair), and SOAP formats using the Shopping API. The HTTP GET and HTTP POST methods are supported; see the Tutorials.

The Gateway URL (endpoint) for the Shopping API is http://open.api.ebay.com/shopping?, in all-lowercase letters. Some Shopping API input values are standard and others are call-specific, as in the following example, which uses a URL:

Standard URL Parameters and HTTP Header Values

When you make a Shopping 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 FindPopularItems call to search for items with the word "dog":
http://open.api.ebay.com/shopping?callname=FindPopularItems&responseencoding=XML&appid=YourAppId&siteid=0&QueryKeywords=dog&version=713

In addition to this section, please see Affiliate URL Parameters and HTTP Header Values.

Notes: 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 Shopping API parameters and the corresponding headers:

URL Parameter Header Value Required? Description
appid X-EBAY-API-APP-ID Y This is the application ID (AppID) you obtain by joining the eBay Developers Program. Note: This value and other standard values cannot be specified in a SOAP header.
callback X-EBAY-API-CALLBACK N Applies only in cases where the response data is in JSON format. If this value is true, the response data is wrapped in a call to a _cb_[call name] function, to make the response data easier to use. For example, if you use the FindPopularItems call and you specify callback=true, then the FindPopularItems response data will be wrapped in a call to a _cb_FindPopularItems function. If you prefer, use the callbackname parameter instead. The callbackname parameter enables you to specify the name of the function that is returned. If you use both the callback parameter and the callbackname parameter, the callback parameter is ignored.
callbackname X-EBAY-API-CALLBACK-NAME N Applies only in cases where the response data is in JSON format. If you use this value, the response data is wrapped in a call to a function, to make the response data easier to use. The value you specify for this parameter is used as the name of the function that is returned. For example, if you use the FindPopularItems call and you specify callbackname=myfunction, then the FindPopularItems response data will be wrapped in a call to a myfunction function. The value you specify for this parameter can contain only alphanumeric characters (and the "_" and "." characters). If you use this parameter with the callback parameter, the callback parameter is ignored.
callname X-EBAY-API-CALL-NAME Y The name of the call you are using, e.g. FindPopularItems.
requestencoding X-EBAY-API-REQUEST-ENCODING Y/N If you use a URL for an HTTP GET request, requestencoding is unnecessary: the only valid value is NV (Name-Value Pair).

If you use HTTP POST, this is a required header. Valid options: JSON, XML, NV, or SOAP (all caps).

For request formats JSON and NV, you must append a "Value" field to represent instances of an extension of a simple type or instances of a restriction on a simple type (see responseencoding, below).
responseencoding X-EBAY-API-RESPONSE-ENCODING N The default responseencoding for a URL request is XML. Set responseencoding in the URL to JSON, SOAP or NV (Name-Value pair) to override this default. You must use all caps.

The default responseencoding for an HTTP POST is the same as the requestencoding.

If you specify an output format of JSON or NV, a Value field is introduced for instances of an extension of a simple type or for instances of a restriction on a simple type (see uses of AmountType and DistanceType, for example, extensions of double). An example from GetSingleItem, NV response format, is ShippingServiceCost (AmountType):
Item.ShippingCostSummary.ShippingServiceCost.Value=3.5
siteid X-EBAY-API-SITE-ID N The numeric value for the eBay site with the items you want information about, e.g. the siteid of the US site is 0.
version X-EBAY-API-VERSION Y The API version that your application supports.
versionhandling X-EBAY-API-VERSIONHANDLING N The versionhandling option allows you to receive the enum values from the latest Shopping API schema, regardless of the schema version you specified in version (or in X-EBAY-API-VERSION) parameter. To utilize this option, set versionhandling=LatestEnumValues.
If you set versionhandling=eBayStandard, you will receive the value 'CustomCode' if we have added an enum value that is not defined in the schema version you specified in version (or in X-EBAY-API-VERSION).
If you don't specify a versionhandling value, the default behavior is the same as the versionhandling=eBayStandard setting.

Affiliate URL Parameters and HTTP Header Values

If you use affiliate parameters, you can get commissions (see eBay Partner Network). Affiliate parameters enable the tracking of user activity and can be used with the following calls:

When you use affiliate parameters with an applicable call, a URL is returned (e.g. in the ViewItemURLForNaturalSearch field of the FindPopularItems response) that includes information for tracking user activity.

If you specify affiliate parameters in a call request (see input parameters below), the tracking URL returned in a call response will be similar to the following:
http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=1234567890&customid=custominformation&toolid=10013&mpre=http://www.ebay.com

The following table contains the input URL parameters and corresponding HTTP header values for affiliate tracking. In most cases, URL parameters are easier to use than HTTP header values:

URL Parameter Header Value Description
trackingid X-EBAY-API-TRACKING-ID Specifies an ID to identify you to your tracking partner. The value you specify is obtained from your tracking partner. For eBay Partner Network, the trackingid is the Campaign ID ("campid") provided by eBay Partner Network. A Campaign ID is a 10-digit, unique number to be used for associating traffic. A Campaign ID is valid across all programs to which you have been accepted.
trackingpartnercode X-EBAY-API-TRACKING-PARTNER-CODE Specifies the third party who is your tracking partner. Required if you specify a trackingid. Depending on who your tracking partner is, specify one of the following values. Not all partners are valid for all sites.
2 = Be Free
3 = Affilinet
4 = TradeDoubler
5 = Mediaplex
6 = DoubleClick
7 = Allyes
8 = BJMT
9 = eBay Partner Network
affiliateuserid X-EBAY-API-AFFILIATE-USER-ID Need not be specified. You can define an affiliateuserid (up to 256 characters) if you want to leverage it to better monitor your marketing efforts. If you are using the eBay Partner Network, and you provide an affiliateuserid, the tracking URL returned by eBay Partner Network will contain the affiliateuserid, but it will be referred to as a "customid".

Call-Specific Values

In addition to standard and affiliate-related values, call-specific values must be specified. For example, in the FindPopularItems call, the QueryKeywords value is used.

If you are using the HTTP GET method, you always are specifying standard and call-specific values in a URL. If you are using the HTTP POST method, you choose whether to specify a standard input value in the URL or in the HTTP header. If you are using the HTTP POST method, call-specific values are specified in your HTTP message.

Specifying Arrays in Requests

When you use the URL (or Name-Value Pair) input format, and you specify multiple values for a repeatable field, you can generally use commas to separate the values.

However, in some cases, a comma can be embedded in a string. In such cases, you must use an array index to prevent the comma from acting as a delimiter. This applies in the case of string types. For example, for DomainName in a FindProducts request, use an index value (not a comma). To specify a DomainName of Textbooks, Education in a URL (or Name-Value Pair) input format, you must specify DomainName(0)=Textbooks,%20Education.

If a string type is an ID, e.g. SellerID in a FindHalfProducts request, it will not have an embedded comma. Therefore, a comma can be used to separate the seller ID values you specify. For an example of using a comma to separate IDs that are strings, see GetItemStatus Sample: Basic Call. The GetItemStatus Sample: Basic Call topic also includes an example of XML input.

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 responseencoding parameter to specify that data is returned in one of the following formats: NV, JSON, XML, or SOAP.

This example shows standard Shopping API parameters.
The responseencoding parameter specifies NV for Name-Value Pair output, and can be changed as follows: XML for XML output, SOAP for SOAP output, and JSON for JSON output.
http://open.api.ebay.com/shopping?
   callname=FindPopularItems
   &appid=YourAppIDHere
   &version=517
   &siteid=0
   &responseencoding=NV
This example shows standard Shopping API parameters.
The responseencoding parameter specifies JSON for JSON output, and the example includes callbackname=myfunction.
If you use callbackname=myfunction, the response will be wrapped in a call to a myfunction function.
http://open.api.ebay.com/shopping?
   callname=FindPopularItems
   &appid=YourAppIDHere
   &version=517
   &siteid=0
   &responseencoding=JSON
   &callbackname=myfunction

HTTP Header Examples

If you are using the HTTP POST method, use the X-EBAY-API-REQUEST-ENCODING value (or a requestencoding URL parameter) to specify that your input is in one of the following formats: NV (Name-Value Pair), JSON, XML, or SOAP.

The output (response data) will be in the same format as the input, so there is no need to specify a X-EBAY-API-RESPONSE-ENCODING value. However, you can specify an output format that is different from your input format by using a X-EBAY-API-RESPONSE-ENCODING value.

This example shows standard Shopping API headers for an HTTP POST call
(which uses the same http://open.api.ebay.com/shopping? endpoint as a GET call).
The X-EBAY-API-REQUEST-ENCODING header specifies NV for Name-Value Pair input, and can be changed as follows:: XML for XML input, SOAP for SOAP input, and JSON for JSON input.

   X-EBAY-API-CALL-NAME: FindPopularItems
   X-EBAY-API-APP-ID: YourAppIDHere
   X-EBAY-API-VERSION: 517
   X-EBAY-API-SITE-ID: 0
   X-EBAY-API-REQUEST-ENCODING: NV
This example shows standard Shopping API headers for an HTTP POST call
(which uses the same http://open.api.ebay.com/shopping? endpoint as a GET call).
The X-EBAY-API-REQUEST-ENCODING header specifies JSON for JSON input, and the example includes X-EBAY-API-CALLBACK-NAME: myfunction.
If you use X-EBAY-API-CALLBACK-NAME: myfunction, the response will be wrapped in a call to a myfunction function.

   X-EBAY-API-CALL-NAME: FindPopularItems
   X-EBAY-API-APP-ID: YourAppIDHere
   X-EBAY-API-VERSION: 517
   X-EBAY-API-SITE-ID: 0
   X-EBAY-API-REQUEST-ENCODING: JSON
   X-EBAY-API-CALLBACK-NAME: myfunction

Testing Overview

You can test calls using the Production environment (that is, using the http://open.api.ebay.com/shopping? endpoint).

You also can test calls using the Sandbox environment (that is, using the http://open.api.sandbox.ebay.com/shopping? 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 example, in the Sandbox environment, the data returned by FindReviewsAndGuides in BuyingGuideDetails.BuyingGuide.URL will not correspond to an actual page on the eBay Sandbox site.

For the Shopping API, the Production environment usually is preferable for testing because the Production environment has live data. However, if an application uses both the Shopping API and the Trading API together, the Sandbox environment must be used for testing.

Schema Location

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

For ShoppingService.xsd:
http://developer.ebay.com/webservices/VERSION/ShoppingService.xsd

For ShoppingService.wsdl:
http://developer.ebay.com/webservices/VERSION/ShoppingService.wsdl

The version identifier can be one of the following:

For example, you can access version 521 of the WSDL version of the schema at http://developer.ebay.com/webservices/521/ShoppingService.wsdl

If 523 were the latest version of ShoppingService.wsdl, it would be available at http://developer.ebay.com/webservices/latest/ShoppingService.wsdl

All releases have odd-numbered versions. Each time we release a new version of the eBay schema, we add a new directory with a new version number, and point the "latest" URL to the new version. That is, the schema file in the "latest" directory changes for every release.

User-Contributed Notes

 

Copyright © 2007–2014 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.