This doc page has moved! You should be automatically redirected to the resources page for the eBay Metadata API. If you are not redirected automatically, follow this link to the Metadata API.

eBay Metadata APIVersion 1.1.0

Get Policies for Listing Structures

GET /marketplace/{marketplace_id}/get_listing_structure_policies

This method returns the 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.

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 return a very large response payload and we strongly reccomend you get the results in a GZIP file by including the following HTTP header with your request:

  Accept-Encoding: application/gzip


See also Samples.

Resource URI (production)


URI parameters

Parameter Type Required? Meaning
filter string Optional Limits the response by returning policy information for only the leaf categories specified by this parameter. Set filter to a list of categoryId values. You can specify up to 50 category IDs by separating each with a pipe character ('|'). If you specfy more than 50 categoryId values, eBay returns a warning along with the results for the first 50 IDs. If you specify a category that has child nodes, eBay returns policy information for all the leaf categories of the parent node.

Example: filter=categoryIds:{100|101|102}

Note that you must URL-encode the list of category ID values, which results in the following filter for the above example: filter=categoryIds%3A%7B100%7C101%7C102%7D
marketplace_id string Required Specifies the eBay marketplace for which policy information is returned.

HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication.
See HTTP request headers for details.

OAuth request scope

This request requires either a user access token or an application access token with the following scope:

See Getting Access Tokens for more information.

Payload model

This call has no request payload.


See also Samples.

HTTP status codes

This call can return one of the following HTTP status codes. See the HTTP Status Code Registry for a complete overview of HTTP status codes.

Status Meaning
200 Success
204 No content
400 Bad Request
404 Not found
500 Internal Server Error

Payload model

Note: For information about the error fields and how to work with them, see Error Handling.

The following lists all fields that could be included in the response.

{ /* ListingStructurePolicyResponse */
"listingStructurePolicies": [
    { /* ListingStructurePolicy */
    "categoryId": string,
    "categoryTreeId": string,
    "variationsSupported": boolean
    /* More ListingStructurePolicy nodes here */
"warnings": [
    { /* ErrorDetailV3 */
    "category": string,
    "domain": string,
    "errorId": integer,
    "inputRefIds": [
        /* More string nodes here */
    "longMessage": string,
    "message": string,
    "outputRefIds": [
        /* More string nodes here */
    "parameters": [
        { /* ErrorParameterV3 */
        "name": string,
        "value": string
        /* More ErrorParameterV3 nodes here */
    "subdomain": string
    /* More ErrorDetailV3 nodes here */

Response field descriptions

Output Container/Field Type Occurrence Meaning
listingStructurePolicies array of ListingStructurePolicy Always A list of category IDs and a flag indicating whether or not each listed category supports item variations.
string Always The category ID to which the listing-structure policy applies.
string Always A categoryTreeId is a unique eBay-assigned ID value that represents the root node of an eBay category tree. A category tree is a hierarchical framework of eBay categories that begins at the root node of the tree and extends to include all the child nodes in the tree. Each child node in the tree is an eBay category, and each is represented by a unique categoryId value. Within a category tree, the leaf nodes are the nodes that have no child nodes. The root node of a category tree is often used to define the default category tree used by one or more eBay marketplaces.
boolean Always Indicates if the associated category supports listings with item variations. A value of true indicates the category does support item variations.
warnings array of ErrorDetailV3 Conditionally 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.
warnings.category string Conditionally 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.
warnings.domain string Conditionally Name of the domain containing the service or application.
warnings.errorId integer Conditionally A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.
warnings.inputRefIds array of string Conditionally Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.
warnings.longMessage string Conditionally An expanded version of message that should be around 100-200 characters long, but is not required to be such.
warnings.message string Conditionally An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.
warnings.outputRefIds array of string Conditionally Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.
warnings.parameters array of ErrorParameterV3 Conditionally 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. string Conditionally Name of the entity that threw the error.
warnings.parameters.value string Conditionally A description of the error.
warnings.subdomain string Conditionally Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain.

Error Codes

Code Domain Category Nature Meaning
46000 API_METADATA APPLICATION ERROR There was a problem with an eBay internal system or process.Contact eBay developer support for assistance.
46001 API_METADATA REQUEST ERROR The specified marketplace ID was not found.
46002 API_METADATA REQUEST WARNING The filter value is invalid. Specify multiple categories using the following syntax: filter=categoryIds:{catId1|catId2|catId3}
46003 API_METADATA REQUEST WARNING The specified categoryId was not found for the marketplace.
46004 API_METADATA REQUEST WARNING Only the first 50 Category IDs specified in the filter parameter are returned, the rest are ignored.


Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Get the policies regarding categories that support item variation listings

This example retrieves the policies for two specific categories.


This example gets the policies that dictate whether or not you can list items that contain variations in two specified categories, 90638 and 75529.


There is no request payload for this call, however, unless you want to retrieve the policies for the entire marketplace tree, specify up to 50 category IDs using the filter query parameter. See the example URI for the specifics of the syntax needed to specify multiple category IDs.

Note: You must URL-encode the category ID values of the filter parameter. The example shown encodes the ID list of following parameter: filter=categoryIds:{75592|90638}

URL format. See also the non-wrapped version of this URL.



If the call is successful, the response payload contains the listing-structure policies for items listed in the categories specified in the request.

JSON format.
    "listingStructurePolicies": [
            "categoryTreeId": "0",
            "categoryId": "90638",
            "variationsSupported": false
            "categoryTreeId": "0",
            "categoryId": "75592",
            "variationsSupported": true

Change History

Change Date Description
  • Call (added): New call.