eBay Post-Order APIVersion 2.7.7
 

Check Return Eligibility

POST /post-order/v2/return/check_eligibility

This method is used on behalf of the buyer to check whether or not a line item is eligible to be returned. The response will also show the deadline for the buyer creating the return request. Multiple check types can be specified in the request.

The itemId, transactionId, and quantity of the order line item are all required in the request.

This method is not supported in the Sandbox environment.

Input

See also Samples.

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 into this array to run one or more return eligibility checks. See the ret:EligibilityCheckTypeEnum type definition for a full list of supported values.

Applicable values are from ret:EligibilityCheckTypeEnum:See checkTypes.
itemId string Required The unique identifier for the eBay listing where the item was purchased. This field is used in conjunction with the transactionId field to identify a line item within an order.
reason string Required This enumerated value indicates the buyer's reason for returning an item.

The supported enumeration values representing valid return reasons are defined in the ReturnReasonEnum type definition.

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 line 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 identifier for the purchase of the item. This value is created right when the buyer is committed to buying the item, whether that buyer uses a 'Buy it Now' capability, is the winning bidder of an auction, or the buyer's Best Offer is accepted by the seller. This field is used in conjunction with the itemId field to identify a line item within an order.

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 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 order line item and the results for each eligibility check type that was run against the order line item.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
array of ReturnEligibilityItemPerCheckTypeResult Always This array contains the results of one or more return eligibility check types for the line, including any errors that may have occurred with the check type.
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 method, multiple eligibility checks can be run against the order line item, but the POST /post-order/v2/return method only uses the RETURN_CREATION check.

Applicable values are from ret:EligibilityCheckTypeEnum:See checkType.
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 return 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 array may consist of one or more errors that may have occurred with the return eligibility check. This array is only returned if one or more return eligibility check errors occurred.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .eligibilityErrorDetail
  .eligibilityError
EligibilityErrorType Conditionally This container provides information on an error that occurred in regards to an order line item being eligible for a return request.

This container is only returned if one or more errors occur with an item eligibility check.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .eligibilityErrorDetail
  .eligibilityError.code
string Conditionally A unique eBay-assigned ID of the error.
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 error.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .eligibilityStatus
string Always This enumeration value indicates the success or failure of a return eligibility check. See StatusType for the description of the supported values.

Applicable values are from StatusType:

FAILED
If this value is returned in the GET /post-order/v2/return/check_eligibility or POST /post-order/v2/return responses, it means that the return eligibility check or the creation of return request failed. This generally indicates that there was either an issue with the request payload or there was a system error.
SELLER_APPROVAL
If this value is returned in the GET /post-order/v2/return/check_eligibility or POST /post-order/v2/return responses, it indicates that the buyer is eligible to create a return request for the order line item, but the return request will have to be accepted by the seller.
SUCCESS
If this value is returned in the GET /post-order/v2/return/check_eligibility response, it indicates that the buyer is eligible to create a return request for the order line item. If this value is returned in the POST /post-order/v2/return response, it indicates that the return request for the order line item was created successfully.
UNKNOWN
This enumeration value may get returned in the GET /post-order/v2/return/check_eligibility or POST /post-order/v2/return responses if the status of the return eligibility check or the creation of the return request is unknown.
WARNING
If this value is returned in the GET /post-order/v2/return/check_eligibility or POST /post-order/v2/return responses, it means that the return eligibility check or the creation of return request succeeded, but with a warning. The user should check for a eligibilityErrorDetail container to possibly get more information about the warning

Code so that your app gracefully handles any future changes to this list.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .eligibleStartDate
DateTime Conditionally The timestamp in this container indicates when the buyer is first eligible to create a return request for a 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 timestamp indicates the date and time when an action or event occurred.

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: 2022-03-20T00:00:00.000Z
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .returnCreationDate
DateTime Conditionally The timestamp in this container indicates the date/time when the return request was created. This field is only returned if a return request was successfully created.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .returnCreationDate
  .formattedValue
string Conditionally Reserved for future use.
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .returnCreationDate.value
datetime Conditionally This timestamp indicates the date and time when an action or event occurred.

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: 2022-03-20T00:00:00.000Z
eligibilityResultPerItem
  .eligibilityResultsPerCheckType
  .eligibilityInfo
  .returnDeadline
DateTime Always The timestamp in this container indicates the deadline for 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 timestamp indicates the date and time when an action or event occurred.

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: 2022-03-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 a return request was successfully created.
eligibilityResultPerItem
  .returnItem
ReturnEligibilityItemType Always This container consists of summary information on the line item being checked for return eligibility.
eligibilityResultPerItem
  .returnItem.itemId
string Always The unique identifier of the eBay listing where the item was purchased. This field is used in conjunction with the transactionId field to identify a line item within an order.
eligibilityResultPerItem
  .returnItem.reason
string Always This enumerated value lists indicates the buyer's reason for returning the item.

The supported enumeration values representing valid return reasons are defined in the ReturnReasonEnum type definition.

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 identifier for the purchase of a item. This value is created right when the buyer is committed to buying the item, whether that buyer uses a 'Buy it Now' capability, is the winning bidder of an auction, or the buyer's Best Offer is accepted by the seller. This field is used in conjunction with the itemId field to identify a line item within an order.
null



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": "1**********8",
"transactionId": "8********9",
"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": "1**********8",
				"transactionId": "8********9",
				"reason": "DEFECTIVE_ITEM",
				"returnQuantity": "1"
        }
    }
}



Change History

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