Check Return Eligibility

POST /post-order/v2/return/check_eligibility

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.

Input

Resource URI (production)

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

This call has no path or query 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

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
}

Request field descriptions

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: ITEM_SELECTION Checks that the item is paid for and happens before the return reason is selected. PRE_TRANSACTION Check that happens before the item is purchased. REPLACEMENT_CREATION Check that happens during the replacement creation process. REPLACEMENT_ITEM_SELECTION Checks that the item is paid for and is eligible for replacement. This happens before the return reason is selected. RETURN_CREATION Check that happens during the return creation process.
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.

Output

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 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
        }
    }
}

Response field descriptions

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: ITEM_SELECTION Checks that the item is paid for and happens before the return reason is selected. PRE_TRANSACTION Check that happens before the item is purchased. REPLACEMENT_CREATION Check that happens during the replacement creation process. REPLACEMENT_ITEM_SELECTION Checks that the item is paid for and is eligible for replacement. This happens before the return reason is selected. RETURN_CREATION Check that happens during the return creation process. 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: FAILED Indicates the return eligibility check failed. SELLER_APPROVAL Indicates the return eligibility check requires seller approval. SUCCESS Indicates the return eligibility check was successful. UNKNOWN Indicates the status of the return eligibility check is unknown. 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	Reserved for 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	Reserved for 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	Reserved for 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.

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.

Sample: Basic Call

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"
        }
    }
}

Change History

Change Date	Description
1.0 2015-06-30	Call (added): New call.