eBay Post-Order APIVersion 2

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

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

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



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.