Shopping API

Making an API Call

Note: Developers using Shopping API calls must authenticate with an OAuth application access token in the HTTP header X-EBAY-API-IAF-TOKEN and use OAuth application access tokens with a scope that includes https://api.ebay.com/oauth/api_scope. See the client credentials grant flow topic for more information on generating and managing OAuth application access tokens. See the Specifying OAuth scopes topic for more information on OAuth scopes.

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 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 through 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=1119

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 Conditionally 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_scope scope 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.

Note: Developers using Shopping API calls must authenticate with an OAuth application access token.

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/

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 standard and affiliate-related values, call-specific values must be specified. For example, in the FindProducts 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.
https://open.api.ebay.com/shopping?
   callname=FindProducts
   &version=1119
   &siteid=0
   &responseencoding=NV

Note: Developers using Shopping API calls must authenticate with an OAuth application access token in the HTTP header X-EBAY-API-IAF-TOKEN and use OAuth application access tokens with a scope that includes https://api.ebay.com/oauth/api_scope. See the client credentials grant flow topic for more information on generating and managing OAuth application access tokens. See the Specifying OAuth scopes topic for more information on OAuth scopes.

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: 1063
   X-EBAY-API-SITE-ID: 0
   X-EBAY-API-REQUEST-ENCODING: NV

Note: Developers using Shopping API calls must authenticate with an OAuth application access token in the HTTP header X-EBAY-API-IAF-TOKEN and use OAuth application access tokens with a scope that includes https://api.ebay.com/oauth/api_scope. See the client credentials grant flow topic for more information on generating and managing OAuth application access tokens. See the Specifying OAuth scopes topic for more information on OAuth scopes.

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:

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

If 1063 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.

Copyright © 2007–2021 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.