Create Cancellation Request

POST /post-order/v2/cancellation

This method initiates an order cancellation on behalf of a seller and, if needed, you can also create an order cancellation on behalf of a buyer.Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including this method. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signature to be included in the HTTP payload.

The buyer use-case for this method provides a way for you to programmatically test your cancellation flows in the Sandbox, as buyers in a production environment normally request order cancellations via the eBay web flows.

Tip: Call POST /post-order/v2/cancellation/check_eligibility before calling this method to ensure the order being considered is eligible to be cancelled.

Orders are eligible for cancellation based on various criteria, such as the cancellation cutoff period for the eBay marketplace on which the order was placed. As an example, the cutoff for EBAY_US is 1 hour after purchase, after which the order becomes ineligible for cancellation. If the order is not eligible for cancellation, you can notify the buyer or seller so they don't proceed with a cancellation request.

When a buyer cancels an order after purchase, it is up to the seller to either reject or approve it the request by calling POST /post-order/v2/cancellation/{cancelId}/reject or POST /post-order/v2/cancellation/{cancelId}/approve methods, respectively.

Sellers can call 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 are unable to fulfill the order for up to 30 days after the sale. While the POST /post-order/v2/cancellation/check_eligibility method can be used to check for order cancellation eligibility, the POST /post-order/v2/cancellation method also returns eligibility information in the response. If the order's cancellation eligibility has changed, examine the failureReason field for why the cancellation failed.

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. Also, note there is no negative effect on the seller's account if the seller is cancelling the order at the request of the buyer.

Note: Currently, an entire eligible order can be cancelled, but not individual order line items. For the order to be eligible for cancellation, all of its order line items must be eligible.

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 */
    "formattedValue": string,
    "value": datetime
    },
"cancelReason": string,
"legacyOrderId": string,
"relistLineItem": [
    { /* RelistLineItem */
    "itemId": integer,
    "quantity": integer,
    "transactionId": integer
    }
    /* More RelistLineItem nodes here */
  ]
}

Request field descriptions

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": [
        string
        /* More string nodes here */
      ],
    "failureReason": [
        string
        /* More string nodes here */
      ],
    "itemEligibilityResult": [
        { /* ItemEligibilityResult */
        "cancelQuantity": integer,
        "eligible": boolean,
        "failureReason": [
            string
            /* More string nodes here */
          ],
        "itemId": string,
        "transactionId": string
        }
        /* More ItemEligibilityResult nodes here */
      ],
    "legacyOrderId": string
    },
"warnings": [
    { /* ErrorData */
    "category": string,
    "domain": string,
    "errorId": integer,
    "httpStatusCode": integer,
    "longMessage": string,
    "message": string,
    "parameter": [
        { /* ErrorParameter */
        "name": string,
        "value": string
        }
        /* More ErrorParameter nodes here */
      ],
    "severity": string
    }
    /* More ErrorData nodes here */
  ]
}

Response field descriptions

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.

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": "1**********6-8********7",
  "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, 1***********6-8********7, 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": "5********2",
"orderEligibilityResult":
    { 
    "eligible": "true",
    "itemEligibilityResult": [
        { 
        "eligible": "true",
        "itemId": "1**********76",
        "transactionId": "8********7"
        }
      ],
    "legacyOrderId": "1***********6-8********7"
    }
}

Change History