eBay Post-Order APIVersion 2

Submit Cancellation Request

POST /post-order/v2/cancellation

Use this call to request an order cancellation on behalf of a buyer, or to initiate and perform an order cancellation on behalf of a seller. The buyer case is for testing in the Sandbox, as buyers in a production environment normally request order cancellations via the eBay website.

Note: It is highly recommended that before issuing this call, you use the POST /post-order/v2/cancellation/check_eligibility call to determine if the order is eligible to be canceled, based on criteria such as the cancellation cutoff period for the eBay marketplace (for example, the cutoff for EBAY_US is 1 hour after purchase). If the order is not eligible, you can inform the buyer or seller before they decide to request or perform a cancellation, respectively.
When a buyer wants to cancel an order after purchase, it will be up to the seller to either reject the request with the POST /post-order/v2/cancellation/{cancelId}/reject call, or approve it with the POST /post-order/v2/cancellation/{cancelId}/approve call. The approve call also performs the cancellation, so it is unnecessary to issue POST /post-order/v2/cancellation again. Sellers do not use this call in response to a buyer request for cancellation.

For a seller, issue POST /post-order/v2/cancellation to directly cancel the order. Sellers may cancel an order if they run out of stock on an item and cannot fulfill the order, up to 30 days after the sale. Like the POST /post-order/v2/cancellation/check_eligibility call, this call also returns eligibility information; if the order's cancellation eligibility has changed, you can determine why by examining the failureReason field returned by this call at the order and line item levels.

Note: Sellers may cancel an order up to 30 days after the sale. However, if a seller has run out of stock on an item and cannot fulfill the order, a cancellation can result in a defect on the seller's account. There will be no negative effect on the seller's account if the seller is canceling the order at the request of the buyer.
Sellers can use this call in certain other scenarios as well. After the order has shipped, the buyer and the seller can privately agree to a cancellation within the seller's 30 day cancellation window. (This might also involve soliciting the help of the carrier to retrieve an in-transit shipment.) Once the order is returned, you can then use the POST /post-order/v2/cancellation/check_eligibility and POST /post-order/v2/cancellation calls to complete the cancellation in the normal way. Because only cancellation calls are used, this is not a return. The buyer is refunded the entire purchase price and the seller receives a final value fee credit.

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

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.

{ /* CreateCancelRequest */
"buyerPaid": boolean,
"buyerPaidDate":
    { /* DateTime */
    "value": datetime
    },
"cancelReason": token,
"legacyOrderId": string
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
buyerPaid boolean Conditional If set to true, the buyer has paid for the order and will receive a refund if the cancellation request is approved by the seller (in this case, you must populate the buyerPaidDate field in the request).

A value of false indicates that the buyer did not pay for the order, so is not eligible for a refund even if the cancellation request is approved by the seller.

This field is required only if the buyer requested to cancel the order cancellation and only if the buyer did not pay via PayPal.
buyerPaidDate DateTime Conditional The date and time that the buyer paid for the order. This field is required for only a buyer-requested cancellation and only if buyerPaid=true.
buyerPaidDate.value datetime Conditional 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.
cancelReason token Optional The reason why the buyer or seller wants to cancel the order. This must be one of the values returned in the eligibleCancelReason container returned by a POST /post-order/v2/cancellation/check_eligibility call.

Although not required, eBAy recommends you populate this field. If omitted, the cancelReason value defaults to OTHER. The values specific to sellers are BUYER_CANCEL_OR_ADDRESS_ISSUE and OUT_OF_STOCK_OR_CANNOT_FULFILL.

Applicable values: See CancelReasonEnum
legacyOrderId string Required The unique eBay-assigned ID of the order that the buyer is attempting to cancel or that the seller is canceling.

Note: This is the value of the OrderID 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 CreateCancelResponse 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

{ /* CreateCancelResponse */
"cancelId": string,
"orderEligibilityResult":
    { /* 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
cancelId string Conditionally The unique eBay-assigned ID for the order cancellation. This field is not returned if the order is not eligible for cancellation.
orderEligibilityResult OrderEligibilityResult Always This container indicates whether or not the order (and the order's line items) is eligible to be canceled. Cancellation eligibility for each line item in the order is returned in a separate itemEligibilityResult container.
orderEligibilityResult
  .eligible
boolean Always If set to true, this order is eligible to be canceled. If false, this order is not eligible to be canceled.
orderEligibilityResult
  .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
orderEligibilityResult
  .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.
orderEligibilityResult
  .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).
orderEligibilityResult
  .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.
orderEligibilityResult
  .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.
orderEligibilityResult
  .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.
orderEligibilityResult
  .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.
orderEligibilityResult
  .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: Request an Order Cancellation

This operation creates a request to cancel an order.

Description

This operation is used by the buyer to request the cancellation of an order.

Input

The buyer must supply the legacyOrderId for the order being cancelled, and a reason for the cancellation request. The legacyOrderId value is actually the OrderID value that is returned in the Trading API's GetOrders call. Possible values for cancelReason are stored in the CANCEL_REASON_ENUM type. In this example, cancelReason is set to ORDER_MISTAKE, meaning the buyer purchased the wrong item, or just purchased the item by mistake.

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

POST https://api.ebay.com/post-order/v2/cancellation/
{
  "legacyOrderId": "170006494376-8756205007",
  "cancelReason":"ORDER_MISTAKE",
  "buyerPaid": "false"
}

Output

The appearance of a cancelId value in the output indicates that the order cancellation request was successfully created. This particular order, 1170006494376-8756205007, had only one order line item, which is identified by the itemId and transactionId pair under the itemEligibilityResult container. Now that the cancellation request has been successfully created, it is now up to the seller to accept or reject the cancellation request.

JSON format.
{ 
"cancelId": "5000018282",
"orderEligibilityResult":
    { 
    "eligible": "true",
    "itemEligibilityResult": [
        { 
        "eligible": "true",
        "itemId": "1170006494376",
        "transactionId": "8756205007"
        }
      ],
    "legacyOrderId": "1170006494376-8756205007"
    }
}



Change History

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