GET/marketplace/{marketplace_id}/get_item_condition_policies
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.
If applicable, this metadata also shows the different condition descriptors (with IDs) that an eBay category supports.
Note: Currently, condition grading is only applicable to the following trading card categories:
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 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 filter query parameter.
Important: Certified - Refurbished-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 authorization code grant flow and https://api.ebay.com/oauth/api_scope/sell.inventory scope in order to retrieve the refurbished conditions for the relevant categories.
See the eBay Refurbished Program - Category and marketplace support topic for the categories and marketplaces that support these refurbished conditions
These restricted item conditions will not be returned if an OAuth token created with the client credentials grant flow and https://api.ebay.com/oauth/api_scope scope is used, or if any seller is not eligible to list with that item condition.
See the Specifying OAuth scopes topic for more information about specifying scopes.
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.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| marketplace_id | string | This path parameter specifies the eBay marketplace for which policy information is retrieved. See HTTP Request Headers for a list of supported eBay marketplace ID values. Occurrence: Required |
| filter | string | 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. 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 that 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 Occurrence: Optional |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| Accept-Encoding | string | 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. Occurrence: Strongly Recommended |
OAuth scope
This request requires an access token created with either authorization code grant flow or client credentials grant flow. Please refer to the note below for more details.
The access token must be created using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope
https://api.ebay.com/oauth/api_scope/sell.inventory
See OAuth access tokens for more information.
IMPORTANT: An OAuth token created with the client credentials grant flow and https://api.ebay.com/oauth/api_scope scope is generally used for this method. However, Certified Refurbished-eligible sellers must use an OAuth token created with the authorization code grant flow and https://api.ebay.com/oauth/api_scope/sell.inventory scope in order to retrieve the 'Certified Refurbished' condition (condition ID 2000) for the relevant categories.
Request payload
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| itemConditionPolicies | array of ItemConditionPolicy | A list of category IDs and the policies for how to indicate an item's condition in each of the listed categories. Occurrence: Always |
| itemConditionPolicies.categoryId | string | The category ID to which the item-condition policy applies. Occurrence: Always |
| itemConditionPolicies.categoryTreeId | string | 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. Occurrence: Always |
| itemConditionPolicies.itemConditionRequired | boolean | This flag denotes whether or not you must list the item condition in a listing for the specified category. If set to Occurrence: Always |
| itemConditionPolicies.itemConditions | array of ItemCondition | The item-condition values allowed in the category. Occurrence: Always |
| itemConditionPolicies.itemConditions.conditionDescription | string | The human-readable label for the condition (e.g., "New"). This value is typically localized for each site. Occurrence: Always |
| itemConditionPolicies.itemConditions.conditionDescriptors | array of ItemConditionDescriptor | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint | ItemConditionDescriptorConstraint | This container shows the constraints on a condition descriptor, such as the maximum length, default condition descriptor value ID, cardinality, mode, usage, and applicable descriptor IDs. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint.applicableToConditionDescriptorIds | array of string | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint.cardinality | CardinalityEnum | The value returned in this field indicates whether a condition descriptor can have a single value or multiple values. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint.defaultConditionDescriptorValueId | string | The default condition descriptor value that will be set if there are multiple values. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint.maxLength | integer | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint.mode | ModeEnum | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorConstraint.usage | DescriptorUsageEnum | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorHelpText | string | A description of the condition descriptor that directs a user to its condition descriptor values. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorId | string | The unique identification number of a condition descriptor associated with with a conditionDescriptorName. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorName | string | The human-readable label for the condition descriptor associated with the conditionDescriptorID. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues | array of ItemConditionDescriptorValue | This array shows the possible values that map to the corresponding conditionDescriptorName values. Constraint information and help text are also shown for each value. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueAdditionalHelpText | array of string | Additional information about the the condition of the item that is not included in the conditionDescriptorValueHelpText field. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueConstraints | array of ItemConditionDescriptorValueConstraint | The constraints on a condition descriptor value, such as which descriptor value IDs and Descriptor ID it is associated with. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueConstraints.applicableToConditionDescriptorId | string | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueConstraints.applicableToConditionDescriptorValueIds | array of string | 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. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueHelpText | string | A detailed description of the condition descriptor value. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueId | string | The unique identification number of a condition descriptor value associated with the conditionDescriptorValueName. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionDescriptors.conditionDescriptorValues.conditionDescriptorValueName | string | The human-readable label for the condition descriptor value associated with the conditionDescriptorValueID. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionHelpText | string | A detailed description of the condition denoted by the conditionID and conditionDescription. Occurrence: Conditional |
| itemConditionPolicies.itemConditions.conditionId | string | The ID value of the selected item condition. For information on the supported condition ID values, see Item condition ID and name values. Occurrence: Always |
| itemConditionPolicies.itemConditions.usage | UsageEnum | The value returned in this field indicates if there are any usage restrictions or requirements for the corresponding item condition in the corresponding category. Occurrence: Conditional |
| warnings | array of ErrorDetailV3 | 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. Occurrence: Conditional |
| warnings.category | string | The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:
Occurrence: Conditional |
| warnings.domain | string | Name of the domain containing the service or application. Occurrence: Conditional |
| warnings.errorId | integer | 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. Occurrence: Conditional |
| warnings.inputRefIds | array of string | Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation. Occurrence: Conditional |
| warnings.longMessage | string | An expanded version of message that should be around 100-200 characters long, but is not required to be such. Occurrence: Conditional |
| warnings.message | string | 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. Occurrence: Conditional |
| warnings.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | This optional complex field type contains a list of one or more context-specific Occurrence: Conditional |
| warnings.parameters.name | string | Name of the entity that threw the error. Occurrence: Conditional |
| warnings.parameters.value | string | A description of the error. Occurrence: Conditional |
| warnings.subdomain | string | Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain. Occurrence: Conditional |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
| Status | Meaning |
|---|---|
| 200 | Success |
| 204 | No content |
| 400 | Bad Request |
| 404 | Not found |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 46000 | API_METADATA | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 46001 | API_METADATA | REQUEST | The specified marketplace ID was not found. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 46002 | API_METADATA | REQUEST | The filter value is invalid. Sample supported values: filter=categoryIds:{catId1|catId2|catId3}. |
| 46003 | API_METADATA | REQUEST | The specified categoryId was not found for the marketplace. |
| 46004 | API_METADATA | REQUEST | Only 50 Category IDs specified in the filter are considered. |
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Get the eBay category policies regarding item conditions
This example retrieves the policies for two specific categories, 90638 and 181923.
This method returns a list of leaf categories from the category tree of the specified marketplace. Each node in the response shows the policies that govern how to list item condition in each of the returned categories.
Input
This method does not use a request payload.
By default, this method returns the leaf nodes of the entire category tree for the specified marketplace. When you retrieve the entire tree, be sure to get the result as a GZIP file (see the top of the call page for syntax). To limit the response, specify up to 50 category IDs using the filter query parameter.
Note that you must URL-encode the category ID filter parameter value. This example uses the parameter: filter=categoryIds:{181923|90638}.
Additionally, this example uses an OAuth token created with the client credentials grant flow; however, Certified Refurbished-eligible sellers must use an OAuth token created with the authorization code grant flow in order to retrieve the Certified Refurbished condition (condition ID 2000) for the relevant categories.
GEThttps://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 body contains the policies for specifying item conditions for items listed in the categories specified in the request.
Sample 2: Get the eBay category policies regarding item conditions with condition descriptors
This examples retrieves the policies, along with the condition descriptors, for a specified eBay category, in this case 183050.
This method returns a list of leaf categories from the category tree of the specified marketplace. Each node in the response shows the policies that govern how to list item condition the returned categories using condition descriptors.
Note that condition descriptors are only returned for the following supported categories:
- Non-Sport Trading Card Singles
- CCG Individual Card
- Sports Trading Card Singles
Input
This method does not use a request payload.
By default, this method returns the leaf nodes for the entire category tree for the specified marketplace. When you retrieve the entire tree, be sure to get the result as a GZIP file (see the top of the call page for syntax). To limit the response, specify up to 50 category IDs using the filter query parameter.
Note that you must URL-encode the category ID filter parameter value. This example uses the parameter: filter=categoryIds:{183050}.
GEThttps://api.ebay.com/sell/metadata/v1/marketplace/EBAY_US/get_item_condition_policies?filter=categoryIds%3A%7B183050%7D
Output
If the call is successful, the response body contains the policies for specifying item conditions using condition descriptors for items listed in the category specified in the request.