eBay Post-Order APIVersion 2.7.3


GET /post-order/v2/return/metadata/{metadataKey}

This call retrieves metadata values relating to Returns. Pass in a supported ReturnMetadataKeyEnum value as a path parameter.


Request model

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

See also Samples.

Resource URI (production)

GET https://api.ebay.com/post-order/v2/return/metadata/{metadataKey}

URI parameters

Parameter Type Required? Meaning
metadataKey string Required One of the values defined in the ReturnMetadataKeyEnum type should be passed in at the end of the call URI to retrieve that set of metadata in the response.

Supported HTTP request headers

Header Description Applicable Values
Accept The media type for the response. Defaults to JSON (the only supported media type). application/json
Authorization The Authentication Token that is used to validate the caller has permission to access the eBay servers. Prefix a valid eBay token with the word "TOKEN".
For more details, see Getting Tokens.
TOKEN <authorization-token-value>
Content-Type The MIME type of the body of the request. Must be JSON.
X-EBAY-C-MARKETPLACE-ID The global ID of the eBay site on which the transaction took place.
Currently, the marketplaces are limited to:


This call uses standard authorization tokens. See Making a Call for details.

Payload model

This call has no request payload.


Response model

A successful call contains an HTTP status code of 200. See the HTTP Status Code Registry for a complete overview of HTTP status codes.

Note: The response information on this page applies to successful requests only. For information about the error fields and how to work with them, see Error Handling.

See also Samples.

Payload model

Supported response formats: application/json, application/xml

For more information:
- See GetMetadataResponse for a description of the response structure
- See the following table for descriptions of each of the data elements returned
- See the Samples for an example of the response format

{ /* GetMetadataResponse */
"metadata": [
    { /* ReturnMetadataType */
    "dataType": string,
    "isArray": boolean,
    "siteMetadataKey": ReturnMetadataKeyEnum,
    "values": [
        /* More string nodes here */
    /* More ReturnMetadataType nodes here */

Response field descriptions

Output Container/Field Type Occurrence Meaning
metadata array of ReturnMetadataType Always Contains an array of one or more sets of Returns-related metadata. For the initial release of the Post-Order API, the only metadata that can be retrieved is a list of return reasons that the buyer can use when creating a return request.
metadata.dataType string Always This value indicates the primitive data type of the metadata being returned under the values array.
metadata.isArray boolean Always This boolean value indicates whether or not an array of metadata values is returned under the values array.
metadata.siteMetadataKey ReturnMetadataKeyEnum Always This enumeration value indicates the type of metadata being returned under the values array.

Applicable values:

This enumeration value indicates that each valid return escalation reason is returned in the metadata call.
This enumeration value indicates that each valid item return reason is returned in the metadata call.

metadata.values array of string Always This container is an array of one or more metadata values associated with the metadata category specified in the siteMetadataKey field of the request. Currently, the only supported siteMetadataKey value is 'RETURN_REASONS'. The values container would contain a list of valid return reasons that can be given by the buyer.


New to making API calls? Please see Making an API Call.

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 Valid Return Reasons

Request a list of the acceptable reasons for a return.


Applications can use this operation to discover the set of valid reasons for a buyer to request a return, present a list of these reasons to buyers or sellers, and use this information to validate a return request.


The metadataKey parameter is set to RETURN_REASONS, its only currently available value, which means that the caller is requesting a list of valid reasons that buyers can use for a return request. This call has no request payload.

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

POST https://api.ebay.com/post-order/v2/return/metadata/RETURN_REASONS


The isArray field's value of true indicates that the values array is populated with values. The dataType field's value of RtnReason indicates that they are valid reasons for a buyer to request a return.

JSON format. Also available is the .txt version of this JSON.

  "metadata": [
      "siteMetadataKey": "RETURN_REASONS",
      "dataType": "RtnReason",
      "isArray": true,
      "values": [

Change History

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