eBay Product Services APIs retrieve information about products on eBay to help sellers add products to the eBay catalogs or to list items with Parts Compatibility. Parts Compatibility is an eBay feature that uses structured data to associate compatible assemblies with parts listed on eBay. For example, Parts Compatibility enables sellers to specify accurately and comprehensively the vehicles on which a headlight or a rim will fit. Parts compatibility improves search relevancy and frees up item titles and descriptions for more detailed and informative descriptions of the part.
eBay Product Services consists of two separate APIs, the Product API and Product Metadata API. These APIs retrieve valuable information and metadata about products on eBay to help you add new items to an eBay catalog or to list items with Parts Compatibility.
The Product API consists of calls that return product information. For example, you can use the Product API to identify products that have associated compatibilities. Listing an item with a product that has compatibilities (e.g., specific vehicle applications, such as a 2004 Honda Accord) is one way to list an item with parts compatibility information.
The API lets you retrieve product information in a variety of ways:
The Product API also has calls to help you add products to the eBay catalog.
Refer to the eBay Product API Call Reference for a list of API calls and the associated inputs and outputs for each.
The Product Metadata API consists of calls that return product metadata for specific categories. For example, you can use the Product Metadata API to retrieve the compatibility search names (e.g., Make and Model) and values (e.g., Honda and Accord) that are allowed for a given category. You can use this compatibility metadata to construct compatible applications for a specific category. Listing an item with compatible applications (e.g., a fender that fits specific cars) is one way to list an item with parts compatibility information. This is known as listing with compatibility by application.
The API returns the following types of metadata:
Refer to the eBay Product Metadata API Call Reference for a list of API calls and the associated inputs and outputs for each.
The eBay Product API and eBay Product Metadata API support the following eBay features:
Product Creation is the capability to add a new product to an eBay catalog associated with a given category. All eBay Electronics categories require sellers to list with a product whenever there's a product match in the associated eBay catalog. Starting in September 2011, listing with a product will be required in some categories. When listing with a product is required and the catalog does not contain a matching product, the seller must add the product to the catalog before listing.
Product Creation consists of the following steps:
| Note: Product creation is supported for a subset of categories on the US (global ID EBAY-US) and UK (global ID EBAY-GB) sites only. Use GetCategoryFeatures in the Trading API to determine which categories support product creation. |
If you attempt to list an item using a product ID that is not in the eBay catalog for the specified category, your listing will fail. This indicates that you may need to add a product to the catalog, or it may indicate you should list in a different category.
Before attempting to add a new product, try searching for it. Use FindProducts in the Shopping API to search for products in eBay catalogs. You can search by product ID or keywords. Some products may be associated with a specific product identifier type (e.g., UPC), but not others (e.g., EAN). If the search comes up with a match, the results should provide enough information for you to list your item. If there is no match, this indicates you may need to add a product to the eBay catalog.
Not all eBay categories support product creation, regardless of whether they support catalogs, or not. Use GetCategoryFeatures in the Trading API to determine whether a given category supports product creation. Specify the ProductCreationEnabled flag in the GetCategoryFeatures request to identify categories for which products may be added to the associated catalog.
The GetCategoryFeatures response indicates:
Currently, unless listing with a product is required, the capability to add products to eBay catalogs is only available to a select set of users identified by eBay. For categories that require listing with a product, any seller will be allowed to add a product. Product creation will be supported in the API and other tools.
The purpose of getProductMetadataBulk is to help you construct an addProducts call to add a product to the eBay catalog for a given category.
The following getProductMetadataBulk response (edited for size) shows metadata for the GPS category (category ID 156955 on the US site). It includes both property metadata (name-value details for individual properties) and group metadata (a set of properties that share a common characteristic).
In this sample, the group properties indicate that Title, Product Description, and ImageURL are required properties for adding a product to the eBay catalog. Also, EAN (International Article Number) and MPN (Manufacturer's Part Number) are both global unique identifiers.
<getProductMetadataBulkResponse xmlns="http://www.ebay.com/marketplace/marketplacecatalog/v1/services">
<ack>Success</ack>
<errorMessage/>
<version>1.3.0</version>
<timestamp>2011-07-01T17:02:36.877Z</timestamp>
<productMetadataResponse>
<ack>Success</ack>
<errorMessage/>
<productMetadata>
<propertyMetadata>
<propertyName>Seller Product ID</propertyName>
<dataType>STRING</dataType>
<typeSpecificInformation>
<stringTypeSpecificInformation>
<maximumCharactersAllowed>4000</maximumCharactersAllowed>
</stringTypeSpecificInformation>
</typeSpecificInformation>
<multiValued>false</multiValued>
<canonicalName>RESERVED_SELLER_SKU</canonicalName>
<propertyTags>
<name>Property Identifier</name>
<dataType>STRING</dataType>
<value>SKU</value>
</propertyTags>
</propertyMetadata>
<propertyMetadata>
<propertyName>Title</propertyName>
<dataType>STRING</dataType>
<typeSpecificInformation>
<stringTypeSpecificInformation>
<maximumCharactersAllowed>4000</maximumCharactersAllowed>
</stringTypeSpecificInformation>
</typeSpecificInformation>
<multiValued>false</multiValued>
<canonicalName>RESERVED_SOURCE_TITLE</canonicalName>
<propertyTags>
<name>Property Identifier</name>
<dataType>STRING</dataType>
<value>TITLE</value>
</propertyTags>
</propertyMetadata>
<propertyMetadata>
<propertyName>Product Description</propertyName>
<dataType>STRING</dataType>
<typeSpecificInformation>
<stringTypeSpecificInformation>
<maximumCharactersAllowed>4000</maximumCharactersAllowed>
</stringTypeSpecificInformation>
</typeSpecificInformation>
<multiValued>false</multiValued>
<canonicalName>RESERVED_PRODUCT_DESCRIPTION</canonicalName>
<propertyTags>
<name>Property Identifier</name>
<dataType>STRING</dataType>
<value>DESCRIPTION</value>
</propertyTags>
</propertyMetadata>
<propertyMetadata>
<propertyName>ImageURL</propertyName>
<dataType>MEDIA</dataType>
<typeSpecificInformation>
<mediaTypeSpecificInformation/>
</typeSpecificInformation>
<multiValued>false</multiValued>
<canonicalName>RESERVED_PRODUCT_IMAGE</canonicalName>
<propertyTags>
<name>Property Identifier</name>
<dataType>STRING</dataType>
<value>IMAGE</value>
</propertyTags>
</propertyMetadata>
<propertyMetadata>
<propertyName>EAN</propertyName>
<dataType>STRING</dataType>
<typeSpecificInformation>
<stringTypeSpecificInformation>
<maximumCharactersAllowed>4000</maximumCharactersAllowed>
</stringTypeSpecificInformation>
</typeSpecificInformation>
<multiValued>true</multiValued>
<canonicalName>UPC</canonicalName>
<propertyTags>
<name>Property Identifier</name>
<dataType>STRING</dataType>
<value>EAN</value>
</propertyTags>
</propertyMetadata>
...
<groupProperties>
<groupType>REQUIRED_PROPERTIES</groupType>
<groupName>Required Set</groupName>
<groupProperty>
<propertyName>Title</propertyName>
</groupProperty>
<groupProperty>
<propertyName>Product Description</propertyName>
</groupProperty>
<groupProperty>
<propertyName>ImageURL</propertyName>
</groupProperty>
</groupProperties>
<groupProperties>
<groupType>GUID_PROPERTIES</groupType>
<groupName>GUID Set</groupName>
<groupProperty>
<propertyName>EAN</propertyName>
</groupProperty>
<groupProperty>
<propertyName>MPN</propertyName>
</groupProperty>
</groupProperties>
</productMetadata>
<requestInformation>
<categoryId>156955</categoryId>
</requestInformation>
</productMetadataResponse>
</getProductMetadataBulkResponse>
The following addProducts request is constructed with information from the getProductMetadataBulk response. The addProducts request contains the required properties: Title, Product Description, and ImageURL. The request also specifies the EAN for the product, as this will help increase the product's visibility in searches. The addProducts request can also specify any of the optional properties returned by getProductMetadataBulk, such as the Seller Product ID, which is sometimes referred to as a SKU.
Note that ImageURL is not specified as a name-value pair (productPropertyValue), but in the media node (media.mediaIdentifier.url) instead.
| Important: The addProducts and getProductSubmissions calls require a security token (also called the Auth Token), which is specified in the X-EBAY-SOA-SECURITY-TOKEN HTTP header. The addProducts and getProductSubmissions requests cannot be submitted as a REST-style URLs via HTTP GET. For more information about header requirements, see Making a Call.
Use the User Token Tool to create a token for a single user. Log in and follow the online instructions to retrieve your token. For a tutorial on retrieving tokens for use on behalf of users of your application, see Getting Tokens. |
<?xml version="1.0" encoding="UTF-8"?>
<addProductsRequest xmlns="http://www.ebay.com/marketplace/marketplacecatalog/v1/services">
<addProductRequest>
<invocationId>0123456789</invocationId>
<categoryId>156955</categoryId>
<productPropertyValue>
<propertyName>Seller Product ID</propertyName>
<value>
<text>
<value>1122334455-01</value>
</text>
</value>
</productPropertyValue>
<productPropertyValue>
<propertyName>Title</propertyName>
<value>
<text>
<value>Garmin nuvi 255W Automotive GPS Receiver</value>
</text>
</value>
</productPropertyValue>
<productPropertyValue>
<propertyName>Product Description</propertyName>
<value>
<text>
<value>Get all the directions with great detail
and accuracy even in direct sunlight with 4.3-inch
widescreen display of the Garmin nuvi 255W GPS.
Equipped with the City Navigator NT street maps, this
Garmin automotive GPS takes you to places like
restaurants, ATMs, etc. Enter the destination with a
mere touch on the screen and this Garmin widescreen
navigator properly takes you there through turn-by-
turn voice directions. To know more about the desired
destination, the Garmin nuvi 255W has digital
elevation maps that give shaded pictures at higher
zoom levels. This Garmin automotive GPS lets you store
custom POIs like school zones and safety cameras so
that you can receive alerts while approaching POIs.
Other features of this Garmin widescreen navigator
include HotFix satellite prediction, JPEG picture
viewer, etc.</value>
</text>
</value>
</productPropertyValue>
<productPropertyValue>
<propertyName>EAN</propertyName>
<value>
<text>
<value>753759083588</value>
</text>
</value>
</productPropertyValue>
...
<media>
<mediaIdentifier>
<url>http://www.botany.com/img/plants/dictionary-plants-flowers.jpg</url>
</mediaIdentifier>
<mediaType>Image</mediaType>
</media>
</addProductRequest>
<clientBatchId>54321</clientBatchId>
</addProductsRequest>
Parts Compatibility uses structured data to associate compatible assemblies with parts listed on eBay. For example, parts compatibility enables sellers to specify accurately and comprehensively the vehicles on which a side mirror or a rim will fit. Parts compatibility improves search relevancy and frees up item titles and descriptions for more useful descriptions of the part.
| Note: Parts Compatibility is supported in select categories for eBay Motors (site ID 100, global ID EBAY-MOTOR) and eBay Germany (site ID 77, global ID EBAY-DE) in the Sandbox and Production environments. Parts Compatibility is enabled by category. Use GetCategoryFeatures (use FeatureID values: CompatibilityEnabled, MinCompatibleApplications, MaxCompatibleApplications) to retrieve information about categories that support parts compatibility. |
The easiest way to list an item with Parts Compatibility is to select a product that has compatibilies. If the part or accessory you want to list is in the eBay catalog for a category that supports compatibilities, you can use the eBay data to prefill your listings with rich structured data, including the compatible applications.
Parts Compatibilities (or compatible applications) consist of name-value pairs that describe an assembly with which a part or accessory is compatible. A compatible application for an item listed in an eBay Motors Parts & Accessories category will be name-value pairs that describe a vehicle (e.g., Make = Honda, Model = Accord, Year = 2004, etc.). The Product and Product Metadata APIs both return compatibility information. Use getProductCompatibilities in the Product API to retrieve compatibilities associated with a specific product or set of product specifications. Use the Product Metadata API to retrieve compatibility data by category.
The primary use of the compatibility information returned by the Product and Product Metadata APIs is to add or revise item listings with parts compatibility. That is, the compatibility name-value pairs can be used to construct an item compatibility list (Item.ItemCompatibilityList) for use with the AddItem family of calls in the Trading API.
Compatibility information can also be used as a filter for product searches, findProductsByCompatibility, to restrict the products in the response to only those compatible with the specified application (e.g., vehicle) in the request.
Once you have used the Product and Product Metadata API to collect compatibility information, you use the AddItem family of calls in the Trading API to list the item.
See Listing Items with Parts Compatibility in the Trading API Guide to learn more how to list an item with parts compatibility information.
The Product and Product Metadata APIs are intended to be used in conjunction with the eBay Trading API.
eBay Trading API offers authenticated access to private eBay data to enable automation and innovation in the areas of listing items, retrieving seller sales status, managing post-transaction fulfillment, and accessing private user information such as My eBay and Feedback details.
Using the Trading API, you can:
See the Products page to learn more about eBay Web Services products and upcoming product releases and feature enhancements.
The Product and Product Metadata APIs are simple and easy to use. This section outlines the fundamentals of how to use them.
All that is required to use the Product or Proudct Metadata APIs is an AppID. If you already have an AppID for use with another eBay API, such as the Shopping or Merchandising APIs, it will work with the Product and Proudct Metadata APIs, as well. You must specify your AppID in the X-EBAY-SOA-SECURITY-APPNAME HTTP header (or SECURITY-APPNAME URL parameter) of every request.
If you have not already, join the eBay Developers Program and get your Access Keys.
Joining is free and you get 5,000 API calls a day just for joining! When you generate your application keys from your My Account page. You will need to generate separate keys for use with the Sandbox and Production environments.
Please refer to the API Call Limits page on the eBay Developers Program site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.
The Product and Proudct Metadata APIs are provided to support Product Creation and Parts Compatibility only. Product Creation is supported in select category for the eBay US (global ID EBAY-US) and eBay UK (global ID EBAY-GB) sites only. Parts Compatibility is supported in select categories for the eBay Motors (site ID 100, global ID EBAY-MOTOR) and eBay Germany (site ID 77, global ID EBAY-DE) sites only.
Use GetCategoryFeatures in the Trading API to determine which categories support Product Creation (feature ID: ProductCreationEnabled) and Parts Compatibility (feature ID: CompatibilityEnabled).
When submitting your Product or Product Metadata requests, you must set the global ID in the X-EBAY-SOA-GLOBAL-ID HTTP header (or GLOBAL-ID URL parameter) of every request to correspond to one of the supported sites, such as eBay Motors (global ID: EBAY-MOTOR) for Parts Compatibility. Most calls require you to specify the category ID in the request. Use only categories that support the feature you are using.
The Product and Product Metadata APIs work in the Sandbox for select categories. Use GetCategoryFeatures in the Trading API to determine which categories support Product Creation (feature ID: ProductCreationEnabled) and Parts Compatibility (feature ID: CompatibilityEnabled).
For more information about testing, refer to Testing Overview in the Making an API Call document.
Refer to the Call Reference for a list of calls in the Finding API. The Call Reference includes the following information:
You can get more information about the eBay Finding API at these locations:
Share tips or code samples related to this call or topic. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.
© 2010–2011 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.