--- title: Marketing API description: "The Marketing API is part of the eBay Buy APIs. It retrieves eBay products based on a metric, such as Best Selling. This API helps shoppers compare products and motivate them to purchase items. You can use the other [Buy APIs](/api-docs/buy/static/buy-overview.html) to create a buying application that lets users, eBay members or guests, buy from eBay sellers without visiting the eBay site. The Buy APIs provide the opportunity to purchase eBay items in your app or website. This API uses the following resources: * **merchandised\\_product** - retrieves eBay products for a specific metric, such as Best Selling. * **most\\_watched\\_items** - retrieves items with the highest watch counts in a category. * **similar\\_items** - retrieves recommended similar items for a specified item." api_version: 1.1.0 api_name: buy_marketing_api api_type: REST api_group: buy/marketing source_url: html: https://developer.ebay.com/develop/api/buy/marketing md: https://developer.ebay.com/develop/api/buy/marketing.md --- # Marketing API API The Marketing API is part of the eBay Buy APIs. It retrieves eBay products based on a metric, such as Best Selling. This API helps shoppers compare products and motivate them to purchase items. You can use the other [Buy APIs](/api-docs/buy/static/buy-overview.html) to create a buying application that lets users, eBay members or guests, buy from eBay sellers without visiting the eBay site. The Buy APIs provide the opportunity to purchase eBay items in your app or website. This API uses the following resources: * **merchandised\_product** - retrieves eBay products for a specific metric, such as Best Selling. * **most\_watched\_items** - retrieves items with the highest watch counts in a category. * **similar\_items** - retrieves recommended similar items for a specified item. ## API Information **Title:** Buy Marketing API **Version:** 1.1.0 **Description:** The Marketing Beta API is part of the eBay Buy APIs. It retrieves eBay products based on a metric, such as Best Selling. This API helps shoppers compare products and motivate them to purchase items. You can use the other Buy APIs to create a buying application that lets users, eBay members or guests, buy from eBay sellers without visiting the eBay site. The Buy APIs provide the opportunity to purchase eBay items in your app or website. **Base Path:** /buy/marketing/v1 ## API Methods The following API methods are available: ### getMerchandisedProducts #### GET /merchandised_product **Description:** This method returns an array of products based on the category and metric specified. This includes details of the product, such as the eBay product ID (EPID), title, and user reviews and ratings for the product. You can use the `epid` returned by this method in the **Browse API** **search** method to retrieve items for this product. ### **Restrictions** * To test **getMerchandisedProducts** in Sandbox, you must use category ID 9355 and the response will be mock data. * For a list of supported sites and other restrictions, see [Buy API Support by Marketplace](/api-docs/buy/static/ref-marketplace-supported.html). **Parameters:** - **aspect_filter** (string) - This value specifies the aspect name/value pairs used to further refine product results. For example: /buy/marketing/v1\_beta/merchandised\_product?category\_id=31388&metric\_name=BEST\_SELLING&aspect\_filter=Brand:Canon You can use the Browse API **search** method with the `fieldgroups=ASPECT_REFINEMENTS` field to return the aspects of a product. - **category_id** (string) *required* - This query parameter limits the products returned to a specific eBay category. The list of eBay category IDs is not published and category IDs are not all the same across all the eBay marketplace. You can use the following techniques to find a category by site: * Use the [Category Changes page](https://pages.ebay.com/sellerinformation/news/categorychanges.html). * Use the **Taxonomy API**. For details see [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html). * Use the **Browse API** and submit the following method to get the **dominantCategoryId** for an item. /buy/browse/v1/item\_summary/search?q=_keyword_&fieldgroups=ASPECT\_REFINEMENTS **Maximum:** 1 **Required:** 1 - **limit** (string) - This value specifies the maximum number of products to return in a result set. **Note:** Maximum value means the method will return up _to_ that many products per set, but it can be less than this value. If the number of products found is less than this value, the method will return all of the products matching the criteria. **Default:** 8 **Maximum:** 100 - **metric_name** (string) *required* - This value filters the result set by the specified metric. Only products in this metric are returned. **Note:** Currently, the only metric supported is `BEST_SELLING`. **Default:** `BEST_SELLING` **Maximum:** 1 **Required:** 1 **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): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/buy.marketing` ### getMostWatchedItems #### GET /most_watched_items **Description:** This method retrieves items with the highest watch counts in a specific category. The leaf category for which to retrieve items with the highest watch counts is specified by its **category\_id** value. Up to 50 items can be returned for a specific category using this method. The number of items to return using this method can be specified through the **max\_result** query parameter. If this parameter is not used, the top 20 most watched items will be returned for the specified category. A successful call returns details about the most watched items in a specific category, such as the watch count, current price, shipping cost, and basic information about the listing. Returned items are ranked in descending order with the highest watch count appearing first. **Parameters:** - **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. - **category_id** (string) *required* - This query parameter can be used to specify the leaf category from which to retrieve most watched items. The list of eBay category IDs is not published and category IDs are not all the same across all the eBay marketplaces. You can use the following techniques to find a category by site: * Use the [Category Changes](https://pages.ebay.com/sellerinformation/news/categorychanges.html) page. * Use the **Taxonomy API**. For details on using this API, see [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html). * Use the following **Browse API** method to get the **dominantCategoryId** for an item: /buy/browse/v1/item\_summary/search?q= _keyword_&fieldgroups=ASPECT\_REFINEMENTS **Note:** If no category ID is input though this parameter, category `9355` will be used by default. **Maximum:** 1 - **max_results** (string) - This query parameter can be used to specify the maximum number of most watched items to return from the specified category. **Default value:** 20 **Min value:** 1 **Max value:** 50 - **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.](/api-docs/buy/static/api-browse.html#affiliate-header) - **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](/develop/api/buy/buy_marketing_api/most_watched_items/getmostwatcheditems#buy-buy_marketing_api-most_watched_items-getmostwatcheditems.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` **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): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/buy.marketing` ### getSimilarItems #### GET /similar_items **Description:** 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. **Parameters:** - **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. - **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` - **excluded_category_ids** (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](https://pages.ebay.com/sellerinformation/news/categorychanges.html ) * Using the **Taxonomy API**. Refer to [Get Categories for Buy APIs](/api-docs/buy/buy-categories.html) 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. - **filter** (string) - 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\] - **item_id** (string) *required* - 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](/api-docs/buy/static/api-browse.html#Legacy) in the [Buying Integration Guide](/api-docs/buy/static/buying-ig-landing.html). - **max_results** (string) - This query parameter can be used to specify the max number of items to display from the result set. **Default:** 20 **Max value:** 50 - **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.](/api-docs/buy/static/api-browse.html#affiliate-header) - **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](/develop/api/buy/buy_marketing_api/similar_items/getsimilaritems#buy-buy_marketing_api-similar_items-getsimilaritems.marketplaceidenum) for a list of supported marketplaces. **Default:** `EBAY_US` **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): **Required Scopes:** **Client Credentials Grant:** - `https://api.ebay.com/oauth/api_scope/buy.marketing.similaritems` ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 70001 - API_MARKETING **Description:** A metric\_name is required to make the API call. #### 70002 - API_MARKETING **Description:** The metric\_name {metric\_name} is invalid. #### 70003 - API_MARKETING **Description:** A categoryId is required to make the API call. #### 70004 - API_MARKETING **Description:** The category id {categoryId} is invalid #### 70005 - API_MARKETING **Description:** The 'limit' value should be between 1 and 100 (inclusive). #### 70006 - API_MARKETING **Description:** The 'limit' value must be an integer value. #### 70007 - API_MARKETING **Description:** The marketplace value {marketplace} is not supported. The supported values are: {marketplaces}. #### 70100 - API_MARKETING **Description:** The 'max\_results' value must be a positive integer from 1 up to 50. #### 12600 - API_MARKETING **Description:** 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 **Description:** The 'excluded\_category\_ids' field has exceeded the maximum limit of 3 category IDs. #### 12602 - API_MARKETING **Description:** The specified buying option is invalid. Please see documentation for supported values. #### 12603 - API_MARKETING **Description:** 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 **Description:** The 'max\_results' value must be a positive integer from 1 up to 50. #### 12605 - API_MARKETING **Description:** The required 'item\_id' parameter is either missing or has an invalid value. Please include this parameter and use a supported value. ### APPLICATION Errors #### 70000 - API_MARKETING **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. #### 12000 - API_MARKETING **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. ## Types ### Amount **Description:** This type defines the monetary value of an amount and the currency used. **Type:** object **Properties:** - **currency** (CurrencyCodeEnum) - The three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code representing the currency of the amount in the **value** field. - **value** (string) - The monetary amount, in the currency specified by the **currency** field. ### BestSellingProductResponse **Description:** This type defines the fields for the best selling product information. **Type:** object **Properties:** - **merchandisedProducts** (array) - An array of containers for the products. - **warnings** (array) - The container with all the warnings for the input request. ### Category **Description:** This type defines information about a category, such as its name and identifier. **Type:** object **Properties:** - **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. - **categoryName** (string) - The name of the category the item is listed in. ### CountryCodeEnum **Description:** This enumerated type defines the two-letter [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard code representing a country. | - **AD**: Indicates the country is Andorra. - **AE**: Indicates the country is United Arab Emirates. - **AF**: Indicates the country is Afghanistan. - **AG**: Indicates the country is Antigua and Barbuda. - **AI**: Indicates the country is Anguilla. - **AL**: Indicates the country is Albania. - **AM**: Indicates the country is Armenia. - **AN**: Indicates the country is Netherlands Antilles. - **AO**: Indicates the country is Angola. - **AQ**: Indicates the country is Antarctica. - **AR**: Indicates the country is Argentina. - **AS**: Indicates the country is American Samoa. - **AT**: Indicates the country is Austria. - **AU**: Indicates the country is Australia. - **AW**: Indicates the country is Aruba. - **AX**: Indicates the country is Aland Islands. - **AZ**: Indicates the country is Azerbaijan. - **BA**: Indicates the country is Bosnia and Herzegovina. - **BB**: Indicates the country is Barbados. - **BD**: Indicates the country is Bangladesh. - **BE**: Indicates the country is Belgium. - **BF**: Indicates the country is Burkina Faso. - **BG**: Indicates the country is Bulgaria. - **BH**: Indicates the country is Bahrain. - **BI**: Indicates the country is Burundi. - **BJ**: Indicates the country is Benin. - **BL**: Indicates the country is Saint Barthelemy. - **BM**: Indicates the country is Bermuda. - **BN**: Indicates the country is Brunei Darussalam. - **BO**: Indicates the country is Bolivia. - **BQ**: Indicates the country is Bonaire, Sint Eustatius, and Saba. - **BR**: Indicates the country is Brazil. - **BS**: Indicates the country is Bahamas. - **BT**: Indicates the country is Bhutan. - **BV**: Indicates the country is Bouvet Island. - **BW**: Indicates the country is Botswana. - **BY**: Indicates the country is Belarus. - **BZ**: Indicates the country is Belize. - **CA**: Indicates the country is Canada. - **CC**: Indicates the country is Cocos (Keeling) Islands. - **CD**: Indicates the country is The Democratic Republic of the Congo. - **CF**: Indicates the country is Central African Republic. - **CG**: Indicates the country is Congo. - **CH**: Indicates the country is Switzerland. - **CI**: Indicates the country is Cote d'Ivoire. - **CK**: Indicates the country is Cook Islands. - **CL**: Indicates the country is Chile. - **CM**: Indicates the country is Cameroon. - **CN**: Indicates the country is China. - **CO**: Indicates the country is Colombia. - **CR**: Indicates the country is Costa Rica. - **CU**: Indicates the country is Cuba. - **CV**: Indicates the country is Cape Verde. - **CW**: Indicates the country is Curacao. - **CX**: Indicates the country is Christmas Island. - **CY**: Indicates the country is Cyprus. - **CZ**: Indicates the country is Czech Republic. - **DE**: Indicates the country is Germany. - **DJ**: Indicates the country is Djibouti. - **DK**: Indicates the country is Denmark. - **DM**: Indicates the country is Dominica. - **DO**: Indicates the country is Dominican Republic. - **DZ**: Indicates the country is Algeria. - **EC**: Indicates the country is Ecuador. - **EE**: Indicates the country is Estonia. - **EG**: Indicates the country is Egypt. - **EH**: Indicates the country is Western Sahara. - **ER**: Indicates the country is Eritrea. - **ES**: Indicates the country is Spain. - **ET**: Indicates the country is Ethiopia. - **FI**: Indicates the country is Finland. - **FJ**: Indicates the country is Fiji. - **FK**: Indicates the country is Falkland Islands (Malvinas). - **FM**: Indicates the country is Federated States of Micronesia. - **FO**: Indicates the country is Faroe Islands. - **FR**: Indicates the country is France. - **GA**: Indicates the country is Gabon. - **GB**: Indicates the country is United Kingdom. - **GD**: Indicates the country is Grenada. - **GE**: Indicates the country is Georgia. - **GF**: Indicates the country is French Guiana. - **GG**: Indicates the country is Guernsey. - **GH**: Indicates the country is Ghana. - **GI**: Indicates the country is Gibraltar. - **GL**: Indicates the country is Greenland. - **GM**: Indicates the country is Gambia. - **GN**: Indicates the country is Guinea. - **GP**: Indicates the country is Guadeloupe. - **GQ**: Indicates the country is Equatorial Guinea. - **GR**: Indicates the country is Greece. - **GS**: Indicates the country is South Georgia and the South Sandwich Islands. - **GT**: Indicates the country is Guatemala. - **GU**: Indicates the country is Guam. - **GW**: Indicates the country is Guinea-Bissau. - **GY**: Indicates the country is Guyana. - **HK**: Indicates the country is Hong Kong. - **HM**: Indicates the country is Heard Island and McDonald Islands. - **HN**: Indicates the country is Honduras. - **HR**: Indicates the country is Croatia. - **HT**: Indicates the country is Haiti. - **HU**: Indicates the country is Hungary. - **ID**: Indicates the country is Indonesia. - **IE**: Indicates the country is Ireland. - **IL**: Indicates the country is Israel. - **IM**: Indicates the country is Isle of Man. - **IN**: Indicates the country is India. - **IO**: Indicates the country is British Indian Ocean Territory. - **IQ**: Indicates the country is Iraq. - **IR**: Indicates the country is Islamic Republic of Iran. - **IS**: Indicates the country is Iceland. - **IT**: Indicates the country is Italy. - **JE**: Indicates the country is Jersey. - **JM**: Indicates the country is Jamaica. - **JO**: Indicates the country is Jordan. - **JP**: Indicates the country is Japan. - **KE**: Indicates the country is Kenya. - **KG**: Indicates the country is Kyrgyzstan. - **KH**: Indicates the country is Cambodia. - **KI**: Indicates the country is Kiribati. - **KM**: Indicates the country is Comoros. - **KN**: Indicates the country is Saint Kitts and Nevis. - **KP**: Indicates the country is Democratic People's Republic of Korea. - **KR**: Indicates the country is Republic of Korea. - **KW**: Indicates the country is Kuwait. - **KY**: Indicates the country is Cayman Islands. - **KZ**: Indicates the country is Kazakhstan. - **LA**: Indicates the country is Lao People's Democratic Republic. - **LB**: Indicates the country is Lebanon. - **LC**: Indicates the country is Saint Lucia. - **LI**: Indicates the country is Liechtenstein. - **LK**: Indicates the country is Sri Lanka. - **LR**: Indicates the country is Liberia. - **LS**: Indicates the country is Lesotho. - **LT**: Indicates the country is Lithuania. - **LU**: Indicates the country is Luxembourg. - **LV**: Indicates the country is Latvia. - **LY**: Indicates the country is Libyan Arab Jamahiriya. - **MA**: Indicates the country is Morocco. - **MC**: Indicates the country is Monaco. - **MD**: Indicates the country is Republic of Moldova. - **ME**: Indicates the country is Montenegro. - **MF**: Indicates the country is Saint Martin (French part). - **MG**: Indicates the country is Madagascar. - **MH**: Indicates the country is Marshall Islands. - **MK**: Indicates the country is The Former Yugoslav Republic of Macedonia. - **ML**: Indicates the country is Mali. - **MM**: Indicates the country is Myanmar. - **MN**: Indicates the country is Mongolia. - **MO**: Indicates the country is Macao. - **MP**: Indicates the country is Northern Mariana Islands. - **MQ**: Indicates the country is Martinique. - **MR**: Indicates the country is Mauritania. - **MS**: Indicates the country is Montserrat. - **MT**: Indicates the country is Malta. - **MU**: Indicates the country is Mauritius. - **MV**: Indicates the country is Maldives. - **MW**: Indicates the country is Malawi. - **MX**: Indicates the country is Mexico. - **MY**: Indicates the country is Malaysia. - **MZ**: Indicates the country is Mozambique. - **NA**: Indicates the country is Namibia. - **NC**: Indicates the country is New Caledonia. - **NE**: Indicates the country is Niger. - **NF**: Indicates the country is Norfolk Island. - **NG**: Indicates the country is Nigeria. - **NI**: Indicates the country is Nicaragua. - **NL**: Indicates the country is Netherlands. - **NO**: Indicates the country is Norway. - **NP**: Indicates the country is Nepal. - **NR**: Indicates the country is Nauru. - **NU**: Indicates the country is Niue. - **NZ**: Indicates the country is New Zealand. - **OM**: Indicates the country is Oman. - **PA**: Indicates the country is Panama. - **PE**: Indicates the country is Peru. - **PF**: Indicates the country is French Polynesia. Includes Tahiti. - **PG**: Indicates the country is Papua New Guinea. - **PH**: Indicates the country is Philippines. - **PK**: Indicates the country is Pakistan. - **PL**: Indicates the country is Poland. - **PM**: Indicates the country is Saint Pierre and Miquelon. - **PN**: Indicates the country is Pitcairn. - **PR**: Indicates the country is Puerto Rico. - **PS**: Indicates the country is Palestinian territory Occupied. - **PT**: Indicates the country is Portugal. - **PW**: Indicates the country is Palau. - **PY**: Indicates the country is Paraguay. - **QA**: Indicates the country is Qatar. - **RE**: Indicates the country is Reunion. - **RO**: Indicates the country is Romania. - **RS**: Indicates the country is Serbia. - **RU**: Indicates the country is Russian Federation. - **RW**: Indicates the country is Rwanda. - **SA**: Indicates the country is Saudi Arabia. - **SB**: Indicates the country is Solomon Islands. - **SC**: Indicates the country is Seychelles. - **SD**: Indicates the country is Sudan. - **SE**: Indicates the country is Sweden. - **SG**: Indicates the country is Singapore. - **SH**: Indicates the country is Saint Helena. - **SI**: Indicates the country is Slovenia. - **SJ**: Indicates the country is Svalbard and Jan Mayen. - **SK**: Indicates the country is Slovakia. - **SL**: Indicates the country is Sierra Leone. - **SM**: Indicates the country is San Marino. - **SN**: Indicates the country is Senegal. - **SO**: Indicates the country is Somalia. - **SR**: Indicates the country is Suriname. - **SS**: Indicates the country is South Sudan. - **ST**: Indicates the country is Sao Tome and Principe. - **SV**: Indicates the country is El Salvador. - **SX**: Indicates the country is Sint Maarten (Dutch part). - **SY**: Indicates the country is Syrian Arab Republic. - **SZ**: Indicates the country is Swaziland. - **TC**: Indicates the country is Turks and Caicos Islands. - **TD**: Indicates the country is Chad. - **TF**: Indicates the country is French Southern Territories. - **TG**: Indicates the country is Togo. - **TH**: Indicates the country is Thailand. - **TJ**: Indicates the country is Tajikistan. - **TK**: Indicates the country is Tokelau. - **TL**: Indicates the country is Timor-Leste. - **TM**: Indicates the country is Turkmenistan. - **TN**: Indicates the country is Tunisia. - **TO**: Indicates the country is Tonga. - **TR**: Indicates the country is Turkey. - **TT**: Indicates the country is Trinidad and Tobago. - **TV**: Indicates the country is Tuvalu. - **TW**: Indicates the country is Taiwan. - **TZ**: Indicates the country is Tanzania. - **UA**: Indicates the country is Ukraine. - **UG**: Indicates the country is Uganda. - **UM**: Indicates the country is United States Minor Outlying Islands. - **US**: Indicates the country is United States. - **UY**: Indicates the country is Uruguay. - **UZ**: Indicates the country is Uzbekistan. - **VA**: Indicates the country is Holy See (Vatican City state). - **VC**: Indicates the country is Saint Vincent and the Grenadines. - **VE**: Indicates the country is Venezuela. - **VG**: Indicates the country is British Virgin Islands. - **VI**: Indicates the country is the U.S. Virgin Islands. - **VN**: Indicates the country is Vietnam. - **VU**: Indicates the country is Vanuatu. - **WF**: Indicates the country is Wallis and Futuna. - **WS**: Indicates the country is Samoa. - **YE**: Indicates the country is Yemen. - **YT**: Indicates the country is Mayotte. - **ZA**: Indicates the country is South Africa. - **ZM**: Indicates the country is Zambia. - **ZW**: Indicates the country is Zimbabwe. **Type:** string ### CurrencyCodeEnum **Description:** This enumerated type defines the three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code representing a world currency. | - **AED**: Indicates the currency is United Arab Emirates dirham. - **AFN**: Indicates the currency is Afghan afghani. - **ALL**: Indicates the currency is Albanian lek. - **AMD**: Indicates the currency is Armenian dram. - **AOA**: Indicates the currency is Angolan kwanza. - **ARS**: Indicates the currency is Argentine peso. - **AWG**: Indicates the currency is Aruban florin. - **AZN**: Indicates the currency is Azerbaijani manat. - **BAM**: Indicates the currency is Bosnia and Herzegovina convertible mark. - **BBD**: Indicates the currency is Barbados dollar. - **BDT**: Indicates the currency is a Bangladeshi taka. - **BGN**: Indicates the currency is Bulgarian lev. - **BHD**: Indicates the currency is Bahraini dinar. - **BIF**: Indicates the currency is Burundian franc. - **BMD**: Indicates the currency is Bermudian dollar. - **BND**: Indicates the currency is Brunei dollar. - **BOB**: Indicates the currency is Bolivian Boliviano. - **BRL**: Indicates the currency is Brazilian real. - **BSD**: Indicates the currency is Bahamian dollar. - **BTN**: Indicates the currency is Bhutanese ngultrum. - **BWP**: Indicates the currency is Botswana pula. - **BYR**: Indicates the currency is Belarusian ruble. - **BZD**: Indicates the currency is Belize dollar. - **CAD**: Indicates the currency is Canadian dollar. - **CDF**: Indicates the currency is Congolese franc. - **CLP**: Indicates the currency is Chilean peso. - **CNY**: Indicates the currency is Chinese yuan renminbi. - **COP**: Indicates the currency is Colombian peso. - **CRC**: Indicates the currency is Costa Rican colon. - **CUP**: Indicates the currency is Cuban peso. - **CVE**: Indicates the currency is Cape Verde escudo. - **CZK**: Indicates the currency is Czech koruna. - **DJF**: Indicates the currency is Djiboutian franc. - **DOP**: Indicates the currency is Dominican peso. - **DZD**: Indicates the currency is Algerian dinar. - **EGP**: Indicates the currency is Egyptian pound. - **ERN**: Indicates the currency is Eritrean nakfa. - **ETB**: Indicates the currency is Ethiopian birr. - **FJD**: Indicates the currency is Fiji dollar. - **FKP**: Indicates the currency is Falkland Islands pound. - **GEL**: Indicates the currency is Georgian lari. - **GHS**: Indicates the currency is Ghanaian cedi. - **GIP**: Indicates the currency is Gibraltar pound. - **DKK**: Indicates the currency is Danish krone. - **GMD**: Indicates the currency is Gambian dalasi. - **GNF**: Indicates the currency is Guinean franc. - **GTQ**: Indicates the currency is Guatemalan quetzal. - **GYD**: Indicates the currency is Guyanese dollar. - **HKD**: Indicates the currency is Hong Kong dollar. - **HNL**: Indicates the currency is Honduran lempira. - **HRK**: Indicates the currency is Croatian kuna. - **HTG**: Indicates the currency is Haitian gourde. - **HUF**: Indicates the currency is Hungarian forint. - **IDR**: Indicates the currency is Indonesian rupiah. - **INR**: Indicates the currency is Indian rupee. - **IQD**: Indicates the currency is Iraqi dinar. - **IRR**: Indicates the currency is Iranian rial. - **ISK**: Indicates the currency is Icelandic krona. - **GBP**: Indicates the currency is British pound sterling. - **JMD**: Indicates the currency is Jamaican dollar. - **JOD**: Indicates the currency is Jordanian dinar. - **JPY**: Indicates the currency is Japanese yen. - **KES**: Indicates the currency is Kenyan shilling. - **KGS**: Indicates the currency is Kyrgyzstani som. - **KHR**: Indicates the currency is Cambodian riel. - **KMF**: Indicates the currency is Comoro franc. - **KPW**: Indicates the currency is North Korean won. - **KRW**: Indicates the currency is South Korean won. - **KWD**: Indicates the currency is Kuwaiti dinar. - **KYD**: Indicates the currency is Cayman Islands dollar. - **KZT**: Indicates the currency is Kazakhstani tenge. - **LAK**: Indicates the currency is Lao kip. - **LBP**: Indicates the currency is Lebanese pound. - **CHF**: Indicates the currency is a Swiss franc. - **LKR**: Indicates the currency is Sri Lankan rupee. - **LRD**: Indicates the currency is Liberian dollar. - **LSL**: Indicates the currency is Lesotho loti. - **LTL**: Indicates the currency is Lithuanian litas. - **LYD**: Indicates the currency is Libyan dinar. - **MAD**: Indicates the currency is Moroccan dirham. - **MDL**: Indicates the currency is Moldovan leu. - **MGA**: Indicates the currency is Malagasy ariary. - **MKD**: Indicates the currency is Macedonian denar. - **MMK**: Indicates the currency is Myanmar kyat. - **MNT**: Indicates the currency is Mongolian tugrik. - **MOP**: Indicates the currency is Macanese pataca. - **MRO**: Indicates the currency is Mauritanian ouguiya. - **XCD**: Indicates the currency is East Caribbean dollar. - **MUR**: Indicates the currency is Mauritian rupee. - **MVR**: Indicates the currency is Maldivian rufiyaa. - **MWK**: Indicates the currency is Malawian kwacha. - **MXN**: Indicates the currency is Mexican peso. - **MYR**: Indicates the currency is Malaysian ringgit. - **MZN**: Indicates the currency is Mozambican metical. - **NAD**: Indicates the currency is Namibian dollar. - **NGN**: Indicates the currency is Nigerian naira. - **NIO**: Indicates the currency is Nicaraguan cordoba oro. - **NPR**: Indicates the currency is Nepalese rupee. - **OMR**: Indicates the currency is Omani rial. - **PAB**: Indicates the currency is Panamanian balboa. - **PEN**: Indicates the currency is Peruvian sol. - **XPF**: Indicates the currency is CFP franc. - **PGK**: Indicates the currency is Papua New Guinean kina. - **PHP**: Indicates the currency is Philippine peso. - **PKR**: Indicates the currency is Pakistani rupee. - **PLN**: Indicates the currency is Polish zloty. - **ILS**: Indicates the currency is Israeli new shekel. - **PYG**: Indicates the currency is Paraguayan guarani. - **QAR**: Indicates the currency is Qatari riyal. - **RON**: Indicates the currency is Romanian leu. - **RSD**: Indicates the currency is Serbian dinar. - **RUB**: Indicates the currency is Russian ruble. - **RWF**: Indicates the currency is Rwandan franc. - **SAR**: Indicates the currency is Saudi riyal. - **SBD**: Indicates the currency is Solomon Islands dollar. - **SCR**: Indicates the currency is Seychelles rupee. - **SDG**: Indicates the currency is Sudanese pound. - **SEK**: Indicates the currency is Swedish krona. - **SGD**: Indicates the currency is Singapore dollar. - **SHP**: Indicates the currency is Saint Helena pound. - **NOK**: Indicates the currency is Norwegian krone. - **SLL**: Indicates the currency is Sierra Leonean leone. - **SOS**: Indicates the currency is Somali shilling. - **SRD**: Indicates the currency is Surinamese dollar. - **STD**: Indicates the currency is Sao Tome and Principe dobra. - **ANG**: Indicates the currency is Netherlands Antillean guilder. - **SYP**: Indicates the currency is Syrian pound. - **SZL**: Indicates the currency is Swazi lilangeni. - **XAF**: Indicates the currency is CFA franc BEAC. - **XOF**: Indicates the currency is CFA franc BCEAO. - **THB**: Indicates the currency is Thai baht. - **TJS**: Indicates the currency is Tajikistani somoni. - **NZD**: Indicates the currency is New Zealand dollar. - **TMT**: Indicates the currency is Turkmenistani manat. - **TND**: Indicates the currency is Tunisian dinar. - **TOP**: Indicates the currency is Tongan pa'anga. - **TRY**: Indicates the currency is Turkish lira. - **TTD**: Indicates the currency is Trinidad and Tobago dollar. - **AUD**: Indicates the currency is Australian dollar. - **TWD**: Indicates the currency is New Taiwan dollar. - **TZS**: Indicates the currency is Tanzanian shilling. - **UAH**: Indicates the currency is Ukrainian hryvnia. - **UGX**: Indicates the currency is Ugandan shilling. - **USD**: Indicates the currency is United States dollar. - **UYU**: Indicates the currency is Uruguayan peso. - **UZS**: Indicates the currency is Uzbekistani som. - **VEF**: Indicates the currency is Venezuelan bolivar. - **VND**: Indicates the currency is Vietnamese dong. - **VUV**: Indicates the currency is Vanuatu vatu. - **WST**: Indicates the currency is Samoan tala. - **YER**: Indicates the currency is Yemeni rial. - **EUR**: Indicates the currency is European Union euro. - **ZAR**: Indicates the currency is South African rand. - **ZMW**: Indicates the currency is Zambian kwacha. - **ZWL**: Indicates the currency is Zimbabwean dollar. **Type:** string ### ErrorDetailV3 **Description:** This type defines the fields that can be returned in an error. **Type:** object **Properties:** - **category** (string) - This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. - **domain** (string) - The name of the primary system where the error occurred. This is relevant for application errors. - **errorId** (integer) - A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. - **inputRefIds** (array) - An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. - **longMessage** (string) - A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. - **message** (string) - A description of the condition that caused the error or warning. - **outputRefIds** (array) - An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. - **parameters** (array) - An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning. - **subdomain** (string) - The name of the subdomain in which the error or warning occurred. ### ErrorParameterV3 **Description:** This type defines the name and value of the input field that caused the error. **Type:** object **Properties:** - **name** (string) - This is the name of input field that caused an issue with the call request. - **value** (string) - This is the actual value that was passed in for the element specified in the **name** field. ### Image **Description:** This type defines the details of an image, such as size and URL. Currently only **imageUrl** will be populated. The **height** and **width** fields were added for future use. **Type:** object **Properties:** - **height** (integer) - **Reserved for future use.** - **imageUrl** (string) - The URL of the image. - **width** (integer) - **Reserved for future use.** ### ItemLocation **Description:** This type defines the country location details of an item. **Type:** object **Properties:** - **country** (CountryCodeEnum) - The two-letter [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) standard code that indicates the country in which the item is located. ### MarketPriceDetail **Description:** This type defines the market price details of a product. **Type:** object **Properties:** - **conditionGroup** (string) - The type that defines the fields for details about the product, such as condition and estimated start price. - **conditionIds** (array) - An array of condition identifiers for the product. - **estimatedStartPrice** (Amount) - The lowest priced active item for this product on eBay. ### MarketplaceIdEnum **Description:** This enumerated type is used to indicate the different eBay marketplace sites. | - **EBAY_US**: This enumeration value indicates that the eBay Marketplace is the US site (ebay.com). - **EBAY_CA**: This enumeration value indicates that the eBay Marketplace is the Canada (English) site (ebay.ca). - **EBAY_GB**: This enumeration value indicates that the eBay Marketplace is the UK site (ebay.co.uk). - **EBAY_AU**: This enumeration value indicates that the eBay Marketplace is the Australia site (ebay.com.au). - **EBAY_AT**: This enumeration value indicates that the eBay Marketplace is the Austria site (ebay.at). - **EBAY_BE**: This enumeration value indicates that the eBay marketplace is the Belgium (Dutch) site (www.ebay.be). - **EBAY_DE**: This enumeration value indicates that the eBay Marketplace is the Germany site (ebay.de). - **EBAY_IT**: This enumeration value indicates that the eBay Marketplace is the Italy site (ebay.it). - **EBAY_NL**: This enumeration value indicates that the eBay Marketplace is the Netherlands site (ebay.nl). - **EBAY_ES**: This enumeration value indicates that the eBay Marketplace is the Spain site (ebay.es). - **EBAY_CH**: This enumeration value indicates that the eBay Marketplace is the Switzerland site (ebay.ch). - **EBAY_TW**: This enumeration value indicates that the eBay Marketplace is the Taiwan site (ebay.com/tw). - **EBAY_CZ**: This enumeration value indicates that the eBay Marketplace is the Czech Republic site (ebay.com/sch/Czech-Republic). - **EBAY_DK**: This enumeration value indicates that the eBay Marketplace is the Denmark site (ebay.com/sch/Denmark). - **EBAY_FI**: This enumeration value indicates that the eBay Marketplace is the Finland site (ebay.com/sch/Finland). - **EBAY_FR**: This enumeration value indicates that the eBay Marketplace is the France site (ebay.fr). - **EBAY_GR**: This enumeration value indicates that the eBay Marketplace is the Greece site (ebay.com/sch/Greece). - **EBAY_HK**: This enumeration value indicates that the eBay Marketplace is the Hong Kong site (ebay.com.hk). - **EBAY_HU**: This enumeration value indicates that the eBay Marketplace is the Hungary site (ebay.com/sch/Hungary). - **EBAY_IN**: This enumeration value indicates that the eBay Marketplace is the India site (ebay.in). Note: eBay India is no longer a functioning eBay marketplace. - **EBAY_ID**: This enumeration value indicates that the eBay Marketplace is the Indonesia site (id.ebay.com). - **EBAY_IE**: This enumeration value indicates that the eBay Marketplace is the Ireland site (ebay.ie). - **EBAY_IL**: This enumeration value indicates that the eBay Marketplace is the Israel site (ebay.com/sch/Israel). - **EBAY_MY**: This enumeration value indicates that the eBay Marketplace is the Malaysia site (ebay.com/my). - **EBAY_NZ**: This enumeration value indicates that the eBay Marketplace is the New Zealand site (ebay.com/sch/New-Zealand). - **EBAY_NO**: This enumeration value indicates that the eBay Marketplace is the Norway site (ebay.com/sch/Norway). - **EBAY_PH**: This enumeration value indicates that the eBay Marketplace is the Philippines site (ebay.ph). - **EBAY_PL**: This enumeration value indicates that the eBay Marketplace is the Poland site (ebay.pl). - **EBAY_PT**: This enumeration value indicates that the eBay Marketplace is the Portugal site (ebay.com/sch/Portugal). - **EBAY_PR**: This enumeration value indicates that the eBay Marketplace is the Puerto Rico site (ebay.com/sch/Puerto-Rico). - **EBAY_RU**: This enumeration value indicates that the eBay Marketplace is the Russia site (ebay.com/sch/Russia). - **EBAY_SG**: This enumeration value indicates that the eBay Marketplace is the Singapore site (ebay.com/sg). - **EBAY_ZA**: This enumeration value indicates that the eBay Marketplace is the South Africa site (ebay.com/sch/South-Africa). - **EBAY_SE**: This enumeration value indicates that the eBay Marketplace is the Sweden site (ebay.com/sch/Sweden). - **EBAY_TH**: This enumeration value indicates that the eBay Marketplace is the Thailand site (export.ebay.co.th). - **EBAY_VN**: This enumeration value indicates that the eBay Marketplace is the Vietnam site (ebay.vn). - **EBAY_CN**: This enumeration value indicates that the eBay Marketplace is the China site (ebay.com/sch/China). - **EBAY_JP**: This enumeration value indicates that the eBay Marketplace is the Japan site (ebay.co.jp). - **EBAY_PE**: This enumeration value indicates that the eBay Marketplace is the Peru site (ebay.com/sch/Peru). - **EBAY_HALF_US**: This enumeration value is no longer applicable as the Half.com site no longer exists. - **EBAY_MOTORS_US**: This enumeration value indicates that the eBay Marketplace is the US eBay Motors site (ebay.com/motors). **Type:** string ### MerchandisedProduct **Description:** This type defines the fields for product information, including price, condition, ratings, etc. **Type:** object **Properties:** - **averageRating** (string) - The average rating for the product based on eBay user ratings. - **epid** (string) - The eBay product identifier of a product from the eBay product catalog. You can use this value in the Browse API **search** method to retrieve items for this product. - **image** (Image) - The product image. - **marketPriceDetails** (array) - An array of containers for the product market price details, such as condition and market price. - **ratingAspects** (array) - An array of containers for ratings of the product aspects, such as "Is it a good value". - **ratingCount** (integer) - The total number of eBay users that rated the product. - **reviewCount** (integer) - The total number of eBay users that wrote a review for the product. - **title** (string) - The title of the product. ### MostWatchedItem **Description:** This type defines item details about a most watched item. **Type:** object **Properties:** - **bidCount** (integer) - 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. - **category** (Category) - The ID of the leaf category for this item. - **currentBidPrice** (Amount) - 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. - **galleryImageUrl** (string) - The URL for the image used as the Gallery thumbnail. - **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. - **itemId** (string) - The unique RESTful identifier of the item. - **itemLocation** (ItemLocation) - This container returns the 2-digit ISO code of the country in which the item is location. - **itemWebUrl** (string) - The URL to the View Item page of the item. - **listingMarketplaceId** (MarketplaceIdEnum) - The unique identifier of the eBay marketplace of the listing. - **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. - **shippingCost** (Amount) - The final shipping cost of the item. - **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). - **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. - **title** (string) - The title of the item as its appears on the listing. - **watchCount** (integer) - The number of users that have added the item to their watch list. ### MostWatchedItemsResponse **Description:** This type defines the response payload of the **getMostWatchedItems** method. **Type:** object **Properties:** - **mostWatchedItems** (array) - This array returns a list of most watched items matching the input criteria. ### RatingAspect **Description:** This type defines the fields for the product aspect ratings. **Type:** object **Properties:** - **count** (integer) - The number of eBay users that rated the product on this aspect. - **description** (string) - The name of the rating aspect. Camping tent examples: Is it lightweight? or Is it easy to set up? - **name** (string) - The answer or value of the rating aspect. Camping tent examples: Lightweight or Easy to set up - **ratingAspectDistributions** (array) - The container for the details of the aspect rating. The details show the aspect rating value, usually TRUE or FALSE and the user count and percentage. ### RatingAspectDistribution **Description:** This type defines the field for the aspect rating details, such as the aspect rating value, usually TRUE or FALSE and the user count and percentage. **Type:** object **Properties:** - **count** (integer) - The number of eBay users that choose this rating aspect value. - **percentage** (string) - The percentage of the aspect rating value. **ratingAspectDistributions.percentage** = **ratingAspectDistributions.count** / **ratingAspects.count** - **value** (string) - The rating aspect. For example: TRUE or FALSE ### SimilarItem **Description:** This type returns details about an item that is similar to the specified item. **Type:** object **Properties:** - **bidCount** (integer) - 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. - **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. - **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. - **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. - **itemId** (string) - The unique RESTful identifier of the item. - **itemLocation** (ItemLocation) - This container returns the 2-digit ISO code of the country in which the item is location. - **itemWebUrl** (string) - The URL to the View Item page of the listing. - **listingMarketplaceId** (MarketplaceIdEnum) - The unique identifier of the eBay marketplace of the listing. - **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. - **primaryCategory** (Category) - This container returns the category name and ID of the primary listing category. - **shippingCost** (Amount) - The final shipping cost for all the item. - **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). - **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. - **title** (string) - The title of the item as its appears on the listing. ### SimilarItemsResponse **Description:** This type defines the response container for the **getSimilarItems** method. **Type:** object **Properties:** - **similarItems** (array) - This array returns a list of similar items matching the input criteria. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-04-10T13:18:04.760Z*