Handling Order Cancellations

The Post-Order API offers updated after-sale experiences that include new flows for cancelling orders. Both buyers and sellers can specify a variety of reasons to initiate the cancellation of an order, and both paid and unpaid orders can be cancelled. Buyers must initiate an order cancellation within one hour after purchase/commit to buy. In all instances, a buyer-initiated cancellation requires the seller's approval.

Topics:

Buyer-Requested Cancellations

Seller-Initiated Cancellations

Other Cancellations

Managing Cancellations

If you're currently handling order cancellations using the Trading API, you will need to make changes to your flows to take advantage of the updated after-sale capabilities offered by the Post-Order API.

Currently, the cancellation operations in the Post-Order API act upon an entire order, so a single line item within a multiple line item order cannot be cancelled. See Cancellations in the Fall 2014 Seller Update for details on the updated cancellation functionality.

Important! A cancellation initiated by a buyer does not count as a defect against the seller, as long as the seller properly clears the cancellation. The seller must handle the request through the appropriate eBay flows so eBay can verify the buyer request and count the cancellation as "buyer requested." In this flow, eBay doesn't count the action as a seller defect.

However, eBay Seller Standards do take into account seller-initiated cancellations for out-of-stock reasons, and this can affect a seller's defect rating.

Buyer-Requested Cancellations

Buyers can initiate an order cancellation through My eBay Web flows, as long as the cancellation is requested within the allotted time frame and the the order has not yet been marked as shipped by the seller. The seller must approve the cancellation before it can be processed, but once approved, eBay automatically reverses the transaction in the buyer and seller accounts. If the order was paid for through PayPal, the buyer is automatically refunded for the purchase, and the Final Value Fee is automatically refunded to the seller's account.

For each marketplace site, eBay policy defines the time frame in which cancellations can be requested by the buyer. For example, the eBay US site has a time frame of one hour after purchase/commit to buy. After the allotted time passes, the ability for the buyer to initiate the cancellation request expires, although the buyer can still contact and ask the seller to cancel the order on the buyer's behalf. If the seller agrees to cancel an order on the buyer's behalf, it will not count as a seller defect.

Buyer-requested cancellation flow
 Buyer-Requested Cancellation Flow

Sellers should regularly monitor their orders for cancellation requests, and eBay encourages sellers to approve all buyer-requested cancellations. By agreeing to a buyer's cancellation request, the seller can take advantage of eBay's streamlined cancellation process, and avoid the possibility of dealing with a possible return of the same item. Buyer-initiated cancellation requests will never count as a defect on the seller's record.

Discovering Buyer Cancellation Requests

Orders can be monitored for buyer cancellation requests by using either the GET /post-order/v2/cancellation/search call of the Post-Order API or the GetOrders call of the Trading API:

Note: Sellers are also notified via email of any buyer cancellation requests.

Approving Buyer-Requested Cancellations

To approve and process a buyer-requested cancellation:

  1. Check the cancellation eligibility of the order. (Optional)

    While eBay rejects cancellation requests that are not eligible due to the timing of the request, you can programmatically ensure an order is eligible for a cancellation by calling POST /post-order/v2/cancellation/check_eligibility.

  2. Get the cancelId value that you previously captured from My eBay, the eBay-generated email, or the GET /post-order/v2/cancellation/search call.
  3. Approve and perform the cancellation.

    Call POST /post-order/v2/cancellation/{cancelId}/approve to cancel the specified order and initiate eBay's automatic cancellation processing. If the order was paid for through PayPal, the buyer is automatically refunded for the purchase, and the Final Value Fee is automatically refunded to the seller's account. If PayPal is not the method of payment, the seller is expected to issue a refund using the systems provided by the bank or payment processor used in the original purchase. A refund is not applicable if the buyer never paid for the order.

    There is no Trading API call specifically designed to approve or reject a buyer-initiated cancellation request. However, it is still possible for the seller to use the AddDispute call of the Trading API to cancel the order on behalf of the buyer. See the AddDispute call reference page for more information on cancelling an order on the buyer's behalf. Generally, in the AddDispute call request, the seller would want to set the DisputeReason value to TransactionMutuallyCanceled and the DisputeExplanation value to BuyerNoLongerWantsItem or BuyerPurchasingMistake, whichever value more closely matches the buyer's reason for cancelling the order.

Rejecting Buyer-Requested Cancellations

While sellers are encouraged to approve all valid buyer-requested cancellations, there might be reasons to reject a request. For example, if you have already shipped one or more packages associated with an order, you will want to reject the cancellation request.

To reject a buyer cancellation request:

  1. Get the cancelId value that you previously captured from My eBay, the eBay-generated email, or the GET /post-order/v2/cancellation/search call.
  2. Reject the cancellation request.

    Call POST /post-order/v2/cancellation/{cancelId}/reject to reject the cancellation request. Although not required, it is a best practice to include the shipment date and tracking number if the order has indeed already been shipped. This will indicate to the buyer that the order could not be cancelled since it has already been shipped. eBay will also send the buyer a notification that the cancellation request was declined.

  3. Fulfill the order.

Note: A seller need not do anything to reject a buyer's request to cancel an order, as the request will time out after three business days and the order cancellation will be automatically rejected. However, to preserve good customer relations, the best choice for a seller is to always communicate your intentions to your buyers.

Seller-Initiated Cancellations

Sellers can cancel an order up to 30 days after checkout, as long as they haven't yet shipped the order.

There are several scenarios where a seller might want to cancel an order. For example, the buyer might have contacted the seller directly to request a cancellation, or the seller might realize the purchased item is out of stock. The "out-of-stock" cancellation reason will result in a defect on the seller's account, but there will be no negative effect on the seller's account if the seller is only cancelling the order at the request of the buyer. Sellers must make sure they give the correct cancellation reason.

Seller-initiated cancellation flow
 Seller-Initiated Cancellation Flow

Note: If the buyer requests a cancellation using a method other than the eBay Web flow, and the seller decides against cancelling the order, the seller should inform the buyer of their decision by following the steps outlined in Rejecting Buyer-Requested Cancellations.

To cancel an order:

  1. Get the Order ID with a call to GetOrders.

    Note that the Trading API OrderID field is named legacyOrderId in the Post-Order API.

  2. Check the cancellation eligibility of the order. (Optional)

    Call POST /post-order/v2/cancellation/check_eligibility to ensure that the order is eligible for cancellation.

  3. Cancel the order.

    Call POST /post-order/v2/cancellation and set the cancelReason to one of the following two values:

    • BUYER_CANCEL_OR_ADDRESS_ISSUE: This value is given by the seller if the seller is cancelling the order on behalf of the buyer, or if the buyer has provided the seller with an undeliverable/bad address. This cancel reason will not result in a defect on the seller's record.
    • OUT_OF_STOCK_OR_CANNOT_FULFILL: This value indicates that the seller's reason for cancelling the order is that the item is out of stock or there is another fulfillment issue. This cancel reason will result in a defect on the seller's record.

    If the order was paid for, and PayPal was the payment method, eBay automatically issues a full refund to the buyer; otherwise the seller is expected to issue a refund by following the appropriate actions with the bank or payment processor used to receive the funds.

Other Cancellations

There is no Trading API call specifically designed to approve or reject a buyer-initiated cancellation request. However, it is still possible for the seller to use the AddDispute call of the Trading API to cancel the order on behalf of the buyer. See the AddDispute call reference page for more information on cancelling an order on the buyer's behalf. Generally, in the AddDispute call request, the seller would want to set the DisputeReason value to TransactionMutuallyCanceled and the DisputeExplanation value to BuyerNoLongerWantsItem or BuyerPurchasingMistake, whichever value more closely matches the buyer's reason for cancelling the order.

The Post-Order API currently addresses only full-order cancellations, meaning that individual line items within a multiple line item order cannot be cancelled using this API. For partial-order (or line item) cancellations, sellers can use the Trading API to cancel a single line item within a multiple line item order. To do so, call AddDispute from the Trading API. If the seller is cancelling the line item at the request of the seller, the DisputeReason value should be set to TransactionMutuallyCanceled and the DisputeExplanation value set to BuyerNoLongerWantsItem or BuyerPurchasingMistake, whichever value more closely matches the buyer's reason for cancelling the order. If the seller is cancelling the line item due to being out of stock on the item, the DisputeReason value should again be set to TransactionMutuallyCanceled, but the DisputeExplanation value must be set to SellerRanOutOfStock. Again, the out-of-stock scenario will result in a defect on the seller's account. If PayPal is the payment method, a full refund can be issued using the PayPal API. For other payment methods, issue a refund using the method appropriate to the original transaction.

Note: Creating a mutual cancellation ensures that the appropriate Final Value Fee is refunded to the seller and the paid transaction or order status is marked as cancelled, even in the case where the seller issues a refund after the new cancellation system times out waiting for the seller's approval. eBay's Seller Standards do not interpret this scenario as an out-of-stock condition, so it does not count as a defect against the seller.

Managing Cancellations

Use calls from the Post-Order API to manage cancellations and retrieve details on specific cancellations. The following list offers an overview of the operations that let you manage cancellations:

See the Post-Order API Call Reference for more information.

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.