checkCompatibility: eBay Browse API | eBay Developers Program

POST/item/{item_id}/check_compatibility

This method checks if a product is compatible with the specified item. You can use this method to check the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay.

For example, to check the compatibility of a part, you pass in the item_id of the part as a URI parameter and specify all the attributes used to define a specific car within the compatibilityProperties container. If the call is successful, the response will be COMPATIBLE, NOT_COMPATIBLE, or UNDETERMINED. Refer to compatibilityStatus for details.

Note: The only products supported are cars, trucks, and motorcycles.
To find the attributes and values for a specific marketplace, you can use the compatibility methods in the Taxonomy API. You can use this data to create menus to help buyers specify the product, such as their car.

For more information and a list of required attributes for the US marketplace that describe motor vehicles, refer to Check compatibility in the Buying Integration Guide.

For an example, refer to the Samples section.

Note: This method is supported in Sandbox but only when passing in the specified item_id and compatibility name-value pairs listed in Sample 2: Sandbox Sample.

Restrictions

For a list of supported sites and other restrictions, refer to API Restrictions.

Input

Resource URI

POST https://api.ebay.com/buy/browse/v1/item/{item_id}/check_compatibility

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

Parameter	Type	Description
item_id	string	This path parameter specifies the unique RESTful identifier of an item (such as the park you want to check). 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
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to `application/json`. For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide. Occurrence: Required
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

Content-Type

string

This header indicates the format of the request body provided by the client.

Its value should be set to application/json.

For more information, refer to HTTP request headers in the Using eBay RESTful APIs guide.

Occurrence: Required

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

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

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* CompatibilityPayload */

"compatibilityProperties" : [

{ /* AttributeNameValue */

"name" : "string",

"value" : "string"

}

]

}

Request fields

Input container/field Type Description

Input container/field	Type	Description
compatibilityProperties	array of AttributeNameValue	An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be `"name" : "Year", "value" : "2019"` For a list of the attributes required for cars and trucks and motorcycles see Check compatibility in the Buy Integration Guide. Occurrence: Required
compatibilityProperties.name	string	The name of the product attribute, such as Make, Model, Year, etc. Occurrence: Required
compatibilityProperties.value	string	The value for the `name` attribute, such as BMW, R1200GS, 2011, etc. Occurrence: Required

compatibilityProperties

array of AttributeNameValue

An array of attribute name/value pairs used to define a specific product. For example: If you wanted to specify a specific car, one of the name/value pairs would be

"name" : "Year", "value" : "2019"

For a list of the attributes required for cars and trucks and motorcycles see Check compatibility in the Buy Integration Guide.

Occurrence: Required

compatibilityProperties.name

string

The name of the product attribute, such as Make, Model, Year, etc.

Occurrence: Required

compatibilityProperties.value

string

The value for the name attribute, such as BMW, R1200GS, 2011, etc.

Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* CompatibilityResponse */

"compatibilityStatus" : "CompatibilityStatus : [COMPATIBLE,NOT_COMPATIBLE,UNDETERMINED]",

"warnings" : [

{ /* ErrorDetailV3 */

"category" : "string",

"domain" : "string",

"errorId" : "integer",

"inputRefIds" : [

"string"

"longMessage" : "string",

"message" : "string",

"outputRefIds" : [

"string"

"parameters" : [

{ /* ErrorParameterV3 */

"name" : "string",

"value" : "string"

}

"subdomain" : "string"

}

]

}

Response fields

Output container/field	Type	Description
compatibilityStatus	CompatibilityStatus	An enumeration value that tells you if the item is compatible with the product. The values are: COMPATIBLE - Indicates the item is compatible with the product specified in the request. NOT_COMPATIBLE - Indicates the item is not compatible with the product specified in the request. Be sure to check all the value fields to ensure they are correct as errors in the value can also cause this response. UNDETERMINED - Indicates one or more attributes for the specified product are missing so compatibility cannot be determined. The response returns the attributes that are missing. Code so that your app gracefully handles any future changes to this list. Occurrence: Conditional
warnings	array of ErrorDetailV3	An array of warning messages. These types of errors do not prevent the method from executing but should be checked. Occurrence: Conditional
warnings.category	string	This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Always
warnings.domain	string	The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Always
warnings.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. Occurrence: Always
warnings.inputRefIds	array of string	An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. Occurrence: Conditional
warnings.longMessage	string	A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. Occurrence: Conditional
warnings.message	string	A description of the condition that caused the error or warning. Occurrence: Always
warnings.outputRefIds	array of string	An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. Occurrence: Conditional
warnings.parameters	array of ErrorParameterV3	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. Occurrence: Conditional
warnings.parameters.name	string	This is the name of input field that caused an issue with the call request. Occurrence: Conditional
warnings.parameters.value	string	This is the actual value that was passed in for the element specified in the `name` field. Occurrence: Conditional
warnings.subdomain	string	The name of the subdomain in which the error or warning occurred. Occurrence: NA

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
404	Not Found
409	Conflict
500	Internal Server Error

Error codes

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

Code	Domain	Category	Meaning
11000	API_BROWSE	APPLICATION	There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
11001	API_BROWSE	REQUEST	The specified item ID was not found.
11011	API_BROWSE	REQUEST	The marketplace value {marketplaceId} is not supported. The supported values are: {allowedMarketplaces}
11503	API_BROWSE	REQUEST	The request is either empty or incomplete. For help, see the documentation for this call.
11505	API_BROWSE	REQUEST	The item is not valid for compatibility validation.
11506	API_BROWSE	REQUEST	The 'name' {compatibilityNames} appears more than once in the request.
11507	API_BROWSE	REQUEST	The following name(s) in the request are not supported {attributes}.

Warnings

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

Code	Domain	Category	Meaning
11504	API_BROWSE	REQUEST	The following compatibilityProperties (attributes name/value pairs) are missing: {attributes}

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: Checks for Part Compatibility on US Marketplace

Sample 2: Sandbox Sample

Sample 1: Checks for Part Compatibility on US Marketplace

This sample checks whether the part specified by the item ID is compatible with the specified vehicle.

Input

The item ID of the motor vehicle is input as a path parameter in the URL, and the attributes (name/value pairs) that define a specific vehicle are included in the request payload. In this sample, the part is a headlight bulb and the request will check whether the bulb is compatible with a 2016 Honda EX-L Hatchback 4-Door.

You also need to pass in EBAY_US in the X-EBAY-C-MARKETPLACE-ID request header.

POSThttps://api.ebay.com/buy/browse/v1/item/v1|1**********9|0/check_compatibility

Output

The output is the compatibilityStatus field, which shows that the part is compatible with the vehicle.

Sample 2: Sandbox Sample

This sample can be ran in the Sandbox enviroment to produce a result that indicates that a motor vehicle part is compatibile with the vehicle specified in the request payload.

Input

The item ID of the motor vehicle is input as a path parameter in the URL, and the attributes (name/value pairs) that define a specific vehicle are included in the request payload.

You also need to pass in EBAY_US in the X-EBAY-C-MARKETPLACE-ID request header.

POSThttps://api.sandbox.ebay.com/buy/browse/v1/item/v1%7C281726208046%7C0/check_compatibility

Output

The output is the compatibilityStatus field, which shows that the part is compatible with the vehicle.