eBay Metadata API
The eBay Metadata API exposes marketplace policies and configuration metadata that govern selling activity across countries and categories.
OpenAPI Specification
openapi: 3.0.0
info:
title: eBay 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://developer.ebay.com/join/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 the specified marketplace. <br><br>By default, this method returns all categories that support parts compatibility. You can limit the size of the result set by using the <b>filter</b> query parameter to specify only the category IDs you want to review.<br><br><span class="tablenote"><b>Note: </b>To return policy information for the eBay US marketplace, specify <code>EBAY_MOTORS_US</code> as the path parameter for <b>marketplace_id</b>.</span><br><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the <b>Accept-Encoding</b> request header and setting the value to <code>gzip</code>.</span><br>If you specify a valid marketplace ID but that marketplace does not contain policy information, or if you filter out all results, a <b>204 No content</b> status code is returned with an empty response body.'
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 <b>categoryId</b> values for the sections of the tree you want returned. Use the <a href="/api-docs/commerce/taxonomy/overview.html" target="_blank ">Taxonomy API</a> to retrieve category ID values.<br><br>When you specify a <b>categoryId</b> value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below the at parent node. <br><br>The parameter takes a list of <b>categoryId</b> values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character (''|''). If you specify more than 50 <code>categoryId</code> values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. <br><br><b>Example:</b> <code>filter=categoryIds:{183521|183523|183524}</code> <br><br><span class="tablenote"><b>Note: </b>URL-encoding of the parameter list is no longer required.</span>'
required: false
schema:
type: string
- name: marketplace_id
in: path
description: 'This path parameter specifies the eBay marketplace for which policy information is retrieved. <br><br><span class="tablenote"><b>Note: </b>Only the following eBay marketplaces support automotive parts compatibility: <ul> <li>EBAY_MOTORS_US</li> <li>EBAY_AU</li> <li>EBAY_CA</li> <li>EBAY_DE</li> <li>EBAY_ES</li> <li>EBAY_FR</li> <li>EBAY_GB</li> <li>EBAY_IT</li></ul></span>'
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 <code>gzip</code>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
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.<br><br>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.<br><br><span class="tablenote"><span style="color:#004680"><strong>Note:</strong></span> Currently, the Extended Producer Responsibility policies are only applicable to a limited number of categories.</span><br><span class="tablenote"><span style="color:#004680"><strong>Note: </strong></span>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 <a href="https://accountsettings.ebay.fr/epr-fr " target="_blank">Account Settings</a>.</span><br><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the <b>Accept-Encoding</b> request header and setting the value to <code>gzip</code>.</span>'
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 <b>categoryId</b> values for the sections of the tree that should be returned.<br><br>When a <b>categoryId</b> 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.<br><br>Pass in the <b>categoryId</b> values using a URL-encoded, pipe-separated ('|') list. For example:<br><br><code>filter=categoryIds%3A%7B100%7C101%7C102%7D</code><br><br><b>Maximum:</b> 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.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> 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 <code>gzip</code>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
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.<p>This information is used by the seller to add hazardous materials label related information to their listings (see <a href='/api-docs/sell/static/metadata/feature-regulatorhazmatcontainer.html'>Specifying hazardous material related information</a>).</p>
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.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> for a list of supported eBay marketplace ID values.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/HazardousMaterialDetailsResponse'
'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_item_condition_policies:
get:
tags:
- Marketplace
description: 'This method returns item condition metadata on one, multiple, or all eBay categories on an eBay marketplace. This metadata consists of the different item conditions (with IDs) that an eBay category supports, and a boolean to indicate if an eBay category requires an item condition. <br><br>If applicable, this metadata also shows the different condition descriptors (with IDs) that an eBay category supports.<br><br><span class="tablenote"><b>Note:</b> Currently, condition grading is only applicable to the following trading card categories: <ul><li>Non-Sport Trading Card Singles</li><li>CCG Individual Cards</li><li>Sports Trading Cards Singles</li></ul></span><br>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 <b>filter</b> query parameter, this method will return metadata on every single category for the specified marketplace. If you only want to view item condition metadata for one eBay category or a select group of eBay categories, you can pass in up to 50 eBay category ID through the <b>filter</b> query parameter.<br><br><span class="tablenote"><span style="color:#FF0000"><strong>Important:</strong></span> <b>Certified - Refurbished</b>-eligible sellers, and sellers who are eligible to list with the new values (EXCELLENT_REFURBISHED, VERY_GOOD_REFURBISHED, and GOOD_REFURBISHED) must use an OAuth token created with the <a href="/api-docs/static/oauth-authorization-code-grant.html" target="_blank">authorization code grant flow</a> and <b>https://api.ebay.com/oauth/api_scope/sell.inventory</b> scope in order to retrieve the refurbished conditions for the relevant categories.<br/><br/>See the <a href="/api-docs/sell/static/metadata/condition-id-values.html#Category " target="_blank">eBay Refurbished Program - Category and marketplace support</a> topic for the categories and marketplaces that support these refurbished conditions<br/><br/>These restricted item conditions will not be returned if an OAuth token created with the <a href="/api-docs/static/oauth-client-credentials-grant.html" target="_blank">client credentials grant flow</a> and <b>https://api.ebay.com/oauth/api_scope</b> scope is used, or if any seller is not eligible to list with that item condition. <br/><br/> See the <a href="/api-docs/static/oauth-scopes.html" target="_blank">Specifying OAuth scopes</a> topic for more information about specifying scopes.</span><br><br><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the <b>Accept-Encoding</b> request header and setting the value to <code>gzip</code>.</span>'
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 <b>categoryId</b> values for the sections of the tree you want returned. <br><br>When you specify a <b>categoryId</b> value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node. <br><br>The parameter takes a list of <b>categoryId</b> values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character (''|''). If you specify more than 50 <code>categoryId</code> values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. <br><br><b>Example:</b> <code>filter=categoryIds:{100|101|102}</code> <br><br>Note that you must URL-encode the parameter list, which results in the following filter for the above example: <br><br> <code>filter=categoryIds%3A%7B100%7C101%7C102%7D</code>'
required: false
schema:
type: string
- name: marketplace_id
in: path
description: This path parameter specifies the eBay marketplace for which policy information is retrieved.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> 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 <code>gzip</code>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ItemConditionPolicyResponse'
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
- https://api.ebay.com/oauth/api_scope/sell.inventory
/marketplace/{marketplace_id}/get_listing_structure_policies:
get:
tags:
- Marketplace
description: This method returns the eBay policies that define the allowed listing structures for the categories of a specific marketplace. The listing-structure policies currently pertain to whether or not you can list items with variations. <br><br>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 <b>filter</b> query parameter to specify only the category IDs you want to review.<br><br><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the <b>Accept-Encoding</b> request header and setting the value to <code>gzip</code>.</span>
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 <b>categoryId</b> values for the sections of the tree you want returned. <br><br>When you specify a <b>categoryId</b> value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node. <br><br>The parameter takes a list of <b>categoryId</b> values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character (''|''). If you specify more than 50 <code>categoryId</code> values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. <br><br><b>Example:</b> <code>filter=categoryIds:{100|101|102}</code> <br><br>Note that you must URL-encode the parameter list, which results in the following filter for the above example: <br><br> <code>filter=categoryIds%3A%7B100%7C101%7C102%7D</code>'
required: false
schema:
type: string
- name: marketplace_id
in: path
description: This path parameter specifies the eBay marketplace for which policy information is retrieved. <br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> 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 <code>gzip</code>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ListingStructurePolicyResponse'
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_negotiated_price_policies:
get:
tags:
- Marketplace
description: This method returns the eBay policies that define the supported negotiated price features (like "best offer") for the categories of a specific marketplace. <br><br>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 <b>filter</b> query parameter to specify only the category IDs you want to review.<br><br><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the <b>Accept-Encoding</b> request header and setting the value to <code>gzip</code>.</span>
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 <b>categoryId</b> values for the sections of the tree you want returned. <br><br>When you specify a <b>categoryId</b> value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node. <br><br>The parameter takes a list of <b>categoryId</b> values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character (''|''). If you specify more than 50 <code>categoryId</code> values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. <br><br><b>Example:</b> <code>filter=categoryIds:{100|101|102}</code> <br><br>Note that you must URL-encode the parameter list, which results in the following filter for the above example: <br><br> <code>filter=categoryIds%3A%7B100%7C101%7C102%7D</code>'
required: false
schema:
type: string
- name: marketplace_id
in: path
description: This path parameter specifies the eBay marketplace for which policy information is retrieved.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> 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 <code>gzip</code>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/NegotiatedPricePolicyResponse'
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_return_policies:
get:
tags:
- Marketplace
description: This method returns the eBay policies that define whether or not you must include a return policy for the items you list in the categories of a specific marketplace, plus the guidelines for creating domestic and international return policies in the different eBay categories. <br><br>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 <b>filter</b> query parameter to specify only the category IDs you want to review.<br><br><span class="tablenote"><span style="color:#478415"><strong>Tip:</strong></span> This method can potentially return a very large response payload. eBay recommends that the response payload be compressed by passing in the <b>Accept-Encoding</b> request header and setting the value to <code>gzip</code>.</span>
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 <b>categoryId</b> values for the sections of the tree you want returned. <br><br>When you specify a <b>categoryId</b> value, the returned category tree includes the policies for that parent node, plus the policies for any leaf nodes below that parent node. <br><br>The parameter takes a list of <b>categoryId</b> values and you can specify up to 50 separate category IDs. Separate multiple values with a pipe character (''|''). If you specify more than 50 <code>categoryId</code> values, eBay returns the policies for the first 50 IDs and a warning that not all categories were returned. <br><br><b>Example:</b> <code>filter=categoryIds:{100|101|102}</code> <br><br>Note that you must URL-encode the parameter list, which results in the following filter for the above example: <br><br> <code>filter=categoryIds%3A%7B100%7C101%7C102%7D</code>'
required: false
schema:
type: string
- name: marketplace_id
in: path
description: This path parameter specifies the eBay marketplace for which policy information is retrieved.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl" target="_blank">HTTP Request Headers</a> 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 <code>gzip</code>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnPolicyResponse'
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
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-metadata-openapi-original.yml