eBay Post-Order APIVersion 2.7.3
 

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



Input Container/Field Type Occurrence Meaning
buyerPaid boolean Conditional This field should be included and set to true if the buyer has paid for the order, and is eligible for a refund if the cancellation request is approved by the seller. If the buyer has paid for the order, the payment date should also be included in the buyerPaidDate field.

If the buyer has not paid for an order, this field should be included and set to false. In this case, the buyer is not eligible for a refund even if the cancellation request is approved by the seller.
buyerPaidDate DateTime Conditional The timestamp in this container indicates that the buyer paid for the order. If the buyer has not paid for the order, this container is not applicable.
buyerPaidDate.formattedValue string Optional Reserved for future use.
buyerPaidDate.value datetime Conditional This timestamp indicates the date and time when an action or event occurred.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-03-20T00:00:00.000Z
cancelReason string Optional This field is used to indicate the reason why the buyer or seller wants to cancel the order. One of the enumeration values defined in the CancelReasonEnum type definition must be used in this field. The descriptions for each enumeration value in that type definition will indicate whether the cancel reason is intended for the buyer or seller.

Although not required, it is highly recommended that a cancel reason is provided.

Applicable values: See CancelReasonEnum
legacyOrderId string Required A unique eBay-assigned ID for the order being considered for cancellation.

Note: The unique identifier of an order changes as the order goes from unpaid to paid, so the IDs for both unpaid and paid orders are supported in this field. For orders where payment has been made, the ID for the paid order should be used.

relistLineItem array of RelistLineItem Optional This array can be used for seller-initiated order cancellation requests if the seller wishes to relist one or more line items that are a part of the order being cancelled. Once the order cancellation is successfully processed by eBay, the line item(s) will be relisted automatically.
relistLineItem.itemId integer Conditional The unique identifier of the eBay listing where the line item was purchased. This field is used in conjunction with the transactionId field to identify a line item within an order.
relistLineItem.quantity integer Conditional The quantity you want to relist from the specified line item of the order. This number must be less-than or equal to purchased quantity of the line item.
relistLineItem.transactionId integer Conditional The unique identifier of the purchase transaction. This value is created right when the buyer is committed to buying the item, whether that buyer uses a 'Buy it Now' capability, is the winning bidder of an auction, or the buyer's Best Offer is accepted by the seller. This field is used in conjunction with the itemId field to identify a line item within an order.

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



Output Container/Field Type Occurrence Meaning
cancelId string Conditionally The unique eBay-assigned ID for the order cancellation request. This field is returned unless the order is not eligible for cancellation, or if an error is triggered with the POST /post-order/v2/cancellation request.
orderEligibilityResult OrderEligibilityResult Always This container indicates whether or not the order is eligible to be cancelled. Cancellation eligibility for each line item in the order is returned in a separate itemEligibilityResult container.
orderEligibilityResult
  .eligible
boolean Always If this value is returned as true, the specified order is eligible to be cancelled. If this value is returned as false, the order is not eligible to be cancelled. One or more reasons why an order may not be eligible for cancellation will be shown in the failureReason array.
orderEligibilityResult
  .eligibleCancelReason
array of string Conditionally A list of one or more reasons that a buyer or seller can give for cancelling this order. This field is returned only if the value of the eligible field is true.

Supported enumeration values representing buyer and seller order cancellation reasons can be found in the CancelReasonEnum type definition.
orderEligibilityResult
  .failureReason
array of string Conditionally A list of one or more reasons why this order has been found to be ineligible for cancellation. This field is returned only if the value of the eligible field is false.

The full list of reasons why an order may not be eligible for cancellation can be found in the EligibilityFailureReasonEnum type definition.
orderEligibilityResult
  .itemEligibilityResult
array of ItemEligibilityResult Always A list of all line items in the order and whether or not each line item is eligible to be cancelled. Because only full-order cancellations are supported at this time, if the orderEligibilityResult.eligible value is returned as true, the itemEligibilityResult.eligible value for all line items within the order will also be returned as true.

Note it's possible for the orderEligibilityResult.eligible value to be returned as false while one or more itemEligibilityResult.eligible values may be returned as true.
orderEligibilityResult
  .itemEligibilityResult
  .cancelQuantity
integer Conditionally The quantity of the specified order line item that is being cancelled.

This value must be equal-to or less-than the quantity ordered for the specified order line item.
orderEligibilityResult
  .itemEligibilityResult
  .eligible
boolean Always If the value of this field is returned as true, the corresponding 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 corresponding orderEligibilityResult.eligible field is also true. However, if the value of the orderEligibilityResult.eligible field 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 An array of one or more reasons why a line item has been found to be ineligible for cancellation. This array is only returned if the value of the itemEligibilityResult.eligible field is false.

The full list of reasons why an order may not be eligible for cancellation can be found in the EligibilityFailureReasonEnum type definition.
orderEligibilityResult
  .itemEligibilityResult.itemId
string Always The unique identifier for the eBay listing where the item was purchased. This field is used in conjunction with the transactionId field to identify a line item within an order.
orderEligibilityResult
  .itemEligibilityResult
  .transactionId
string Always The unique identifier for the purchase of the item. This value is created right when the buyer is committed to buying the item, whether that buyer uses a 'Buy it Now' capability, is the winning bidder of an auction, or the buyer's Best Offer is accepted by the seller. This field is used in conjunction with the itemId field to identify a line item within an order.
orderEligibilityResult
  .legacyOrderId
string Always A unique eBay-assigned ID for the order being considered for cancellation.

Note: The unique identifier of an order changes as the order goes from unpaid to paid, so the IDs for both unpaid and paid orders may be returned in this field based on payment status.

warnings array of ErrorData Conditionally This array is returned if the POST /post-order/v2/cancellation request triggers any errors or warnings.
warnings.category string Conditionally The category type for this error or warning.

The value returned in this field will be one of the values defined in the ErrorCategory type, and these values are discussed below.

Applicable values are from ErrorCategory:

APPLICATION
This enumeration value indicates that the corresponding error or warning was caused by faulty application logic.
REQUEST
This enumeration value indicates that the corresponding error or warning was caused by an issue with the request payload.
SYSTEM
This enumeration value indicates that the corresponding error was a system error.

Code so that your app gracefully handles any future changes to this list.
warnings.domain string Conditionally Name of the domain, primary system or service, or application where the error occurred.
warnings.errorId integer Conditionally A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Error messages and their corresponding IDs can be found on the Errors by Number page.
warnings.httpStatusCode integer Conditionally The HTTP status code that resulted from the request.
warnings.longMessage string Conditionally A more detailed explanation of the error than given in the message error field.
warnings.message string Conditionally Information on how to correct the problem, where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the locale of the request.
warnings.parameter array of ErrorParameter Conditionally This optional list of name/value pairs that contain context-specific ErrorParameter objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.
warnings.parameter.name string Conditionally The name of the request parameter that triggered an error or warning.
warnings.parameter.value string Conditionally The value of the request parameter that triggered an error or warning.
warnings.severity string Conditionally The severity can be either a WARNING or an ERROR, where a warning does not stop the processing of the request while an error does.

While you must fix errors before the service will process your request, you should also fix all warnings to ensure your application runs as designed.

Applicable values are from ErrorSeverity:

ERROR
This enumeration value indicates that a "fatal" error occurred and the request was not successfully processed.
WARNING
This enumeration value indicates that a "warning," was triggered. With warnings, the request may have been partially successful, but the user will definitely want to know more about the issue that triggered the warning, and a subsequent request may be needed.

Code so that your app gracefully handles any future changes to this list.
null



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

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