Skip to main content

PUT/inventory_item/{sku}/product_compatibility

This call is used by the seller to create or replace a list of products that are compatible with the inventory item. The inventory item is identified with a SKU value in the URI. Product compatibility is currently only applicable to motor vehicle parts and accessory categories, but more categories may be supported in the future.

Note: In addition to the authorization header, which is required for all Inventory API calls, this call also requires the Content-Type and Content-Language headers. See the HTTP request headers for more information.

Input

Resource URI

PUT https://api.ebay.com/sell/inventory/v1/inventory_item/{sku}/product_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

ParameterTypeDescription
skustringThis path parameter specifies the SKU (stock keeping unit) of the inventory item associated with the compatibility list being created.

Use the getInventoryItems method to retrieve SKU values.

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.

HeaderTypeDescription
Content-LanguagestringThis header sets the natural language that will be used in the field values of the request payload. For example, the value passed in this header should be en-US for English or de-DE for German.

For more information on the Content-Language header, refer to HTTP request headers.

Occurrence: Required

Content-TypestringThis 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.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code 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/sell.inventory

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
compatibleProductsarray of CompatibleProduct

This container consists of an array of motor vehicles (make, model, year, trim, engine) that are compatible with the motor vehicle part or accessory specified by the sku value.

Occurrence: Required

compatibleProducts.compatibilityPropertiesarray of NameValueList

This container consists of an array of motor vehicles that are compatible with the motor vehicle part or accessory specified by the SKU value in the call URI. Each motor vehicle is defined through a separate set of name/value pairs. In the name field, the vehicle aspect (such as 'make', 'model', 'year', 'trim', or 'engine') will be identified, and the value field will be used to identify the value of each aspect.

The getCompatibilityProperties method of the Taxonomy API can be used to retrieve applicable vehicle aspect names for a specified category, and the getCompatibilityPropertyValues method of the Taxonomy API can be used to retrieve possible values for these same vehicle aspect names.

Below is an example of identifying one motor vehicle using the compatibilityProperties container:

"compatibilityProperties" : [
  {
   "name" : "make",
   "value" : "Subaru"
  },
  {
   "name" : "model",
   "value" : "GL"
  },
  {
   "name" : "year",
   "value" : "1983"
  },
  {
   "name" : "trim",
   "value" : "Base Wagon 4-Door"
  },
  {
   "name" : "engine",
   "value" : "1.8L Turbocharged"
  }
]


Typically, the make, model, and year of the motor vehicle are always required, with the trim and engine being necessary sometimes, but it will be dependent on the part or accessory, and on the vehicle class.

Note: The productFamilyProperties container is deprecated and should no longer be used. The compatibilityProperties container should be used instead.

Occurrence: Conditional

compatibleProducts.compatibilityProperties.namestring

This string value identifies the motor vehicle aspect, such as 'make', 'model', 'year', 'trim', and 'engine'. Typically, the make, model, and year of the motor vehicle are always required, with the trim and engine being necessary sometimes, but it will be dependent on the part or accessory, and on the vehicle class.

The getCompatibilityProperties method of the Taxonomy API can be used to retrieve applicable vehicle aspect names for a specified category.

Occurrence: Conditional

compatibleProducts.compatibilityProperties.valuestring

This string value identifies the motor vehicle aspect specified in the corresponding name field. For example, if the name field is 'make', this field may be 'Toyota', or if the name field is 'model', this field may be 'Camry'.

The getCompatibilityPropertyValues method of the Taxonomy API can be used to retrieve possible values for vehicle aspect names.

Occurrence: Conditional

compatibleProducts.notesstring

This field is used by the seller to input any notes pertaining to the compatible vehicle list being defined. The seller might use this field to specify the placement of the part on a vehicle or other applicable information.

This field will only be returned if specified by the seller.

Max Length: 500

Occurrence: Optional

compatibleProducts.productFamilyPropertiesProductFamilyProperties

Important! The productFamilyProperties container is deprecated and should no longer be used. The compatibilityProperties container should be used instead.

Occurrence: Conditional

compatibleProducts.productFamilyProperties.enginestring

Important! The productFamilyProperties container is no longer supported.

Occurrence: Conditional

compatibleProducts.productFamilyProperties.makestring

Important! The productFamilyProperties container is no longer supported.

Occurrence: Conditional

compatibleProducts.productFamilyProperties.modelstring

Important! The productFamilyProperties container is no longer supported.

Occurrence: Conditional

compatibleProducts.productFamilyProperties.trimstring

Important! The productFamilyProperties container is no longer supported.

Occurrence: Conditional

compatibleProducts.productFamilyProperties.yearstring

Important! The productFamilyProperties container is no longer supported.

Occurrence: Conditional

compatibleProducts.productIdentifierProductIdentifier

This container is used in a createOrReplaceProductCompatibility call to identify a motor vehicle that is compatible with the inventory item. The user specifies either an eBay Product ID (ePID) or K-Type value to identify a vehicle, and if the motor vehicle is found in the eBay product catalog, the motor vehicle properties (make, model, year, trim, engine) will automatically be populated for the vehicle. If the vehicle cannot be found using these identifiers, the vehicle will not be added to the compatible vehicle list.

Note that this container will not be returned in the getProductCompatibility call.

Occurrence: Conditional

compatibleProducts.productIdentifier.epidstring

This field can be used if the seller already knows the eBay catalog product ID (ePID) associated with the motor vehicle that is to be added to the compatible product list. If this eBay catalog product ID is found in the eBay product catalog, the motor vehicle properties (e.g. make, model, year, engine, and trim) will automatically get picked up for that motor vehicle.

Occurrence: Optional

compatibleProducts.productIdentifier.gtinstring

This field can be used if the seller knows the Global Trade Item Number for the motor vehicle that is to be added to the compatible product list. If this GTIN value is found in the eBay product catalog, the motor vehicle properties (e.g. make, model, year, engine, and trim will automatically get picked up for that motor vehicle.

Note: This field is for future use.

Occurrence: Optional

compatibleProducts.productIdentifier.ktypestring

This field can be used if the seller knows the K Type Number for the motor vehicle that is to be added to the compatible product list. If this K Type value is found in the eBay product catalog, the motor vehicle properties (e.g. make, model, year, engine, and trim) will automatically get picked up for that motor vehicle.

Only the AU, DE, ES, FR, IT, and UK marketplaces support the use of K Type Numbers.

Occurrence: Optional

skustring

The seller-defined SKU value of the inventory item that will be associated with the compatible vehicles.

Note: This field is not applicable to the createOrReplaceProductCompatibility method, as the SKU value for the inventory item is passed in as part of the call URI and not in the request payload. It is always returned with the getProductCompatibility method.

Occurrence: NA

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
Content-LanguageThis response header sets the natural language that will be provided in the field values of the response payload.

Response payload

Response fields

Output container/fieldTypeDescription
warningsarray of ErrorDetailV3

This container will be returned in a call response payload if one or more warnings or errors are triggered when an Inventory API call is made. This container will contain detailed information about the error or warning.

Occurrence: Conditional

warnings.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

warnings.domainstring

The name of the domain in which the error or warning occurred.

Occurrence: Conditional

warnings.errorIdinteger

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: Conditional

warnings.inputRefIdsarray of string

An array of one or more reference IDs which identify the specific request element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestring

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.messagestring

A description of the condition that caused the error or warning.

Occurrence: Conditional

warnings.outputRefIdsarray of string

An array of one or more reference IDs which identify the specific response element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

Various warning and error messages return one or more variables that contain contextual information about the error or waring. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

warnings.parameters.namestring

This type contains the name and value of an input parameter that contributed to a specific error or warning condition.

Occurrence: Conditional

warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstring

The name of the subdomain in which the error or warning occurred.

Occurrence: Conditional

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.

StatusMeaning
200Success
201Created
204No Content
400Bad Request
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONA system error has occurred. {additionalInfo}
25002API_INVENTORYREQUESTA user error has occurred. {additionalInfo}
25003API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid price. {additionalInfo}
25004API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid quantity. {additionalInfo}
25005API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid category ID. {additionalInfo}
25006API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid listing option. {additionalInfo}
25007API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Fulfillment policy. {additionalInfo}
25008API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Payment policy. {additionalInfo}
25009API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid data in the associated Return policy. {additionalInfo}
25011API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid tax information. {additionalInfo}
25012API_INVENTORYREQUESTInvalid inventory location. {additionalInfo}
25013API_INVENTORYREQUESTInvalid data in the Inventory Item Group. {additionalInfo}
25014API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid pictures. {additionalInfo}
25015API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has an invalid picture URL. {additionalInfo}
25016API_INVENTORYREQUESTThe {fieldName} value is invalid. {additionalInfo}
25017API_INVENTORYREQUEST{fieldName} is missing. {additionalInfo}
25018API_INVENTORYREQUESTIncomplete account information. {additionalInfo}
25019API_INVENTORYREQUESTCannot revise listing. {additionalInfo}
25020API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid shipping package details. {additionalInfo}
25021API_INVENTORYREQUESTThe eBay listing associated with the inventory item, or the unpublished offer has invalid item condition information. {additionalInfo}
25022API_INVENTORYREQUESTInvalid attribute. {fieldName}
25023API_INVENTORYREQUESTInvalid compatibility information. {additionalInfo}
25025API_INVENTORYAPPLICATIONConcurrent access of the same Inventory or Inventory Item Group object is not allowed. Please try again later.
25026API_INVENTORYREQUESTSelling limit exceeded. {additionalInfo}
25702API_INVENTORYREQUEST{skuValue} could not be found or is not available in the system.
25739API_INVENTORYREQUESTUser input error. The number of compatibilityProperties in the request cannot exceed {additionalInfo}.
25740API_INVENTORYREQUESTUser input error. Invalid name for compatibilityProperties. The length should be between 1 and {additionalInfo} characters.
25741API_INVENTORYREQUESTUser input error. Invalid value for compatibilityProperties. The length should be between 1 and {additionalInfo} characters.
25742API_INVENTORYREQUESTUser input error. productFamilyProperties and compatibilityProperties cannot be used together. Please use compatibilityProperties.

Warnings

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

CodeDomainCategoryMeaning
25401API_INVENTORYAPPLICATIONInvalid listing format removed. {additionalInfo}
25402API_INVENTORYAPPLICATIONSystem warning. {additionalInfo}

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: Create Compatible Products

This call creates a list of compatible vehicles for a motor vehicle part. When this particular part is listed as an eBay item, these compatible vehicles will be shown.

Input

The SKU value for the motor vehicle part is passed in as part of call URI. The attributes for two compatible vehicles are passed in the request payload.

PUThttps://api.ebay.com/sell/inventory/v1/inventory_item/Al-8730/product_compatibility

Output

Unless there are any errors or warnings, there is no output payload with this response. A successful call contains an HTTP status code of 200.