eBay Post-Order APIVersion 2.6

Check Cancellation Eligibility

POST /post-order/v2/cancellation/check_eligibility

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

Provide the OrderID value in the legacyOrderId request field. The response contains information on cancellation eligibility at the order and order line-item levels.

Note: Currently, only an entire order can be canceled; the cancellation of individual line items in the order is not supported.

For an order to be eligible for cancellation, all of the line items in the order must be eligible for cancellation.

For more information about using the Order Cancellation calls, see Handling Order Cancellations.

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: The order ID value changes as an order goes from the unpaid to the paid state.


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": [
    token
    /* More token nodes here */
  ],
"itemEligibilityResult": [
    { /* ItemEligibilityResult */
    "cancelQuantity": integer,
    "eligible": boolean,
    "failureReason": [
        token
        /* More token nodes here */
      ],
    "itemId": string,
    "transactionId": string
    }
    /* More ItemEligibilityResult nodes here */
  ],
"legacyOrderId": string
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
eligible boolean Always If set to true, the specified order is eligible to be canceled. If false, the 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_ASKED_CANCEL and OUT_OF_STOCK_OR_CANNOT_FULFILL.
failureReason array of token 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.
itemEligibilityResult array of ItemEligibilityResult Always A list that indicates 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.

Because cancellations happen at the order level, if the orderEligibilityResult.eligible value is true, the itemEligibilityResult.eligible value for each line item must also be true.

Note it's possible for the orderEligibilityResult.eligible value to return false while some itemEligibilityResult.eligible values return true (and others false) in a multiple line-item order.
itemEligibilityResult
  .cancelQuantity
integer Conditionally The number of items from the specified line item that are being canceled from the order.

This value must be equal-to or less-than the quantity of items ordered on the specified line item of the 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 token 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.
itemEligibilityResult.itemId string Always 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.
itemEligibilityResult
  .transactionId
string Always 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.
legacyOrderId string Always A unique eBay-assigned ID for the order being considered for cancellation.

Note: The order ID value changes as an order goes from the unpaid to the paid state.

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