{
"openapi": "3.0.0",
"info": {
"title": "Metadata API",
"description": "The Metadata API has operations that retrieve configuration details pertaining to the different eBay marketplaces. In addition to marketplace information, the API also has operations that get information that helps sellers list items on eBay.",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
"url": "https://go.developer.ebay.com/api-license-agreement"
},
"version": "v1.7.1"
},
"servers": [
{
"url": "https://api.ebay.com{basePath}",
"description": "Production",
"variables": {
"basePath": {
"default": "/sell/metadata/v1"
}
}
}
],
"paths": {
"/marketplace/{marketplace_id}/get_automotive_parts_compatibility_policies": {
"get": {
"tags": [
"marketplace"
],
"description": "This method returns the eBay policies that define how to list automotive-parts-compatibility items in the categories of a specific marketplace.
By default, this method returns the entire category tree for the specified marketplace. You can limit the size of the result set by using the filter query parameter to specify only the category IDs you want to review.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip
.",
"operationId": "getAutomotivePartsCompatibilityPolicies",
"parameters": [
{
"name": "filter",
"in": "query",
"description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. Use the Taxonomy API to retrieve category ID values.
When you specify a categoryId value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below the at parent node.
The parameter takes a list of categoryId values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character ('|'). If you specify more than 50 categoryId
values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned.
Example: filter=categoryIds:{100|101|102}
Note that you must URL-encode the parameter list, which results in the following filter for the above example:
filter=categoryIds%3A%7B100%7C101%7C102%7D
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "marketplace_id",
"in": "path",
"description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.
Note: Only the following eBay marketplaces support automotive parts compatibility:
",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Encoding",
"in": "header",
"description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip
.
For more information, refer to HTTP request headers.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutomotivePartsCompatibilityPolicyResponse"
}
}
},
"x-response-codes": {
"errors": {
"46002": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
},
"46003": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "The specified categoryId was not found for the marketplace."
},
"46004": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "Only 50 Category IDs specified in the filter are considered."
}
}
}
},
"204": {
"description": "No content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"46001": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "The specified marketplace ID was not found."
}
}
}
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"46000": {
"domain": "API_METADATA",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/marketplace/{marketplace_id}/get_extended_producer_responsibility_policies": {
"get": {
"tags": [
"marketplace"
],
"description": "This method returns the Extended Producer Responsibility policies for one, multiple, or all eBay categories in an eBay marketplace.
The identifier of the eBay marketplace is passed in as a path parameter, and unless one or more eBay category IDs are passed in through the filter query parameter, this method will return metadata on every applicable category for the specified marketplace.
Note: Currently, the Extended Producer Responsibility policies are only applicable to a limited number of categories.
Note: Extended Producer Responsibility IDs are no longer set at the listing level so category-level metadata is no longer returned. Instead, sellers will provide/manage these IDs at the account level by going to Account Settings.
Tip: This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the Accept-Encoding request header and setting the value to gzip
.",
"operationId": "getExtendedProducerResponsibilityPolicies",
"parameters": [
{
"name": "filter",
"in": "query",
"description": "A query parameter that can be used to limit the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree that should be returned.
When a categoryId value is specified, the returned category tree includes the policies for that parent node, as well as the policies for any child nodes below that parent node.
Pass in the categoryId values using a URL-encoded, pipe-separated ('|') list. For example:filter=categoryIds%3A%7B100%7C101%7C102%7D
Maximum: 50",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "marketplace_id",
"in": "path",
"description": "This path parameter specifies the eBay marketplace for which policy information shall be retrieved.
See HTTP Request Headers for a list of supported eBay marketplace ID values.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Encoding",
"in": "header",
"description": "This header indicates the compression-encoding algorithms the client accepts for the response. This value should be set to gzip
.
For more information, refer to HTTP request headers.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendedProducerResponsibilityPolicyResponse"
}
}
},
"x-response-codes": {
"errors": {
"46002": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}."
},
"46003": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "The specified categoryId was not found for the marketplace."
},
"46004": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "Only 50 Category IDs specified in the filter are considered."
}
}
}
},
"204": {
"description": "No content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"46001": {
"domain": "API_METADATA",
"category": "REQUEST",
"description": "The specified marketplace ID was not found."
}
}
}
},
"404": {
"description": "Not found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"46000": {
"domain": "API_METADATA",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process.Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/marketplace/{marketplace_id}/get_hazardous_materials_labels": {
"get": {
"tags": [
"marketplace"
],
"description": "This method returns hazardous materials label information for the specified eBay marketplace. The information includes IDs, descriptions, and URLs (as applicable) for the available signal words, statements, and pictograms. The returned statements are localized for the default langauge of the marketplace. If a marketplace does not support hazardous materials label information, an error is returned.
This information is used by the seller to add hazardous materials label related information to their listings (see Specifying hazardous material related information).
", "operationId": "getHazardousMaterialsLabels", "parameters": [ { "name": "marketplace_id", "in": "path", "description": "This path parameter specifies the eBay marketplace for which hazardous materials label information shall be retrieved.gzip
.",
"operationId": "getItemConditionPolicies",
"parameters": [
{
"name": "filter",
"in": "query",
"description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. categoryId
values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. filter=categoryIds:{100|101|102}
filter=categoryIds%3A%7B100%7C101%7C102%7D
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "marketplace_id",
"in": "path",
"description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.gzip
. gzip
.",
"operationId": "getListingStructurePolicies",
"parameters": [
{
"name": "filter",
"in": "query",
"description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. categoryId
values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. filter=categoryIds:{100|101|102}
filter=categoryIds%3A%7B100%7C101%7C102%7D
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "marketplace_id",
"in": "path",
"description": "This path parameter specifies the eBay marketplace for which policy information is retrieved. gzip
. gzip
.",
"operationId": "getNegotiatedPricePolicies",
"parameters": [
{
"name": "filter",
"in": "query",
"description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. categoryId
values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. filter=categoryIds:{100|101|102}
filter=categoryIds%3A%7B100%7C101%7C102%7D
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "marketplace_id",
"in": "path",
"description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.gzip
. gzip
.",
"operationId": "getReturnPolicies",
"parameters": [
{
"name": "filter",
"in": "query",
"description": "This query parameter limits the response by returning policy information for only the selected sections of the category tree. Supply categoryId values for the sections of the tree you want returned. categoryId
values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. filter=categoryIds:{100|101|102}
filter=categoryIds%3A%7B100%7C101%7C102%7D
",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "marketplace_id",
"in": "path",
"description": "This path parameter specifies the eBay marketplace for which policy information is retrieved.gzip
. Important! In the US, eBay now calculates, collects, and remits sales tax to the proper taxing authorities 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:
US
CA
ASSEMBLY
or by SPECIFICATION
. For implementation help, refer to eBay API documentation"
},
"compatibleVehicleTypes": {
"type": "array",
"description": "Indicates the compatibility classification of the part based on high-level vehicle types.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"maxNumberOfCompatibleVehicles": {
"type": "integer",
"description": "Specifies the maximum number of compatible vehicle-applications allowed per item.",
"format": "int32"
}
}
},
"AutomotivePartsCompatibilityPolicyResponse": {
"type": "object",
"properties": {
"automotivePartsCompatibilityPolicies": {
"type": "array",
"description": "A list of category IDs and the automotive-parts-compatibility policies for each of the listed categories.",
"items": {
"$ref": "#/components/schemas/AutomotivePartsCompatibilityPolicy"
}
},
"warnings": {
"type": "array",
"description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:Application
: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business
: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request
: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.inputRefId
.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "This optional complex field type contains a list of one or more context-specific ErrorParameter
objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter
object consists of two fields, a name
and a value
.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain."
}
},
"description": "A container that defines the elements of error and warning messages."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the entity that threw the error."
},
"value": {
"type": "string",
"description": "A description of the error."
}
},
"description": "Container for a error parameter."
},
"ExtendedProducerResponsibility": {
"type": "object",
"properties": {
"enabledForVariations": {
"type": "boolean",
"description": "An indication of whether the attribute can be enabled for listing variations.true
, the attribute may be specified at the variation level."
},
"name": {
"type": "string",
"description": "The name of the attribute included in the policy. For implementation help, refer to eBay API documentation"
},
"usage": {
"type": "string",
"description": "The usage guidelines for the attribute, in the specified marketplace. For implementation help, refer to eBay API documentation"
}
},
"description": "A type that defines the attributes of an Extended Producer Responsibility policy."
},
"ExtendedProducerResponsibilityPolicy": {
"type": "object",
"properties": {
"categoryId": {
"type": "string",
"description": "The unique identifier for the category under which the policy applies."
},
"categoryTreeId": {
"type": "string",
"description": "The unique identifier for the category tree under which the policy applies."
},
"supportedAttributes": {
"type": "array",
"description": "The details regarding the attributes included in the policy, such as their usage guidelines and whether they can be specified at the listing variation level.",
"items": {
"$ref": "#/components/schemas/ExtendedProducerResponsibility"
}
}
},
"description": "A type that defines the Extended Producer Responsibility policy."
},
"ExtendedProducerResponsibilityPolicyResponse": {
"type": "object",
"properties": {
"extendedProducerResponsibilities": {
"type": "array",
"description": "An array of response fields detailing the Extended Producer Responsibility policies supported for the specified marketplace.",
"items": {
"$ref": "#/components/schemas/ExtendedProducerResponsibilityPolicy"
}
},
"warnings": {
"type": "array",
"description": "A collection of warnings generated for the request.",
"items": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "A type that defines the response fields for the getExtendedProducerResponsibilityPolicies method."
},
"HazardStatement": {
"type": "object",
"properties": {
"statementId": {
"type": "string",
"description": "The identifier of the statement. For sample values, see Hazard statement sample values."
},
"statementDescription": {
"type": "string",
"description": "The description of the statement localized to the default language of the marketplace. For sample values, see Hazard statement sample values."
}
},
"description": "A type that describes hazard statements for hazardous materials labels"
},
"HazardousMaterialDetailsResponse": {
"type": "object",
"properties": {
"signalWords": {
"type": "array",
"description": "This array contains available hazardous materials signal words for the specified marketplace.",
"items": {
"$ref": "#/components/schemas/SignalWord"
}
},
"statements": {
"type": "array",
"description": "This array contains available hazardous materials hazard statements for the specified marketplace.",
"items": {
"$ref": "#/components/schemas/HazardStatement"
}
},
"pictograms": {
"type": "array",
"description": "This array contains of available hazardous materials hazard pictograms for the specified marketplace.",
"items": {
"$ref": "#/components/schemas/Pictogram"
}
}
},
"description": "A type that defines the response fields for the getHazardousMaterialsLabels method."
},
"ItemCondition": {
"type": "object",
"properties": {
"conditionDescription": {
"type": "string",
"description": "The human-readable label for the condition (e.g., \"New\"). This value is typically localized for each site. 1000
could be called \"New: with Tags\" in one category and \"Brand New\" in another. For details on condition IDs and descriptions, see Item condition ID and name values."
},
"conditionDescriptors": {
"type": "array",
"description": "This array contains the possible condition descriptors and condition descriptor values applicable for the specified category. It also returns usage requirements, maximum length, cardinality, and help text.Card Condition
is Select ungraded condition
."
},
"conditionDescriptorId": {
"type": "string",
"description": "The unique identification number of a condition descriptor associated with with a conditionDescriptorName. 40001
is the ID for Card Condition
.Card Condition
is the condition descriptor name for ID 40001
"
},
"conditionDescriptorValues": {
"type": "array",
"description": "This array shows the possible values that map to the corresponding conditionDescriptorName values. Constraint information and help text are also shown for each value. 40001
is ID for the condition descriptor card condition
. The ID 400012
is the ID for the Very Good
card condition value.",
"items": {
"$ref": "#/components/schemas/ItemConditionDescriptorValue"
}
}
},
"description": "This type is used to display the possible condition descriptors and condition values applicable for a specified category. It also returns usage requirements, maximum length, cardinality, and help text."
},
"ItemConditionDescriptorConstraint": {
"type": "object",
"properties": {
"applicableToConditionDescriptorIds": {
"type": "array",
"description": "This array is returned if the corresponding condition descriptor requires that one or more other associated condition descriptors must also be specified in a listing. The condition descriptor IDs for the associated condition descriptors are returned here.Grade
and Grader
condition descriptors must always be specified together in a listing for Graded cards.",
"items": {
"type": "string"
}
},
"cardinality": {
"type": "string",
"description": "The value returned in this field indicates whether a condition descriptor can have a single value or multiple values. For implementation help, refer to eBay API documentation"
},
"defaultConditionDescriptorValueId": {
"type": "string",
"description": "The default condition descriptor value that will be set if there are multiple values."
},
"maxLength": {
"type": "integer",
"description": "The maximum characters allowed for a condition descriptor. This field is only returned/applicable for condition descriptors that allow free text for condition descriptor values. ",
"format": "int32"
},
"mode": {
"type": "string",
"description": "The value returned in this field indicates whether the supported values for a condition descriptor are predefined or if the seller manually specified the value.FREE_TEXT
is currently only applicable to the Certification Number condition descriptor. For implementation help, refer to eBay API documentation"
},
"usage": {
"type": "string",
"description": "This value indicates whether or not the condition descriptor is required for the item condition. Currently, this field is only returned if the condition descriptor is required for the item condition. For implementation help, refer to eBay API documentation"
}
},
"description": "This type specifies the constraints on a condition descriptor, such as the maximum length, default condition descriptor value ID, cardinality, mode, usage, and applicable descriptor IDs."
},
"ItemConditionDescriptorValue": {
"type": "object",
"properties": {
"conditionDescriptorValueAdditionalHelpText": {
"type": "array",
"description": "Additional information about the the condition of the item that is not included in the conditionDescriptorValueHelpText field.",
"items": {
"type": "string"
}
},
"conditionDescriptorValueConstraints": {
"type": "array",
"description": "The constraints on a condition descriptor value, such as which descriptor value IDs and Descriptor ID it is associated with.",
"items": {
"$ref": "#/components/schemas/ItemConditionDescriptorValueConstraint"
}
},
"conditionDescriptorValueHelpText": {
"type": "string",
"description": "A detailed description of the condition descriptor value. "
},
"conditionDescriptorValueId": {
"type": "string",
"description": "The unique identification number of a condition descriptor value associated with the conditionDescriptorValueName."
},
"conditionDescriptorValueName": {
"type": "string",
"description": "The human-readable label for the condition descriptor value associated with the conditionDescriptorValueID."
}
},
"description": "This type displays the possible values for the corresponding condition descriptor, along with help text and constraint information."
},
"ItemConditionDescriptorValueConstraint": {
"type": "object",
"properties": {
"applicableToConditionDescriptorId": {
"type": "string",
"description": "This string is returned if the corresponding condition descriptor value requires an associated condition descriptor that must also be specified in a listing. The condition descriptor ID for the associated condition descriptors is returned here."
},
"applicableToConditionDescriptorValueIds": {
"type": "array",
"description": "This array is returned if the corresponding condition descriptor value is required for one or more associated condition descriptor values that must also be specified in a listing. The condition descriptor values IDs for the associated condition descriptor values are returned here.",
"items": {
"type": "string"
}
}
},
"description": "This type shows the constraints on a condition descriptor value, such as any associated condition descriptor ID and condition descriptor value IDs required for a listing."
},
"ItemConditionPolicy": {
"type": "object",
"properties": {
"categoryId": {
"type": "string",
"description": "The category ID to which the item-condition policy applies."
},
"categoryTreeId": {
"type": "string",
"description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree. true
, you must specify an item condition for the associated category."
},
"itemConditions": {
"type": "array",
"description": "The item-condition values allowed in the category.true
, the category does support item variations."
}
}
},
"ListingStructurePolicyResponse": {
"type": "object",
"properties": {
"listingStructurePolicies": {
"type": "array",
"description": "Returns a list of category IDs plus a flag indicating whether or not each listed category supports item variations.",
"items": {
"$ref": "#/components/schemas/ListingStructurePolicy"
}
},
"warnings": {
"type": "array",
"description": "A list of the warnings that were generated as a result of the request. This field is not returned if no warnings were generated by the request.",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"NegotiatedPricePolicy": {
"type": "object",
"properties": {
"bestOfferAutoAcceptEnabled": {
"type": "boolean",
"description": "This flag denotes whether or not the category supports the setting of a price at which best offers are automatically accepted. If set to true
, the category does support the setting of an automatic price for best-offers."
},
"bestOfferAutoDeclineEnabled": {
"type": "boolean",
"description": "This flag denotes whether or not the category supports the setting of an auto-decline price for best offers. If set to true
, the category does support the setting of an automatic-decline price for best-offers."
},
"bestOfferCounterEnabled": {
"type": "boolean",
"description": "This flag denotes whether or not the category supports the setting for an automatic counter-offer on best offers. If set to true
, the category does support the setting of an automatic counter-offer price for best-offers."
},
"categoryId": {
"type": "string",
"description": "The category ID to which the negotiated-price policies apply."
},
"categoryTreeId": {
"type": "string",
"description": "A value that indicates the root node of the category tree used for the response set. Each marketplace is based on a category tree whose root node is indicated by this unique category ID value. All category policy information returned by this call pertains to the categories included below this root node of the tree. true
, this flag indicates that you must specify a return policy for items listed in the associated category. false
) is a valid return policy."
}
}
},
"ReturnPolicyDetails": {
"type": "object",
"properties": {
"policyDescriptionEnabled": {
"type": "boolean",
"description": "If set to true
, this flag indicates you can supply a detailed return policy description within your return policy (for example, by populating the returnInstructions field in the Account API's createReturnPolicy). User-supplied return policy details are allowed only in the DE, ES, FR, and IT marketplaces."
},
"refundMethods": {
"type": "array",
"description": "A list of refund methods allowed for the associated category.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"returnMethods": {
"type": "array",
"description": "A list of return methods allowed for the associated category.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"returnPeriods": {
"type": "array",
"description": "A list of return periods allowed for the associated category. Days_30
).",
"items": {
"$ref": "#/components/schemas/TimeDuration"
}
},
"returnsAcceptanceEnabled": {
"type": "boolean",
"description": "If set to true
, this flag indicates the seller can configure how they handle domestic returns."
},
"returnShippingCostPayers": {
"type": "array",
"description": "A list of allowed values for who pays for the return shipping cost. Important! When countryCode
is set to US
, IDs for all 50 states, Washington, DC, and all US territories will be returned. However, the only salesTaxJurisdictionId
values currently supported are:
AS
(American Samoa)GU
(GuamMP
Northern Mariana IslandsPW (Palau)
VI
(US Virgin Islands)