Making a Call | eBay Developers Program

This topic 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.

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

Standard URL Parameters and HTTP Header Values

When you make a Shopping API call, you choose whether to specify a standard value though a URL parameter or in an equivalent HTTP header.

For example, you could specify the following FindProducts call to search for products with the word "dog": https://open.api.ebay.com/shopping?callname=FindProducts&responseencoding=XML&siteid=0&QueryKeywords=dog&version=1293

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

Note: If you specify an equivalent URL parameter and an HTTP header in the same call, the URL parameter takes precedence. There is no set order which needs to be followed when specifying URL parameters.

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

HTTP Header	URL Parameter	Required?	Description
X-EBAY-API-IAF-TOKEN	No URL equivalent	Yes	This is the generated OAuth application access token, and this token must be passed through the HTTP header. An OAuth application access token with https://api.ebay.com/oauth/api_scopescope is necessary to make a Shopping API call. See the client credentials grant flow topic for more information on generating and managing OAuth application access tokens, and see the Specifying OAuth scopes topic for more information on OAuth scopes.
X-EBAY-API-CALL-NAME	callname	Yes	The name of the Shopping call that you are using, such as GetMultipleItems.
X-EBAY-API-VERSION	version	Yes	This sets the schema version of the Shopping API to use, and is required.
X-EBAY-API-REQUEST-ENCODING	requestencoding	Conditionally	If you use a URL for an HTTP GET request, the requestencoding parameter is unnecessary, since it will default to the only valid value, which is NV (Name-Value Pair). If you do use the requestencoding parameter, it should be set to `NV` If you use HTTP POST, this is a required header. Valid options: JSON, XML, NV, or SOAP (use 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).
X-EBAY-API-RESPONSE-ENCODING	responseencoding	Conditionally	The default response encoding for a URL request is XML, so the response will be XML if this header/parameter is not included. To change the format of the response to JSON, SOAP or NV (Name-Value pair), include the `responseencoding` URL parameter and set its value to `JSON`, `SOAP`, or `NV` (use all CAPS) The default response encoding for an HTTP POST call will default to whatever the request encoding is set to. 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, for example, extensions of `double`). An example from GetSingleItem, NV response format, is ShippingServiceCost (AmountType): `Item.ShippingCostSummary.ShippingServiceCost.Value=3.5`
X-EBAY-API-SITE-ID	siteid	No	This is the numeric identifier of an eBay marketplace. Site ID values for all marketplaces can be found here.
X-EBAY-API-VERSIONHANDLING	versionhandling	No	The option allows you to receive the enum values from the latest Shopping API schema, regardless of the schema version you specified in the version or in the X-EBAY-API-VERSION header. To utilize this option, include and set the versionhandling parameter or the X-EBAY-API-VERSIONHANDLING header value to `LatestEnumValues`. Version handling defaults to a value of `eBayStandard` if not included/set, and this means that any and all enum values that are returned in responses will be the enum values defined in the Shopping API schema specified in the version parameter or the X-EBAY-API-VERSION header. If you are working with an older Shopping API schema, and new enum values have been added in latest versions of the schema, you will receive a value of `CustomCode` for any enum value that is not defined in the schema version that you are using.

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:

https://partnernetwork.ebay.com/

FindProducts
GetSingleItem
GetMultipleItems
GetUserProfile

When you use affiliate parameters with an applicable call, a URL is returned (e.g. in the ViewItemURLForNaturalSearch field of the FindProducts 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: https://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=1234567890&customid=custominformation&toolid=10013&mpre=https://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:

HTTP Header	URL Parameter	Description
X-EBAY-API-TRACKING-ID	trackingid	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.
X-EBAY-API-TRACKING-PARTNER-CODE	trackingpartnercode	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
X-EBAY-API-AFFILIATE-USER-ID	affiliateuserid	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 HTTP headers and/or URL parameters, call-specific, request payload fields must also be specified. Each Call Reference page has an Input section that highlights these request payload field. For an example of this, see the GetMultipleItems Input section.

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.

URL Example

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.

https://open.api.ebay.com/shopping?
   callname=FindProducts
   &version=1119
   &siteid=0
   &responseencoding=NV

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 https://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: FindProducts

X-EBAY-API-IAF-TOKEN: YourOAuthTokenHere

X-EBAY-API-VERSION: 1293

X-EBAY-API-SITE-ID: 0

X-EBAY-API-REQUEST-ENCODING: NV

Testing Overview

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

You also can test calls using the Sandbox environment (that is, using the https://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.

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:
https://developer.ebay.com/webservices/VERSION/ShoppingService.xsd

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

The version identifier can be one of the following:

A number (for example, 1293) -- This is the version number of a particular schema file (a release number)
latest -- This always points to the schema with the highest version number

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

If 1293 were the latest version of ShoppingService.wsdl, it would be available at https://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.