Introduction
Standard URL Parameters and HTTP Header Values
Affiliate URL Parameters and HTTP Header Values
Call-Specific Values
Specifying Arrays in Requests
URL Examples
HTTP Header Examples
Testing Overview
Schema Location
User-Contributed Notes
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:
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 FindItems call to search for items with the word "dog" and
sort them based on Best Match:
http://open.api.ebay.com/shopping?version=517&appid=YourAppIDHere&callname=FindItems&QueryKeywords=dog&ItemSort=BestMatch
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 FindItems call and you specify callback=true, then the FindItems response data will be wrapped in a call to a _cb_FindItems 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 FindItems call and you specify callbackname=myfunction, then the FindItems 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. FindItems. |
| requestencoding | X-EBAY-API-REQUEST-ENCODING | N | If you use a URL for an HTTP GET request, requestencoding 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: JSON, XML, NV, or SOAP. When you specify JSON, XML, NV, or SOAP, you must use all caps. If you specify an input format of JSON or NV, then for instances of an extension of a simple type and for instances of a restriction on a simple type, you must use a Value field. For more information, see responseencoding, below. |
| responseencoding | X-EBAY-API-RESPONSE-ENCODING | N | If you use a URL, use this parameter to specify the output format
as JSON, XML, NV (Name-Value Pair), or SOAP.
When you specify JSON, XML, NV, or SOAP, you must use all caps.
If you specify an output format of JSON or NV, then for instances of
an extension of a simple type and for instances of a restriction on a simple type,
a Value field is used.
Examples are instances of AmountType and DistanceType,
because each of these is an extension of double.
In the FindItemsAdvanced NV response,
here is an example of a possible instance of ShippingServiceCost (which is of type AmountType):
Item(1).ShippingCostSummary.ShippingServiceCost.Value=3.5 If you use a URL, and you do not specify responseencoding, 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 unless you use responseencoding or X-EBAY-API-RESPONSE-ENCODING value to specify a different response encoding. |
| 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. |
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 FindItems response) that includes information for tracking user activity. For an example, see Basic Call with Affiliate Tracking.
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". |
In addition to standard and affiliate-related values, call-specific values must be specified. For example, in the FindItems 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.
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 FindItemsAdvanced 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.
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=FindItems
&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=FindItems
&appid=YourAppIDHere
&version=517
&siteid=0
&responseencoding=JSON
&callbackname=myfunction
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 samehttp://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: FindItems
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 samehttp://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: FindItems
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
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 FindItemsAdvanced in
SearchResult.ItemArray.Item.ViewItemURLForNaturalSearch is
a standard ViewItem URL, rather than the ViewItem URL for natural search that is returned
in the Production environment.
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.
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.
