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 Returns

GET /marketplace/{marketplace_id}/get_return_policies

This method returns the policies that define whether or not you must include a return policy for the items you list 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_return_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.

{ /* ReturnPolicyResponse */
"returnPolicies": [
    sel:ReturnsPolicy
    /* More sel:ReturnsPolicy 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
returnPolicies array of sel:ReturnsPolicy Always A list of category IDs and a flag indicating whether or not the listings in each category requires a return policy.
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 regarding item returns

This example retrieves the policies for two specific categories.

Description

This example gets the policies that dictate whether or not you must supply item return options for the items that you list in the two specified categories, 181923 and 90638.

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_return_policies?
   filter=categoryIds%3A%7B181923%7C90638%7D

Output

If the call is successful, the response payload contains the policies that dictate whether or not you must specify a return policy for items listed in the categories specified in the request.

JSON format.
{
    "returnPolicies": [
        {
            "categoryTreeId": "0",
            "categoryId": "90638",
            "required": true
        },
        {
            "categoryTreeId": "0",
            "categoryId": "181923",
            "required": true
        }
    ]
}



Change History

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