Handling order cancellations

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

If you've historically handled order cancellations using the Trading API, you will need to make changes to your flows to take advantage of the 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 canceled.

However, eBay Seller Standards consider 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 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, the buyer is automatically refunded for the purchase by eBay, and the Final Value Fee is automatically refunded to the seller's account. eBay will charge the seller to get reimbursed for the refund that eBay issued to the buyer.

For each marketplace, 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/commitment 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

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:

• Call GET /post-order/v2/cancellation/search and use the creation_date_range_from and creation_date_range_to query parameters to discover order cancellation requests that were initiated within that time period. Detailed information on each order cancellation request initiated during that time period will be returned in the response. Newly opened cancel requests (awaiting seller approval) will have a cancelStatus value of CANCEL_REQUESTED.
  
  For all newly created cancellation requests, it is a good idea to capture the cancelId value in the response, as this value will be required when using any Post-Order API cancel call that acts upon a specific cancellation request.
• Call GetOrders and set the OrderStatus field in the request to CancelPending. In addition, you can use the CreateTimeFrom and CreateTimeTo date filters fields to narrow your search. Look for an Order.CancelStatus field in the response, and its value should be CancelRequested. If this field is returned, the Order.CancelDetail container should also be returned, and this container will give more information about the cancellation request, including the reason why the buyer is requesting the cancellation.
  
  One data point that is missing from the GetOrders response is a Cancel ID value, so sellers will need to get this ID from My eBay, through an eBay-generated email, or using the GET /post-order/v2/cancellation/search call. A Cancel ID value is needed to approve or reject a cancellation request programmatically.

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. The buyer is automatically refunded for the purchase, and the Final Value Fee is automatically refunded to the seller's account. A refund is not applicable if the buyer never paid for 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 canceled since it has already been shipped. eBay will also send the buyer a notification that the cancellation request was declined.

3. Fulfill the order.

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.

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 canceling the order at the request of the buyer. Sellers must make sure they give the correct cancellation reason.

 Seller-Initiated Cancellation Flow

If the buyer requests a cancellation using a method other than the eBay Web flow, and the seller decides against canceling 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 values:

   • ADDRESS_ISSUES: This value is given by the seller if the buyer has provided the seller with an undeliverable/bad shipping address. This cancel reason will not result in a defect on the seller's record.

   • BUYER_ASKED_CANCEL: This value is given by the seller if the seller is canceling the order on behalf of the buyer. This cancel reason will not result in a defect on the seller's record.

   • ORDER_UNPAID: This enumeration value indicates that the seller initiated the order cancellation request because the buyer has not paid for the order in a timely manner.

   • This cancellation reason can only be given by the seller and not the buyer.

   • OUT_OF_STOCK_OR_CANNOT_FULFILL: This value is given by the seller if the seller is canceling the order due to the item being out of stock or another fulfillment issue. This cancel reason will result in a defect on the seller's record.

   If the order was paid for, eBay automatically issues a full refund to the buyer.

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:

• POST /post-order/v2/cancellation
  For a buyer, this call creates a cancellation request that must be approved by the seller. For a seller, this call actually cancels the order.
• POST /post-order/v2/cancellation/check_eligibility
  Displays whether a specified order is eligible for cancellation, and the response also include valid cancellation reasons.
• GET /post-order/v2/cancellation/search
  Finds one or more cancellations of orders based on a variety of search criteria.
• POST /post-order/v2/cancellation/{cancelId}/approve
  Sellers use this call to approve a buyer-initiated cancellation request.
• GET /post-order/v2/cancellation/{cancelId}
  Retrieves the details of a specific cancellation request, including item details and the cancellation's history log.
• POST /post-order/v2/cancellation/{cancelId}/confirm
  A buyer-facing call that can be used to indicate that the buyer has received the refund for the specified cancellation.
• POST /post-order/v2/cancellation/{cancelId}/reject
  Sellers use this call to reject a buyer-initiated cancellation request.

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