eBay Post-Order APIVersion 2

Check Cancellation Eligibility

POST /post-order/v2/cancellation/check_eligibility

This call determines on behalf of a seller whether a specified order is eligible for cancellation.

In the legacyOrderId request field, provide the value of the OrderID field returned by the Trading API's GetOrders call, and the response will contain cancellation eligibility information at the order and order line item levels.

Note: Currently, an entire eligible order can be canceled, but not individual order line items. For the order to be eligible for cancellation, all of its order line items must be eligible for cancellation.
For more information about using the Order Cancellation calls, see Handling Order Cancellations in the eBay Features Guide.

Input

See also Samples.

Resource URI (production)

POST https://api.ebay.com/post-order/v2/cancellation/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.

{ /* OrderEligibilityCheckInfo */
"legacyOrderId": string
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
legacyOrderId string Required The unique ID of the order being canceled or the order being considered for cancellation.

Note: This is the value of the OrderID field returned by the Trading API's GetOrders call.

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

{ /* OrderEligibilityResult */
"eligible": boolean,
"eligibleCancelReason": [
    token
    /* More token nodes here */
  ],
"failureReason": [
    string
    /* More string nodes here */
  ],
"itemEligibilityResult": [
    { /* ItemEligibilityResult */
    "eligible": boolean,
    "failureReason": [
        string
        /* More string nodes here */
      ],
    "itemId": integer,
    "transactionId": integer
    }
    /* More ItemEligibilityResult nodes here */
  ],
"legacyOrderId": string
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
eligible boolean Always If set to true, this order is eligible to be canceled. If false, this order is not eligible to be canceled.
eligibleCancelReason array of token Conditionally A list of one or more reasons that a buyer or seller can give for canceling this order. This field is returned only if the value of the eligible field is true. The two enumeration values that are specifically for sellers are BUYER_CANCEL_OR_ADDRESS_ISSUE and OUT_OF_STOCK_OR_CANNOT_FULFILL.

Applicable values: See CancelReasonEnum
failureReason array of string Conditionally A list of one or more reasons why this order has been found ineligible for cancellation. This field is returned only if the value of the eligible field is false. This field repeats for each applicable failure reason.

Applicable values are from EligibilityFailureReasonEnum:See failureReason.
Code so that your app gracefully handles any future changes to this list.
itemEligibilityResult array of ItemEligibilityResult Always This array contains information indicating whether each of the order's line items is eligible to be canceled.

An itemEligibilityResult container is returned for each line item in the order. The itemId and transactionId pair identify each line item.

Because cancellations happen at the order level, if the orderEligibilityResult.eligible value is true, the itemEligibilityResult.eligible value for each line item should also be true. However, if the orderEligibilityResult.eligible value is false, some itemEligibilityResult.eligible values may be true and others may be false (in a multiple line item order).
itemEligibilityResult.eligible boolean Always When set to true, the identified line item is eligible for cancellation.

The value of this field should always be true for all line items in the order if the value of the orderEligibilityResult.eligible is also true. However, if the value of the orderEligibilityResult.eligible is false, it is possible that some line items in the order may be eligible for cancellation, but other line items may not be eligible.
itemEligibilityResult
  .failureReason
array of string Conditionally A list containing one or more reasons why a line item has been found ineligible for cancellation. This field repeats for each applicable failure reason.

This field is not returned if the value of the itemEligibilityResult.eligible field is true.

Applicable values are from EligibilityFailureReasonEnum:See failureReason.
Code so that your app gracefully handles any future changes to this list.
itemEligibilityResult.itemId integer Always The unique eBay-assigned ID for an item listing that's associated with cancellation request.

Note: This field in conjunction with the transactionId field uniquely identify a line item within an order.
itemEligibilityResult
  .transactionId
integer Always The unique eBay-assigned ID for the transaction (purchase).

Note: This field in conjunction with the itemId field uniquely identify a line item within an order.
legacyOrderId string Always A unique eBay-assigned ID for the order being considered for cancellation.

Note: This is the value of the OrderID field returned by the Trading API's GetOrders call.



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: Check the eligibility of a cancellation

This operation is used to see if an order is eligible for a cancellation.

Description

Users may check to see if an order is eligible to be cancelled before actually attempting to create a cancellation request.

Input

The user must supply the legacyOrderId for the order being checked for cancellation eligibility. The legacyOrderId value is actually the OrderID value that is returned in the Trading API's GetOrders call.

URL format. See also the non-wrapped version of this URL.

POST https://api.ebay.com/post-order/v2/cancellation/check_eligibility
{
  "legacyOrderId":"170006494376-8756205007"
}

Output

A value of false in the eligible field indicates that the order is not eligible for cancellation. A value of CANCELLATION_EXIST in the failureReason array indicates that the order is not eligible for cancellation due to the fact that an order cancellation request already exists for the order. This particular order, 170006494376-8756205007, has only one order line item, which is identified by the itemId and transactionId pair under the itemEligibilityResult container. Eligibility status (and reason for ineligibility, if applicable) is returned for each line item in the order, since some line items in the order may be eligible to be cancelled and other line items might not be eligible to be cancelled.

JSON format.
{
  "legacyOrderId": "170006494376-8756205007",
  "eligible": false,
  "failureReason": [
    "CANCELLATION_EXIST"
  ],
  "itemEligibilityResult": [
    {
      "itemId": "170006494376",
      "transactionId": "8756205007",
      "eligible": false,
      "failureReason": [
        "CANCELLATION_EXIST"
      ]
    }
  ]
}



Change History

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