Request an Order Cancellation

POST /post-order/v2/cancellation/

Used on behalf of a buyer to request a cancellation of the order. In this call, the order ID value, the cancel reason, and payment information is passed in to the request, and the response will contain cancellation eligibility information at the order and order line item levels.

Input

Request model

The following lists all fields that could be included in the request.

Resource URI (production)

POST https://api.ebay.com/post-order/v2/cancellation/

This call has no path or query parameters.

Supported HTTP request headers

Header	Description	Applicable Values
`Accept`	The media type for the response. Defaults to JSON (the only supported media type).	application/json
`Authorization`	The Authentication Token that is used to validate the caller has permission to access the eBay servers. Prefix a valid eBay token with the word "`TOKEN`". For more details, see Getting Tokens. Required	`TOKEN <authorization-token-value>`
`Content-Type`	The MIME type of the body of the request. Must be JSON. Required	`application/json`
`X-EBAY-C-MARKETPLACE-ID`	The global ID of the eBay site on which the transaction took place. Required	Currently, the marketplaces are limited to: `EBAY-US`, `EBAY-UK`, and `EBAY-DE`

Authorization

This call uses standard authorization tokens. See Making a Call for details.

Payload model

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

Request field descriptions

Input Container/Field	Type	Occurrence	Meaning
buyerPaid	boolean	Required	A value of `true` indicates that the buyer has paid for the order, and will receive a refund if the cancellation request is approved by the seller. If the buyer paid for the order, the buyerPaidDate should have the timestamp of when the order was paid. A value of `false` indicates that the buyer did not pay for the order so it not eligible for a refund if the cancellation request is approved by the seller.
buyerPaidDate	DateTime	Conditional	The date and time that the buyer paid for the order. This field must be included if the buyer paid for the order (buyerPaid=`true`).
buyerPaidDate.value	datetime	Optional	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 is cancelling the order. Although not required, it is recommended that the cancel reason be provided. If this field is omitted, the cancelReason value defaults to `OTHER`.
legacyOrderId	string	Required	The unique identifer of the order that the buyer is attempting to cancel. Note: This is the value of the OrderID field returned by the Trading API's GetOrders call.

Output

Response model

A successful call contains an HTTP status code of 200. See the HTTP Status Code Registry for a complete overview of HTTP status codes.

Note: The response information on this page applies to successful requests only. For information about the error fields and how to work with them, see Error Handling.

Payload model

{ /* CreateCancelResponse */
"cancelId": string,
"orderEligibilityResult":
    { /* OrderEligibilityResult */
    "eligible": boolean,
    "failureReason": [
        EligibilityFailureReasonEnum
        /* More EligibilityFailureReasonEnum nodes here */
      ],
    "itemEligibilityResult": [
        { /* ItemEligibilityResult */
        "eligible": boolean,
        "failureReason": [
            EligibilityFailureReasonEnum
            /* More EligibilityFailureReasonEnum 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 identifer of the newly created order cancellation request. This field will not be 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 cancelled. Cancellation eligibility for each order line item is shown in a separate itemEligibilityResult container.
orderEligibilityResult .eligible	boolean	Always	A value of `true` indicates that this order is eligible to be cancelled. A value of `false` indicates that this order is not eligible to be cancelled.
orderEligibilityResult .failureReason	array of EligibilityFailureReasonEnum	Conditionally	An array of one or more reasons why this order has been found ineligible for cancellation. This field will only be returned if the value of the eligible field is `false`. This field will repeat for each applicable failure reason. Applicable values: CANCEL_WINDOW_ELAPSED The time allowed for cancelling an order has expired. CANCELLATION_EXIST An order cancellation already exists for this order. CASE_EXIST A case or inquiry exists for one or more of the line items in this order. CROSS_SITE_ORDER Cross-border trade orders cannot be cancelled. EBAY_NOW_ORDER_STATUS eBay Now orders cannot be cancelled. FULL_REFUNDED_ORDER This value is only for internal use. IN_STORE_PICKUP_READY The In-store pickup order is ready, hence cancelling the order is not allowed. INSTORE_PICKUP_MADE The In-store pickup order has already been picked up by buyer, so the order cannot be cancelled. INTERNAL_SYSTEM_ERROR There has been a system error, please try the call again. INVALID_ORDER The order identifier is invalid. INVALID_USER The user identifier is invalid. PARTIAL_REFUNDED_ORDER This value is only for internal use. PAYPAL_DISPUTE_EXIST A PayPal case for one or more of the line items in the order already exists. RETURN_EXIST A return request for one or more of the line items in the order already exists. SHIPPED_ORDER The order (or order line item) has already been shipped, so the order cannot be cancelled. UNKNOWN The ineligibility reason is not determined. UNPAID_ORDER This value is only for internal use. UNSUPPORTED_ORDER This value is only for internal use. UNSUPPORTED_PAYMENT_METHOD This value is only for internal use. UNSUPPORTED_SITE The marketplace identifier is invalid.
orderEligibilityResult .itemEligibilityResult	array of ItemEligibilityResult	Always	This array contains eligibility information for each of the order's line items is eligible to be cancelled. The itemId and transactionId pair identify each line item. Since 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	A value of `true` indicates that this order 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 EligibilityFailureReasonEnum	Conditionally	An array of ne or more reasons why an order line item has been found ineligible for cancellation. This field will repeat for each applicable failure reason. This field will not be returned if the value of the itemEligibilityResult.eligible field is `true`. Applicable values: CANCEL_WINDOW_ELAPSED The time allowed for cancelling an order has expired. CANCELLATION_EXIST An order cancellation already exists for this order. CASE_EXIST A case or inquiry exists for one or more of the line items in this order. CROSS_SITE_ORDER Cross-border trade orders cannot be cancelled. EBAY_NOW_ORDER_STATUS eBay Now orders cannot be cancelled. FULL_REFUNDED_ORDER This value is only for internal use. IN_STORE_PICKUP_READY The In-store pickup order is ready, hence cancelling the order is not allowed. INSTORE_PICKUP_MADE The In-store pickup order has already been picked up by buyer, so the order cannot be cancelled. INTERNAL_SYSTEM_ERROR There has been a system error, please try the call again. INVALID_ORDER The order identifier is invalid. INVALID_USER The user identifier is invalid. PARTIAL_REFUNDED_ORDER This value is only for internal use. PAYPAL_DISPUTE_EXIST A PayPal case for one or more of the line items in the order already exists. RETURN_EXIST A return request for one or more of the line items in the order already exists. SHIPPED_ORDER The order (or order line item) has already been shipped, so the order cannot be cancelled. UNKNOWN The ineligibility reason is not determined. UNPAID_ORDER This value is only for internal use. UNSUPPORTED_ORDER This value is only for internal use. UNSUPPORTED_PAYMENT_METHOD This value is only for internal use. UNSUPPORTED_SITE The marketplace identifier is invalid.
orderEligibilityResult .itemEligibilityResult.itemId	integer	Always	The unique identifier of an item listing associated with cancellation request. Note: This field, along with the itemEligibilityResult.transactionId field, uniquely identifies an line item within the order.
orderEligibilityResult .itemEligibilityResult .transactionId	integer	Always	The unique identifier of the transaction (purchase). Note: This field, along with the itemEligibilityResult.itemId field, uniquely identifies a line item within an order.
orderEligibilityResult .legacyOrderId	string	Always	The unique identifer of 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 an API 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: Cancel an order

This operation creates a request to cancel an order.

Description

This is a buyer-facing operation that the buyer can use to request an order cancellation.

Input

Buyers must supply a reason for the cancellation request. Possible values are stored in the CANCEL_REASON_ENUM.
In this example, cancelReason is set to ORDER_MISTAKE, meaning the order does not match the listing description. This is known as a "significantly not as described" scenario, or SNAD for short.

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

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

Output

The output shows a failed cancellation request; the request came in after the allowed time frame or after the order had already been marked as shipped.
A successful cancellation request returns an HTTP code of 201, and a cancelId value.

JSON format. Also available is the .txt version of this JSON.

{
  "error": [
    {
      "errorId": 10005,
      "domain": "CancelSvcErrorDomain",
      "category": "APPLICATION",
      "message": "Eligibility Check failed"
    }
  ]
}

Change History

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