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 Item Condition

GET /marketplace/{marketplace_id}/get_item_condition_policies

This method returns the policies that define how to specify item conditions 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 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

Input

See also Samples.

Resource URI (production)

GET https://api.ebay.com/sell/metadata/v1/marketplace/{marketplace_id}/get_item_condition_policies?
  filter=string

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:

https://api.ebay.com/oauth/api_scope

See Getting Access Tokens for more information.



Payload model

This call has no request payload.


Output

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.

{ /* ItemConditionPolicyResponse */
"itemConditionPolicies": [
    { /* ItemConditionPolicy */
    "categoryId": string,
    "categoryTreeId": string,
    "itemConditionRequired": boolean,
    "itemConditions": [
        { /* ItemCondition */
        "conditionDescription": string,
        "conditionId": string
        }
        /* More ItemCondition nodes here */
      ]
    }
    /* More ItemConditionPolicy nodes here */
  ],
"warnings": [
    { /* ErrorDetailV3 */
    "category": string,
    "domain": string,
    "errorId": integer,
    "inputRefIds": [
        string
        /* More string nodes here */
      ],
    "longMessage": string,
    "message": string,
    "outputRefIds": [
        string
        /* 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
itemConditionPolicies array of ItemConditionPolicy Always A list of category IDs and the policies for how to indicate an item's condition in each of the listed categories.
itemConditionPolicies
  .categoryId
string Always The category ID to which the item-condition policy applies.
itemConditionPolicies
  .categoryTreeId
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.
itemConditionPolicies
  .itemConditionRequired
boolean Always Indicates whether or not you must list the item condition in a listing for the specified category. A value of true indicates that you must specify an item condition for the associated category.
itemConditionPolicies
  .itemConditions
array of ItemCondition Always The allowed item-condition values.
itemConditionPolicies
  .itemConditions
  .conditionDescription
string Always The human-readable label for the condition (e.g., "New"). This value is typically localized for each site. Note that the display name can vary by category. For example, the description for condition ID 1000 could be called "New: with Tags" in one category and "Brand New" in another. For details on condition IDs and descriptions, see eBay Condition ID Values.
itemConditionPolicies
  .itemConditions.conditionId
string Always The ID value of the selected item condition. For information on the supported condition ID values, see eBay Condition ID Values.
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.
warnings.parameters.name 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.



Samples

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 for specifying item conditions

This example retrieves the policies for two specific categories.

Description

This example gets the policies that dictate how you should list the item condition for items listed in the two specified categories, 90638 and 181923.

Input

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:{181923|90638}

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

GET https://api.ebay.com/sell/metadata/v1/marketplace/EBAY_US/get_item_condition_policies?
   filter=categoryIds%3A%7B181923%7C90638%7D

Output

If the call is successful, the response payload contains the policies for specifying item conditions for items listed in the categories specified in the request.

JSON format.
{
    "itemConditionPolicies": [
        {
            "categoryTreeId": "0",
            "categoryId": "90638",
            "itemConditionRequired": false,
            "itemConditions": [
                {
                    "conditionId": "2750",
                    "conditionDescription": "Like New"
                },
                {
                    "conditionId": "7000",
                    "conditionDescription": "For parts or not working"
                },
                {
                    "conditionId": "6000",
                    "conditionDescription": "Acceptable"
                },
                {
                    "conditionId": "5000",
                    "conditionDescription": "Good"
                },
                {
                    "conditionId": "4000",
                    "conditionDescription": "Very Good"
                },
                {
                    "conditionId": "3000",
                    "conditionDescription": "Used"
                },
                {
                    "conditionId": "2500",
                    "conditionDescription": "Seller refurbished"
                },
                {
                    "conditionId": "2000",
                    "conditionDescription": "Manufacturer refurbished"
                },
                {
                    "conditionId": "1750",
                    "conditionDescription": "New with defects"
                },
                {
                    "conditionId": "1500",
                    "conditionDescription": "New other (see details)"
                },
                {
                    "conditionId": "1000",
                    "conditionDescription": "New"
                }
            ]
        },
        {
            "categoryTreeId": "0",
            "categoryId": "181923",
            "itemConditionRequired": true,
            "itemConditions": [
                {
                    "conditionId": "1000",
                    "conditionDescription": "New"
                },
                {
                    "conditionId": "1500",
                    "conditionDescription": "New other (see details)"
                },
                {
                    "conditionId": "2000",
                    "conditionDescription": "Manufacturer refurbished"
                },
                {
                    "conditionId": "2500",
                    "conditionDescription": "Seller refurbished"
                },
                {
                    "conditionId": "3000",
                    "conditionDescription": "Used"
                },
                {
                    "conditionId": "7000",
                    "conditionDescription": "For parts or not working"
                }
            ]
        }
    ]
}



Change History

Change Date Description
1.1.0
2017-06-06
  • Call (added): New call.