Check Return Eligibility

POST /post-order/v2/return/check_eligibility

The buyer uses this call to check whether or not a line item is eligible to be returned plus 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": [
    token
    /* More token nodes here */
  ],
"itemId": string,
"reason": token,
"returnQuantity": integer,
"transactionId": string
}

Request field descriptions

Input Container/Field	Type	Occurrence	Meaning
checkTypes	array of token	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.
itemId	string	Required	The unique eBay-assigned ID for a item in an order. Note: This field in conjunction with the transactionId field uniquely identify a line item within an order.
reason	token	Required	This enumerated value indicates the buyer's reason for returning an item. This field is required. Applicable values: See ReturnReasonEnum
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	The unique eBay-assigned ID of the order (transaction) associated with the return.

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": token,
        "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": token,
        "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	token	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: See ret:EligibilityCheckTypeEnum
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 eBay-assigned ID 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 eBay-assigned ID 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 The return eligibility check failed. SELLER_APPROVAL The return eligibility check requires seller approval. SUCCESS The return eligibility check was successful. UNKNOWN The status of the return eligibility check is unknown. WARNING The return eligibility check succeeded, but with a warning. Review the response for details. 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	The date and time defining the start or end of an action or event. The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2020-08-20T00:00:00.000Z`
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	The date and time defining the start or end of an action or event. The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2020-08-20T00:00:00.000Z`
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	The date and time defining the start or end of an action or event. The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2020-08-20T00:00:00.000Z`
eligibilityResultPerItem .eligibilityResultsPerCheckType .eligibilityInfo.returnId	string	Conditionally	The unique eBay-assigned ID 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	The unique eBay-assigned ID for a item in an order. Note: This field in conjunction with the transactionId field uniquely identify a line item within an order.
eligibilityResultPerItem .returnItem.reason	token	Always	This enumerated value lists indicates the buyer's reason for returning the item. Applicable values: See ReturnReasonEnum
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	The unique eBay-assigned ID of the order (transaction) associated with the return.

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.