Search Returns

GET /post-order/v2/return/search

Use this method to retrieve the details on one or more return requests, or a summary of return requests per user. This method supports several filters, supplied as query parameters, that allow you to restrict results by date, return status, return type, or by listing. If you use more than one filter type in the request, Boolean AND logic is applied to the results set. Boolean OR logic is used for conditions within a filter.

Input

See also Samples.

Resource URI (production)

GET https://api.ebay.com/post-order/v2/return/search?
  creation_date_range_from=string&
  creation_date_range_to=string&
  item_id=string&
  limit=integer&
  offset=integer&
  order_id=string&
  return_id=string&
  return_state=ReturnCountFilterEnum&
  role=UserRoleFilterEnum&
  sort=ReturnSortField&
  states=ReturnStateEnum&
  transaction_id=string

URI parameters

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.

Authorization

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

Payload model

This call has no request payload.

Output

See also Samples.

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.

Supported response formats: application/json, application/xml

For more information:
- See GetSummaryResponse 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

{ /* GetSummaryResponse */
"countSummary": [
    { /* CountSummaryType */
    "count": integer,
    "type": string
    }
    /* More CountSummaryType nodes here */
  ],
"members": [
    { /* ReturnSummaryType */
    "buyerAvailableOptions": [
        { /* AvailableOptionType */
        "actionType": string,
        "actionURL": string
        }
        /* More AvailableOptionType nodes here */
      ],
    "buyerLoginName": string,
    "buyerResponseDue":
        { /* ReturnResponseDueType */
        "activityDue": string,
        "respondByDate":
            { /* DateTime */
            "formattedValue": string,
            "value": datetime
            }
        },
    "buyerTotalRefund":
        { /* TotalRefundAmountType */
        "actualRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "exchangeRate": string,
            "value": number
            },
        "estimatedRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "exchangeRate": string,
            "value": number
            }
        },
    "creationInfo":
        { /* ReturnCreationInfoType */
        "comments":
            { /* Text */
            "content": string,
            "language": string,
            "translatedFromContent": string,
            "translatedFromLanguage": string
            },
        "creationDate":
            { /* DateTime */
            "formattedValue": string,
            "value": datetime
            },
        "item":
            { /* ReturnItemType */
            "itemId": string,
            "returnQuantity": integer,
            "transactionId": string
            },
        "reason": string,
        "reasonType": string,
        "type": string
        },
    "currentType": string,
    "escalationInfo":
        { /* EscalationInfoType */
        "buyerEscalationEligibilityInfo":
            { /* EscalationEligibilityInfo */
            "eligible": boolean,
            "endTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                },
            "startTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                }
            },
        "caseId": string,
        "sellerEscalationEligibilityInfo":
            { /* EscalationEligibilityInfo */
            "eligible": boolean,
            "endTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                },
            "startTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                }
            }
        },
    "orderId": string,
    "returnId": string,
    "returnPolicy":
        { /* ReturnPolicyType */
        "rmaRequired": boolean
        },
    "sellerAvailableOptions": [
        { /* AvailableOptionType */
        "actionType": string,
        "actionURL": string
        }
        /* More AvailableOptionType nodes here */
      ],
    "sellerLoginName": string,
    "sellerResponseDue":
        { /* ReturnResponseDueType */
        "activityDue": string,
        "respondByDate":
            { /* DateTime */
            "formattedValue": string,
            "value": datetime
            }
        },
    "sellerTotalRefund":
        { /* TotalRefundAmountType */
        "actualRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "exchangeRate": string,
            "value": number
            },
        "estimatedRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "exchangeRate": string,
            "value": number
            }
        },
    "state": string,
    "status": string,
    "timeoutDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        }
    }
    /* More ReturnSummaryType nodes here */
  ],
"paginationOutput":
    { /* PaginationOutput */
    "limit": integer,
    "offset": integer,
    "totalEntries": integer,
    "totalPages": integer
    },
"total": integer
}

Response field descriptions

Samples

New to making API calls? Please see Making a 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.

Search for returns

Description

This call allows for a search of return requests. Query parameters allow for flexibility in the search. For this particular call sample, a seller is looking for all return requests that have just been initiated by their order partners (buyers).

Input

The seller is looking for all return requests that have just been initiated, so the seller includes the return_state query parameter and sets its value to RETURN_STARTED.

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

GET https://api.ebay.com/post-order/v2/return/search?
   return_state=RETURN_STARTED

Output

Based on the response, there are currently three return requests that have just been initiated by buyers. The countSummary container captures this fact. Detailed information on the three return requests can be found under the returns container. Each return request is identifier by its returnId value. For two of the return requests, the buyers are asking for their money back, as indicated in the currentType fields. The last return request in the response shows that the buyer noted the received item as being defective (see the creationInfo.reason field) and that buyer wants a replacement item, as indicated by the corresponding currentType field.

For all three of these return requests, the seller's next response will be to either accept or deny the return request, or send the buyer a message. These available options are captured in the sellerAvailableOptions container.

JSON format.
{ /* GetSummaryResponse */
"countSummary": [
    { 
    "count": 3,
    "type": RETURN_STARTED
    }
  ],
"returns": [
    { 
    "returnId": "5********2",
    "currentType": MONEY_BACK,
    "state": RETURN_REQUESTED,
    "status": RETURN_REQUESTED,
    "creationInfo":
				{ 
				"creationDate":
						{ 
						"value": "2015-08-05T20:18:17.000Z"
						},
				"item":
						{ 
						"itemId": "1**********6",
						"transactionId": "8********9",
						"returnQuantity": 1,
						},
				"reason": ARRIVED_DAMAGED,
				"type": MONEY_BACK
        },
    "buyerLoginName": "b*******1",
    "sellerLoginName": "s********4",
    "buyerTotalRefund":
        { 
        "estimatedRefundAmount":
            { 
            "value": 27.5
            "currency": USD,
            }
        },
    "escalationInfo":
        { 
        "buyerEscalationEligibilityInfo":
            { 
            "eligible": true,
            "startTime":
								{ 
								"value": "2015-08-05T20:18:17.000Z"
                }
            "endTime":
                { 
                "value": "2015-08-19T20:18:17.000Z"
                }
            },
        "sellerEscalationEligibilityInfo":
            { 
           	"eligible": true,
							 "startTime":
									{ 
									"value": "2015-08-05T20:18:17.000Z"
									 }
							 "endTime":
									 { 
									 "value": "2015-08-19T20:18:17.000Z"
                }
            }
        },
    "sellerAvailableOptions": [
        { 
        "actionType": SELLER_APPROVE_REQUEST
        },
        { 
				"actionType": SELLER_DECLINE_REQUEST
        },
        { 
				"actionType": SELLER_SEND_MESSAGE
        }
      ],
    "sellerResponseDue":
        { 
        "activityDue": SELLER_APPROVE_REQUEST,
        "respondByDate":
            { 
            "value": "2015-08-09T20:18:17.000Z"
            }
        },
    "sellerTotalRefund":
        { 
				"estimatedRefundAmount":
						{ 
						"value": 27.5
						"currency": USD,
						}
        },
    },
    { 
		"returnId": "5********8",
		"currentType": MONEY_BACK,
		"state": RETURN_REQUESTED,
		"status": RETURN_REQUESTED,
		"creationInfo":
				{ 
				"creationDate":
						{ 
						"value": "2015-08-06T20:20:17.000Z"
						},
				"item":
						{ 
						"itemId": "1**********2",
						"transactionId": "8********4",
						"returnQuantity": 1,
						},
				"reason": NO_LONGER_NEED_ITEM,
				"type": MONEY_BACK
				},
		"buyerLoginName": "b*******4",
		"sellerLoginName": "s********4",
		"buyerTotalRefund":
				{ 
				"estimatedRefundAmount":
						{ 
						"value": 34.75
						"currency": USD,
						}
				},
		"escalationInfo":
				{ 
				"buyerEscalationEligibilityInfo":
						{ 
						"eligible": true,
						"startTime":
								{ 
								"value": "2015-08-06T20:20:17.000Z"
								}
						"endTime":
								{ 
								"value": "2015-08-20T20:20:17.000Z"
								}
						},
				"sellerEscalationEligibilityInfo":
						{ 
						"eligible": true,
							 "startTime":
										{ 
										"value": "2015-08-06T20:20:17.000Z"
										}
								"endTime":
										{ 
										"value": "2015-08-20T20:20:17.000Z"
										}
								},
						}
				},
		"sellerAvailableOptions": [
				{ 
				"actionType": SELLER_APPROVE_REQUEST
				},
				{ 
				"actionType": SELLER_DECLINE_REQUEST
				},
				{ 
				"actionType": SELLER_SEND_MESSAGE
				}
			],
		"sellerResponseDue":
				{ 
				"activityDue": SELLER_APPROVE_REQUEST,
				"respondByDate":
						{ 
						"value": "2015-08-10T20:18:17.000Z"
						}
				},
		"sellerTotalRefund":
				{ 
				"estimatedRefundAmount":
						{ 
						"value": 34.75
						"currency": USD,
						}
				},
		},
		{ 
		"returnId": "5********5",
		"currentType": REPLACEMENT,
		"state": REPLACEMENT_REQUESTED,
		"status": REPLACEMENT_REQUESTED,
		"creationInfo":
				{ 
				"creationDate":
						{ 
						"value": "2015-08-08T09:42:37.000Z"
						},
				"item":
						{ 
						"itemId": "1**********5",
						"transactionId": "8********9",
						"returnQuantity": 1,
						},
				"reason": DEFECTIVE_ITEM,
				"type": REPLACEMENT
				},
		"buyerLoginName": "b********8",
		"sellerLoginName": "s********4",
		"escalationInfo":
				{ 
				"buyerEscalationEligibilityInfo":
						{ 
						"eligible": true,
						"startTime":
								{ 
								"value": "2015-08-08T09:42:37.000Z"
								}
						"endTime":
								{ 
								"value": "2015-08-22T09:42:37.000Z"
								}
						},
				"sellerEscalationEligibilityInfo":
						{ 
						"eligible": true,
						"startTime":
								{ 
								"value": "2015-08-08T09:42:37.000Z"
								}
						"endTime":
								{ 
								"value": "2015-08-22T09:42:37.000Z"
								}
						},
					}
				},
		"sellerAvailableOptions": [
				{ 
				"actionType": SELLER_APPROVE_REQUEST
				},
				{ 
				"actionType": SELLER_DECLINE_REQUEST
				},
				{ 
				"actionType": SELLER_SEND_MESSAGE
				}
			],
		"sellerResponseDue":
				{ 
				"activityDue": SELLER_APPROVE_REQUEST,
				"respondByDate":
						{ 
						"value": "2015-08-12T09:42:37.000Z"
						}
				},
		}
  ],
"paginationOutput":
    { 
    "limit": 100,
    "offset": 1,
    "totalEntries": 3,
    "totalPages": 1
    }
}

Change History