The buyer uses this call to check if the item is eligible to be returned, and how long the buyer has to return the item. Multiple check types can be specified in the request. The itemId, transactionId, and quantity of the order line item are required in the request.
Output Samples Change History |
See also Samples.
POST https://api.ebay.com/post-order/v2/return/check_eligibility
This call has no path or query parameters.
All requests made to eBay REST operations require you to provide the authorization
HTTP header for authentication.
See HTTP request headers for details.
This call uses standard authorization tokens. See Making a Call for details.
The following lists all fields that could be included in the request.
{ /* CheckEligibilityRequest */ "checkTypes": [ string /* More string nodes here */ ], "itemId": string, "reason": string, "returnQuantity": integer, "transactionId": string }
Input Container/Field | Type | Occurrence | Meaning |
---|---|---|---|
checkTypes | array of string | Required |
One or more enumeration values must be passed in this container to run one more eligibility checks. See EligibilityCheckTypeEnum for a full list of values.
Applicable values are from EligibilityCheckTypeEnum: |
itemId | string | Required | This is the unique identifier of the listing that is used to identify the listing that the eligibility check will be run against. The itemId and transactionId pair are required to identify an order line item. |
reason | string | Required |
This enumerated value indicates the buyer's reason for returning an item. This field is required.
Applicable values are from ReturnReasonEnum:See reason. |
returnQuantity | integer | Optional |
This integer value indicates the quantity of the line item being returned. This number is generally 1 , unless the buyer bought multiple quantity of the item in a multiple-quantity, fixed-price listing. If this field is omitted in the request, its value will default to 1 .
|
transactionId | string | Required | This is the unique identifier of the transaction that is used to identify the order line item that the eligibility check will be run against. The itemId and transactionId pair are required to identify an order line item. |
Input Samples Change History |
See also Samples.
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 CheckEligibilityResponse 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
{ /* CheckEligibilityResponse */ "eligibilityResultPerItem": { /* ReturnEligibilityPerItemType */ "eligibilityResultsPerCheckType": [ { /* ReturnEligibilityItemPerCheckTypeResult */ "checkType": string, "eligibilityInfo": { /* EligibilityResultType */ "caseId": string, "eligibilityErrorDetail": [ { /* ReturnEligibilityErrorDetailType */ "eligibilityError": { /* EligibilityErrorType */ "code": string, "content": string, "description": string } } /* More ReturnEligibilityErrorDetailType nodes here */ ], "eligibilityStatus": string, "eligibleStartDate": { /* DateTime */ "formattedValue": string, "value": datetime }, "returnCreationDate": { /* DateTime */ "formattedValue": string, "value": datetime }, "returnDeadline": { /* DateTime */ "formattedValue": string, "value": datetime }, "returnId": string } } /* More ReturnEligibilityItemPerCheckTypeResult nodes here */ ], "returnItem": { /* ReturnEligibilityItemType */ "itemId": string, "reason": string, "returnQuantity": integer, "transactionId": string } } }
Output Container/Field | Type | Occurrence | Meaning |
---|---|---|---|
eligibilityResultPerItem | ReturnEligibilityPerItemType | Always | This container consists of information on the return item and the results for each eligibility check type that was run against the item. |
eligibilityResultPerItem .eligibilityResultsPerCheckType |
array of ReturnEligibilityItemPerCheckTypeResult | Always | This container contains the results for each eligibility check type, including whether or not the line item is eligible to be returned, and any errors that may have occurred with the check. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .checkType |
string | Always |
This enumerated value indicates the type of eligibility check that was run against the order line item. For the POST /post-order/v2/return/check_eligibility call, multiple eligibility checks can be run against the order line item, but the POST /post-order/v2/return call only uses the RETURN_CREATION check.
Applicable values are from EligibilityCheckTypeEnum: Code so that your app gracefully handles any future changes to this list. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo |
EligibilityResultType | Always | This container includes the results of the eligibility check, including any errors that may have occurred with the eligibility check, as well as detailed information on the return request. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo.caseId |
string | Conditionally | This value is the unique identifier of an eBay case associated with the return request. This field is only returned if the return request was escalated into an eBay case. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibilityErrorDetail |
array of ReturnEligibilityErrorDetailType | Conditionally | This container consists of an error that occurred with the return eligibility check. This container is only returned if one or more return eligibility check errors occurred. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibilityErrorDetail .eligibilityError |
EligibilityErrorType | Conditionally | This container holds an array of one or more errors that occurred with an item return eligibility check, including the error code, the description of the error, and the enumeration value associated with the error. This container is only returned if one or more errors occur with an item eligibility check. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibilityErrorDetail .eligibilityError.code |
string | Conditionally | Unique identifier of the enumeration value. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibilityErrorDetail .eligibilityError.content |
string | Conditionally | The actual content of the eligibility error. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibilityErrorDetail .eligibilityError.description |
string | Conditionally | A description of the enumeration value. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibilityStatus |
string | Always |
This enumerated value indicates the success or failure of an return-related eligibility check. See StatusType for the description of the supported values.
Applicable values are from StatusType: Code so that your app gracefully handles any future changes to this list. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibleStartDate |
DateTime | Conditionally | This timestamp indicates when the buyer is eligible to create a return request for an item. This field is not returned if the buyer is not eligible to return the item. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibleStartDate .formattedValue |
string | Conditionally | This field is for internal or future use. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .eligibleStartDate.value |
datetime | Conditionally |
This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .returnCreationDate |
DateTime | Conditionally | This timestamp indicates the date/time when the return request was created. This field is only returned if return request was successfully created. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .returnCreationDate .formattedValue |
string | Conditionally | This field is for internal or future use. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .returnCreationDate.value |
datetime | Conditionally |
This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .returnDeadline |
DateTime | Always | This timestamp indicates the deadline in which the buyer must file a return request. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .returnDeadline.formattedValue |
string | Conditionally | This field is for internal or future use. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo .returnDeadline.value |
datetime | Conditionally |
This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type. |
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo.returnId |
string | Conditionally | The unique identifier of the newly created return request. This field is only returned if return request was successfully created. |
eligibilityResultPerItem .returnItem |
ReturnEligibilityItemType | Always | This container consists of summary information on the line item being returned, including the listing ID, the line item ID, the return reason, and the quantity purchased. |
eligibilityResultPerItem .returnItem.itemId |
string | Always | This is the unique identifier of the listing. |
eligibilityResultPerItem .returnItem.reason |
string | Always |
This enumerated value lists indicates the buyer's reason for returning the item.
Applicable values are from ReturnReasonEnum:See reason. Code so that your app gracefully handles any future changes to this list. |
eligibilityResultPerItem .returnItem.returnQuantity |
integer | Always | This integer value indicates the quantity of the line item being returned. This number is generally '1', unless the buyer bought multiple quantity of the item in a multiple-quantity, fixed-price listing. |
eligibilityResultPerItem .returnItem.transactionId |
string | Always | This is the unique identifier of the order line item. |
Input Output Change History |
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.
Checking return eligibility for line item
Description
This call is used to see if an order line item is eligible to be returned.
Input
In this sample call, the user is checking to see if a specific order line item is eligible to be returned. In the request payload, the user sets the the check type to RETURN_CREATION
. The order line item is identified with the itemId and transactionId field. The return reason is DEFECTIVE_ITEM
and the quantity is 1.
URL format. See also the non-wrapped version of this URL. POST https://api.ebay.com/post-order/v2/return/check_eligibility { "checkTypes": [ RETURN_CREATION ], "itemId": "190004238788", "transactionId": "8546962009", "reason": "DEFECTIVE_ITEM", "returnQuantity": "1" }
Output
The eligibilityInfo.eligibilityStatus field in the output shows that the order line item is eligible for a return. The time window for the return can be discerned by looking at the date values in the eligibleStartDate and returnDeadline containes. The same data that is passed in to the request payload is also returned under the returnItem container.
JSON format.
{
"eligibilityResultPerItem":
{
"eligibilityResultsPerCheckType": [
{
"checkType": "RETURN_CREATION",
"eligibilityInfo":
{
"eligibilityStatus": "SUCCESS",
"eligibleStartDate":
{
"value": "2015-08-05T20:18:17.000Z"
},
"returnDeadline":
{
"value": "2015-08-19T20:18:17.000Z"
}
}
}
],
"returnItem":
{
"itemId": "190004238788",
"transactionId": "8546962009",
"reason": "DEFECTIVE_ITEM",
"returnQuantity": "1"
}
}
}
Input Output Samples |
Change Date | Description |
---|---|
1.0 2015-06-30 |
|
Copyright © 2015–2018 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.