getSimilarItems: eBay Marketing API | eBay Developers Program

GET/similar_items

This method retrieves items that are similar to the specified item.

Items are considered similar if they can serve as a replacement or alternative for the specified item. Similar items from a catalog are associated with the same product. For items not associated with a product, similarity is determined by keywords in the title and attribute value matches.

The item for which to retrieve similar items is specified by its item_id value, input as a required query parameter. A successful call returns a list of items similar to the specified item, as well as details about each item. This includes the current price and shipping costs are returned for each item, as well as basic information about the listing, such as its item ID, price, shipping cost, and time left on the listing.

Input

Resource URI

GET https://api.ebay.com/buy/marketing/v1/similar_items?

excluded_category_ids=string&

buying_option=string&

filter=FilterField&

max_results=integer&

item_id=string

This method is not supported in Sandbox environment.

URI parameters

Parameter	Type	Description
excluded_category_ids	array of string	This query parameter can be used to specify categories to exclude from the result set. Because the list of eBay category IDs is not published and category IDs are not the same across all eBay marketplaces, category IDs may be determined by: Visiting the Category Changes page Using the Taxonomy API. Refer to Get Categories for Buy APIs for complete information. Issuing the following call to retrieve the `dominantCategoryId` for an item: /buy/browse/v1/item_summary/search?q= keyword&fieldgroups=ASPECT_REFINEMENTS Up to three categories to be excluded can be specified through this parameter. Occurrence: Optional
buying_option	string	This query parameter can be used to filter the result set based on the item's buying option type. Valid Values: `FIXED_PRICE` `AUCTION` `BEST_OFFER` `CLASSIFIED_AD` Occurrence: Optional
filter	array of FilterField	An array of field filters that can be used to limit/customize the result set. Currently, only `itemEndDate` is supported. This filter limits the result set to include only items scheduled to end before the specified date and time. For example, filter=itemEndDate:[..2025-12-14T07:47:48Z] Occurrence: Optional
max_results	integer	This query parameter can be used to specify the max number of items to display from the result set. Default: 20 Max value: 50 Occurrence: Optional
item_id	string	This query parameter specifies the unique RESTful identifier of the item for which to retrieve similar items. RESTful Item ID Format: `v1`\|`#`\|`#` For a single SKU listing, pass in the item ID: v1\|2********2\|0 For a multi-SKU listing, pass in the identifier of the variation: v1\|1******2\|4********2 For more information about item IDs for RESTful APIs, refer to Item ID legacy API compatibility overview in the Buying Integration Guide. Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header Type Description

Header	Type	Description
X-EBAY-C-MARKETPLACE-ID	string	This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. Note: If the marketplace ID value is invalid or missing, the default value of `EBAY_US` is used. See MarketplaceIdEnum for a list of supported marketplaces. Default: `EBAY_US` Occurrence: Strongly Recommended
X-EBAY-C-ENDUSERCTX	string	This header can be used to pass in affiliate credentials to return item affiliate information. For more information, see Header for affiliate information. Occurrence: Optional
Accept-Language	string	This header is used to indicate the natural language and locale preferred by the user for the response. This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example: When targeting the French locale of the Belgium marketplace, it is required to pass in `fr-BE` to specify this. If this locale is not specified, the language will default to Dutch. When targeting the French locale of the Canadian marketplace, it is required to pass in `fr-CA` to specify this. If this locale is not specified, the language will default to English. Occurrence: Conditional

X-EBAY-C-MARKETPLACE-ID

string

This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US.

Note: If the marketplace ID value is invalid or missing, the default value of EBAY_US is used.
See MarketplaceIdEnum for a list of supported marketplaces.

Default: EBAY_US

Occurrence: Strongly Recommended

X-EBAY-C-ENDUSERCTX

string

This header can be used to pass in affiliate credentials to return item affiliate information. For more information, see Header for affiliate information.

Occurrence: Optional

Accept-Language

string

This header is used to indicate the natural language and locale preferred by the user for the response.

This header is required when targeting a specific locale of a marketplace that supports multiple locales. For example:

When targeting the French locale of the Belgium marketplace, it is required to pass in fr-BE to specify this. If this locale is not specified, the language will default to Dutch.
When targeting the French locale of the Canadian marketplace, it is required to pass in fr-CA to specify this. If this locale is not specified, the language will default to English.

Occurrence: Conditional

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/buy.marketing.similaritems

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* SimilarItemsResponse */

"similarItems" : [

{ /* SimilarItem */

"bidCount" : "integer",

"currentBidPrice" :

{ /* Amount */

"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",

"value" : "string"

"galleryImageUrl" : "string",

"itemEndDate" : "string",

"itemId" : "string",

"itemLocation" :

{ /* ItemLocation */

"country" : "CountryCodeEnum : [AD,AE,AF...]"

"itemWebUrl" : "string",

"listingMarketplaceId" : "MarketplaceIdEnum",

"price" :

{ /* Amount */

"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",

"value" : "string"

"primaryCategory" :

{ /* Category */

"categoryId" : "string",

"categoryName" : "string"

"shippingCost" :

{ /* Amount */

"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",

"value" : "string"

"shippingCostType" : "string",

"subtitle" : "string",

"title" : "string"

}

]

}

Response fields

Output container/field	Type	Description
similarItems	array of SimilarItem	This array returns a list of similar items matching the input criteria. Occurrence: Always
similarItems.bidCount	integer	undefined Occurrence: Conditional
similarItems.currentBidPrice	Amount	This integer value indicates the total number of bids that have been placed for an auction item. This field is only returned for auction items. Occurrence: Conditional
similarItems.currentBidPrice.currency	CurrencyCodeEnum	The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional
similarItems.currentBidPrice.value	string	The monetary amount, in the currency specified by the currency field. Occurrence: Conditional
similarItems.galleryImageUrl	string	The container that returns the current highest bid for an auction item. The value field shows the dollar value of the current highest bid, and the currency (3-digit ISO code) field denotes the currency associated with that bid value. This container will only be returned for auction items. Occurrence: Always
similarItems.itemEndDate	string	A timestamp that indicates the date and time a listing is scheduled to end. This value is returned in UTC format (`yyyy-MM-ddThh:mm:ss.sssZ`), which can be converted into the local time of the buyer. Occurrence: Conditional
similarItems.itemId	string	The unique RESTful identifier of the item. Occurrence: Always
similarItems.itemLocation	ItemLocation	This container returns the 2-digit ISO code of the country in which the item is location. Occurrence: Conditional
similarItems.itemLocation.country	CountryCodeEnum	The two-letter ISO 3166 standard code that indicates the country in which the item is located. Occurrence: Conditional
similarItems.itemWebUrl	string	The URL to the View Item page of the listing. Occurrence: Conditional
similarItems.listingMarketplaceId	MarketplaceIdEnum	The unique identifier of the eBay marketplace of the listing. Occurrence: Conditional
similarItems.price	Amount	The price of the item. This field will only be returned for fixed-price listings and auction listings that are enabled with the Buy it Now feature. Occurrence: Conditional
similarItems.price.currency	CurrencyCodeEnum	The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional
similarItems.price.value	string	The monetary amount, in the currency specified by the currency field. Occurrence: Conditional
similarItems.primaryCategory	Category	This container returns the category name and ID of the primary listing category. Occurrence: Always
similarItems.primaryCategory.categoryId	string	The unique identifier of the leaf category for this item. A leaf category is the lowest level in that category and has no children. Occurrence: Conditional
similarItems.primaryCategory.categoryName	string	The name of the category the item is listed in. Occurrence: Conditional
similarItems.shippingCost	Amount	The final shipping cost for all the item. Occurrence: Always
similarItems.shippingCost.currency	CurrencyCodeEnum	The three-letter ISO 4217 code representing the currency of the amount in the value field. Occurrence: Conditional
similarItems.shippingCost.value	string	The monetary amount, in the currency specified by the currency field. Occurrence: Conditional
similarItems.shippingCostType	string	Indicates the type of shipping used to ship the item. Possible values are `FIXED` (flat-rate shipping) and `CALCULATED` (shipping cost calculated based on item and buyer location). Occurrence: Always
similarItems.subtitle	string	A subtitle is optional and allows the seller to provide more information about the item, possibly including keywords that may assist with search results. Occurrence: Conditional
similarItems.title	string	The title of the item as its appears on the listing. Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	OK
400	Bad Request
500	Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
12000	API_MARKETING	APPLICATION	There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
12600	API_MARKETING	REQUEST	There is one or more issues with the 'excluded_category_ids' filter. Please see documentation for correct syntax and make sure you are using a valid category ID for the marketplace.
12601	API_MARKETING	REQUEST	The 'excluded_category_ids' field has exceeded the maximum limit of 3 category IDs.
12602	API_MARKETING	REQUEST	The specified buying option is invalid. Please see documentation for supported values.
12603	API_MARKETING	REQUEST	There is an issue with the 'itemEndDate' filter. Please see documentation for details on proper syntax of this filter and the date range constraints.
12604	API_MARKETING	REQUEST	The 'max_results' value must be a positive integer from 1 up to 50.
12605	API_MARKETING	REQUEST	The required 'item_id' parameter is either missing or has an invalid value. Please include this parameter and use a supported value.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Retrieve similar items

This method can be used to retrieve items, and information about each item, that are similar to the specified item.

Input

The item_id URI parameter, which specifies the item for which to find similar items, is required. There is no additional payload required for this request.

GEThttps://api.ebay.com/buy/marketing/v1/similar_items?item_id=1********2

Output

If the call is successful, a list of items similar to the specified item is returned. This includes information such as each item's ID, category information, marketplace, shipping cost, and price.

{
    "getSimilarItemsResponse": {
        "similarItems": [
            {
                "itemId": "v1|3********5|0",
                "title": "10 oz Scottsdale STACKER® Silver Bar .999 Silver #A182",
                "itemWebUrl": "https://www.latest.ebay.com/itm/3********5?_trkparms=amclksrc%3DITM%26mehot%3Dpp%26itm%3D361258016175%26pmt%3D0%26noa%3D1%26brand%3DScottsdale%2BMint&_trksid=p0&src=urllib",
                "listingMarketplaceId": "EBAY_US",
                "itemEndDate": "2025-10-31T23:39:37.000Z",
                "primaryCategory": {
                    "categoryId": "11116",
                    "categoryName": "Coins & Paper Money"
                },
                "itemLocation": {
                    "country": "US"
                },
                "galleryImageUrl": "https://i.ebayimg.com/thumbs/images/g/HFgAAOSwpDdVGzAz/s-l140.jpg",
                "shippingCostType": "FIXED",
                "price": {
                    "value": "568.27",
                    "currency": "USD"
                },
                "shippingCost": {
                    "value": "0.0",
                    "currency": "USD"
                }
            },
            {
                "itemId": "v1|1********2|0",
                "title": "10 oz Scottsdale STACKER® Silver Bar .999 Silver",
                "itemWebUrl": "https://www.latest.ebay.com/itm/1********2?_trkparms=amclksrc%3DITM%26mehot%3Dlo%26itm%3D157392211102%26pmt%3D0%26noa%3D1%26brand%3DScottsdale%2BMint&_trksid=p0&src=urllib",
                "listingMarketplaceId": "EBAY_US",
                "itemEndDate": "2025-11-15T03:18:16.000Z",
                "primaryCategory": {
                    "categoryId": "11116",
                    "categoryName": "Coins & Paper Money"
                },
                "itemLocation": {
                    "country": "US"
                },
                "galleryImageUrl": "https://i.ebayimg.com/thumbs/images/g/ErcAAeSwyTZo7wQ5/s-l140.jpg",
                "shippingCostType": "CALCULATED",
                "price": {
                    "value": "598.0",
                    "currency": "USD"
                },
                "shippingCost": {
                    "value": "9.75",
                    "currency": "USD"
                }
            },
            {
                "itemId": "v1|1********1|0",
                "title": "10 oz Scottsdale Silver Stacker Bar 14036467",
                "itemWebUrl": "https://www.latest.ebay.com/itm/1********1?_trkparms=amclksrc%3DITM%26mehot%3Dnone%26itm%3D177488665741%26pmt%3D0%26noa%3D1%26brand%3DScottsdale%2BMint&_trksid=p0&src=urllib",
                "listingMarketplaceId": "EBAY_US",
                "itemEndDate": "2025-10-21T00:00:01.000Z",
                "primaryCategory": {
                    "categoryId": "11116",
                    "categoryName": "Coins & Paper Money"
                },
                "itemLocation": {
                    "country": "US"
                },
                "galleryImageUrl": "https://i.ebayimg.com/thumbs/images/g/2zUAAeSwDBFo7XI2/s-l140.jpg",
                "shippingCostType": "FIXED",
                "price": {
                    "value": "0.0",
                    "currency": "USD"
                },
                "shippingCost": {
                    "value": "0.0",
                    "currency": "USD"
                },
                "currentBidPrice": {
                    "value": "500.0",
                    "currency": "USD"
                },
                "bidCount": 7
            },
            {
                "itemId": "v1|1********5|0",
                "title": "10 oz Scottsdale Silver Stacker Bar 14036487",
                "itemWebUrl": "https://www.latest.ebay.com/itm/1********5?_trkparms=amclksrc%3DITM%26mehot%3Dnone%26itm%3D177488633415%26pmt%3D0%26noa%3D1%26brand%3DScottsdale%2BMint&_trksid=p0&src=urllib",
                "listingMarketplaceId": "EBAY_US",
                "itemEndDate": "2025-10-20T21:45:01.000Z",
                "primaryCategory": {
                    "categoryId": "11116",
                    "categoryName": "Coins & Paper Money"
                },
                "itemLocation": {
                    "country": "US"
                },
                "galleryImageUrl": "https://i.ebayimg.com/thumbs/images/g/iAgAAeSwdXFo7W8E/s-l140.jpg",
                "shippingCostType": "FIXED",
                "price": {
                    "value": "0.0",
                    "currency": "USD"
                },
                "shippingCost": {
                    "value": "0.0",
                    "currency": "USD"
                },
                "currentBidPrice": {
                    "value": "528.99",
                    "currency": "USD"
                },
                "bidCount": 6
            },
            {
                "itemId": "v1|1********8|0",
                "title": "10 oz Scottsdale Silver Stacker Bar 14038480",
                "itemWebUrl": "https://www.latest.ebay.com/itm/1********8?_trkparms=amclksrc%3DITM%26mehot%3Dnone%26itm%3D177488656958%26pmt%3D0%26noa%3D1%26brand%3DScottsdale%2BMint&_trksid=p0&src=urllib",
                "listingMarketplaceId": "EBAY_US",
                "itemEndDate": "2025-10-20T22:00:01.000Z",
                "primaryCategory": {
                    "categoryId": "11116",
                    "categoryName": "Coins & Paper Money"
                },
                "itemLocation": {
                    "country": "US"
                },
                "galleryImageUrl": "https://i.ebayimg.com/thumbs/images/g/ZPUAAeSwTuBo7XFp/s-l140.jpg",
                "shippingCostType": "FIXED",
                "price": {
                    "value": "0.0",
                    "currency": "USD"
                },
                "shippingCost": {
                    "value": "0.0",
                    "currency": "USD"
                },
                "currentBidPrice": {
                    "value": "499.5",
                    "currency": "USD"
                },
                "bidCount": 8
            },
            {
                "itemId": "v1|1********8|0",
                "title": "10-oz Scottsdale Stacker .999 Fine Silver Bar",
                "itemWebUrl": "https://www.latest.ebay.com/itm/1********8?_trkparms=amclksrc%3DITM%26mehot%3Dnone%26itm%3D145651132148%26pmt%3D0%26noa%3D1%26brand%3DScottsdale%2BMint&_trksid=p0&src=urllib",
                "listingMarketplaceId": "EBAY_US",
                "itemEndDate": "2025-11-06T15:49:56.000Z",
                "primaryCategory": {
                    "categoryId": "11116",
                    "categoryName": "Coins & Paper Money"
                },
                "itemLocation": {
                    "country": "US"
                },
                "galleryImageUrl": "https://i.ebayimg.com/thumbs/images/g/HHoAAeSw9EVo9adI/s-l140.jpg",
                "shippingCostType": "FIXED",
                "price": {
                    "value": "569.01",
                    "currency": "USD"
                },
                "shippingCost": {
                    "value": "0.0",
                    "currency": "USD"
                }
            }
        ]
    }
}