The Metadata API lets you retrieve metadata on eBay category policies, information on sales tax jurisdictions, and available hazardous material related label information.
Category policies are the eBay policies and guidelines for how you must list certain items in specific categories across the different eBay marketplaces. For example, if you are listing items with variations, you'll want to know which categories support multiple-variation listings. Another example is that you may want to know which item conditions are supported for different eBay categories. See Retrieve the eBay listing policies for an eBay marketplace and category ID for more information.
Several countries have sales tax jurisdictions where the tax rates across the different jurisdictions may vary. You can use the Metadata API to retrieve the lists of tax jurisdictions which you can then use to set up sales tax tables. See Retrieve sales tax jurisdictions for more information.
Sellers have the ability to add hazardous material related label information to their listings. See Retrieve hazardous material labels information for selling flows for more information.
Technical overview
The Metadata API contains methods in the following resources:
- marketplace
-
compatibilities
- country
The methods in these resources let you retrieve configuration details that pertain to the different eBay marketplaces, get information about the areas into which you sell, and retrieve parts compatibility information.
Business use cases
The Metadata API supports the use cases outlined below.
Retrieve the eBay listing policy metadata for an eBay marketplace and category ID
Each eBay marketplace has policies that govern how you can list items in different eBay categories. The marketplace resource contains several GET methods that let you retrieve the listing policy metadata of leaf categories for specific marketplaces:
- Automotive parts compatibility items policy metadata (getAutomotivePartsCompatibilityPolicies)
- Extended Producer Responsibilities policy metadata (getExtendedProducerResponsibilityPolicies)
- Item condition policy metadata (getItemConditionPolicies)
- Retrieves categories that support multiple-variation listings (getListingStructurePolicies)
- Retrieves categories that support Best Offer and related features (getNegotiatedPricePolicies)
- Retrieves domestic and international item return policy metadata (getReturnPolicies)
- Metadata on listing categories that support regulatory policies (getRegulatoryPolicies)
- Category policy metadata (getCategoryPolicies)
- Classified ads policy metadata (getClassifiedAdPolicies)
- Listing types policy metadata (getListingTypePolicies)
- Motors policy metadata (getMotorsListingPolicies)
- Shipping policy metadata (getShippingPolicies)
- International site visibility policy metadata (getSiteVisibilityPolicies)
Important! The listing policies are specific to an eBay marketplace and category ID. Be sure to use the policies that match the categories into which you list items.
Retrieve sales tax jurisdictions
Both Canada (CA) and the United States (US) define different sales tax jurisdictions for the different regions in their countries. Sellers can ease the process of calculating the final value of the items they sell by setting up tax tables for the tax jurisdictions where they must charge sales tax.
Use the getSalesTaxJurisdictions method to retrieve details on a county's different sales tax jurisdictions, then use the methods in the sales_tax resource of the Account API to set up and manage your sales tax tables.
Note: Sales-tax tables are only available for the US (EBAY_US) and Canada (EBAY_CA) marketplaces.
US sales-tax tables
eBay now calculates, collects, and remits sales tax on behalf of sellers for items shipped to customers in all 50 states and Washington, DC. Sellers can no longer specify sales-tax rates for these jurisdictions using a tax table.
However, sellers may continue to use a sales-tax table to set rates for the following US territories: American Samoa (AS), Guam (GU), Northern Mariana Islands (MP), Palau (PW), and US Virgin Islands (VI).
Canadian sales-tax tables
Sellers can use sales-tax tables to set and configure rates for any or all Canadian provinces.
Retrieve hazardous material labels information for selling flows
Hazardous material label information can be retrieved and used by sellers to add hazardous material related information to their listings (see Specifying hazardous material related information).
Use the getHazardousMaterialsLabels method to retrieve details of available hazardous materials label information for the specified eBay marketplace, then add the information to your listing through the Regulatory container of Add/Revise/Relist family of calls in the Trading API (for example, AddItem).
Retrieve product safety label information for selling flows
Use the getProductSafetyLabels method to retrieve details of available product safety label information for the specified eBay marketplace. Add the information to your listing through either of the following APIs:
-
Inventory API: Use the productSafety container of the createOffer or updateOffer methods (for example, use the regulatory.productSafety container in createOffer)
-
Trading API: Use the Item.Regulatory.ProductSafety container of Add/Revise/Relist family of calls (for example, AddItem)
Retrieve the default currency
Use the getCurrencies method to obtain the default currency supported by the eBay system for the specified site in the request.
Retrieve parts compatibility information
The compatibilities resource contains several methods that return parts compatibility information for specific categories:
-
Find compatible applications for a part based on provided specifications (getCompatibilitiesBySpecification)
-
Retrieve product compatibility property names for the specified category (getCompatibilityPropertyNames)
-
Retrieve product compatibility property values associated with a property name (getCompatibilityPropertyValues and getMultiCompatibilityPropertyValues)
-
Retrieve all available item compatibility details for a specified product (getProductCompatibilities)
Metadata API requirements and restrictions
The getSalesTaxJurisdictions method returns data for only the countries that designate different sales tax jurisdictions. These countries are currently limited to Canada (CA) and the United States (US).
The methods in the compatibility resource only return data for the following eBay marketplaces:
|
Marketplace ID |
Marketplace Locale Support |
Marketplace Site |
|---|---|---|
EBAY_AT (Austria) |
de-AT
|
https://www.ebay.at |
EBAY_AU (Australia) |
en-AU
|
https://www.ebay.com.au/ |
EBAY_CA (Canada) |
en-CA
|
https://www.ebay.ca
https://www.cafr.ebay.ca/ |
EBAY_CH (Switzerland) |
de-CH
|
https://www.ebay.ch |
EBAY_DE (Germany) |
de-DE
|
https://www.ebay.de |
EBAY_ES (Spain) |
es-ES
|
https://www.ebay.es |
EBAY_FR (France) |
fr-FR
|
https://www.ebay.fr |
EBAY_GB (Great Britain) |
en-GB
|
https://www.ebay.co.uk |
EBAY_IE (Ireland) |
en-IE
|
https://www.ebay.ie |
EBAY_IT (Italy) |
it-IT
|
https://www.ebay.it |
EBAY_MOTORS_US (United States) |
en-US
|
https://www.ebay.com |
The methods in the marketplace resource return data for only the eBay marketplaces in the following list:
|
Marketplace ID |
Marketplace Locale Support |
Marketplace Site |
|---|---|---|
EBAY_AT (Austria) |
de-AT
|
https://www.ebay.at |
EBAY_AU (Australia) |
en-AU
|
https://www.ebay.com.au/ |
EBAY_BE (Belgium) |
fr-BE
|
https://www.befr.ebay.be/
https://www.benl.ebay.be/ |
EBAY_CA (Canada) |
en-CA
|
https://www.ebay.ca
https://www.cafr.ebay.ca/ |
EBAY_CH (Switzerland) |
de-CH
|
https://www.ebay.ch |
EBAY_DE (Germany) |
de-DE
|
https://www.ebay.de |
EBAY_ES (Spain) |
es-ES
|
https://www.ebay.es |
EBAY_FR (France) |
fr-FR
|
https://www.ebay.fr |
EBAY_GB (Great Britain) |
en-GB
|
https://www.ebay.co.uk |
EBAY_HK (Hong Kong) |
zh-HK
|
https://www.ebay.com.hk |
EBAY_IE (Ireland) |
en-IE
|
https://www.ebay.ie |
EBAY_IT (Italy) |
it-IT
|
https://www.ebay.it |
EBAY_MOTORS_US (eBay Motors US) |
en-US
|
https://www.ebay.com/motors |
EBAY_MY (Malaysia) |
en-US
|
https://www.ebay.com/my |
EBAY_NL (Netherlands) |
nl-NL
|
https://www.ebay.nl |
EBAY_PH (Philippines) |
en-PH
|
https://www.ebay.ph |
EBAY_PL (Poland) |
pl-PL
|
https://www.ebay.pl |
EBAY_RU (Russia) |
ru-RU
|
https://www.ebay.com/sch/Russia |
EBAY_SG (Singapore) |
en-US
|
https://www.ebay.com/sg |
EBAY_US (United States) |
en-US
|
https://www.ebay.com |
Note: The Accept-Language request header must be passed in along with the marketplace to specify the preferred language for marketplaces that support multiple locales. See HTTP request headers for more information about request headers, or see Marketplace ID values for more information about marketplace support.