eBay Post-Order APIVersion 2

Create Cancellation

POST /post-order/v2/cancellation

This method initiates and performs an order cancellation on behalf of a seller and, if needed, you can also create an order cancellation on behalf of a buyer.

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 canceled.

Orders are eligible for cancellation based on various criteria, such as the cancellation cutoff period for the eBay marketplace on which the order was places. 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, you can notify the buyer or seller so they don't proceed with a cancellation.

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, respectively.

The call you make to approve a cancellation can also perform the cancellation, all with one call to POST /post-order/v2/cancellation.

Sellers can call POST /post-order/v2/cancellation to directly cancel the order (note that sellers should not use the POST /cancellation call in response to a buyer's request for cancellation).

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 can call POST /check_eligibility to get cancellation eligibility, POST /cancellation also returns eligibility information; 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 canceling the order at the request of the buyer.

Sellers can use the POST /create method in certain other scenarios as well. For example, after the order has shipped, the buyer and the seller can privately agree to a cancellation within the seller's 30 day cancellation window. (Note that this scenario might involve soliciting the help of the carrier to retrieve an in-transit shipment.)

Once the order is returned, use the POST /post-order/v2/cancellation/check_eligibility and POST /post-order/v2/cancellation calls to complete the cancellation in the normal way. When you follow this flow, the transaction technically ends with a cancellation where no return calls are used. The buyer is refunded the entire purchase price and the seller receives a final value fee credit.

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

For more information about using the Order Cancellation calls, see Handling Order Cancellations.

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 */
    "value": datetime
    },
"cancelReason": token,
"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 If set to true, the buyer has paid for the order and will receive a refund if the cancellation request is approved by the seller (in this case, you must populate the buyerPaidDate field in the request).

A value of false indicates that the buyer did not pay for the order, so is not eligible for a refund even if the cancellation request is approved by the seller.

This field is required only if the buyer requested to cancel the order cancellation and only if the buyer did not pay via PayPal.
buyerPaidDate DateTime Conditional The date and time that the buyer paid for the order. This field is required for only a buyer-requested cancellation and only if buyerPaid=true.
buyerPaidDate.value datetime Conditional The date and time defining the start or end of an action or event.

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: 2020-08-20T00:00:00.000Z
cancelReason token Optional The reason why the buyer or seller wants to cancel the order.

The value supplied must be one of the values returned in the eligibleCancelReason container returned by a POST /post-order/v2/cancellation/check_eligibility call.

Although not required, eBay recommends you populate this field. If omitted, the cancelReason value defaults to OTHER. The values specific to sellers are ADDRESS_ISSUES and OUT_OF_STOCK_OR_CANNOT_FULFILL.

Applicable values: See CancelReasonEnum
legacyOrderId string Required The unique eBay-assigned ID of the order that the buyer is attempting to cancel or that the seller is canceling.

Note: This is the value of the OrderID returned by a call to the Trading API GetOrders method.

relistLineItem array of RelistLineItem Optional Populate this array with a list of the items you want to relist from the order being canceled. eBay automatically relists the specified items when the seller marks them as received from the cancellation request.
relistLineItem.itemId integer Optional The unique eBay-assigned ID of the item you want to relist. The supplied ID must refer to one of the line items in the order referred to by the cancellation request.

Note: This field in conjunction with the transactionId field uniquely identify a line item within an order.

relistLineItem.quantity integer Optional The number of items you want to relist from the specified line item of the order. This number must be less-than or equal-to the number of the items in the order for that line item (as defined by the itemId).
relistLineItem.transactionId integer Optional The unique eBay-assigned ID for the order (transaction) associated with the cancellation.

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": [
        token
        /* More token nodes here */
      ],
    "failureReason": [
        token
        /* More token nodes here */
      ],
    "itemEligibilityResult": [
        { /* ItemEligibilityResult */
        "cancelQuantity": integer,
        "eligible": boolean,
        "failureReason": [
            token
            /* More token nodes here */
          ],
        "itemId": string,
        "transactionId": string
        }
        /* More ItemEligibilityResult nodes here */
      ],
    "legacyOrderId": string
    },
"warnings": [
    { /* ErrorData */
    "category": token,
    "domain": string,
    "errorId": integer,
    "httpStatusCode": integer,
    "longMessage": string,
    "message": string,
    "parameter": [
        { /* ErrorParameter */
        "name": string,
        "value": string
        }
        /* More ErrorParameter nodes here */
      ],
    "severity": token
    }
    /* 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. This field is not 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 canceled. Cancellation eligibility for each line item in the order is returned in a separate itemEligibilityResult container.
orderEligibilityResult
  .eligible
boolean Always If set to true, the specified order is eligible to be canceled. If false, the order is not eligible to be canceled.
orderEligibilityResult
  .eligibleCancelReason
array of token Conditionally A list of one or more reasons that a buyer or seller can give for canceling this order. This field is returned only if the value of the eligible field is true. The two enumeration values that are specifically for sellers are BUYER_ASKED_CANCEL and OUT_OF_STOCK_OR_CANNOT_FULFILL.
orderEligibilityResult
  .failureReason
array of token Conditionally A list of one or more reasons why this order has been found ineligible for cancellation. This field is returned only if the value of the eligible field is false. This field repeats for each applicable failure reason.
orderEligibilityResult
  .itemEligibilityResult
array of ItemEligibilityResult Always A list that indicates whether each of the order's line items is eligible to be canceled.

An itemEligibilityResult container is returned for each line item in the order.

Because cancellations happen at the order level, if the orderEligibilityResult.eligible value is true, the itemEligibilityResult.eligible value for each line item must also be true.

Note it's possible for the orderEligibilityResult.eligible value to return false while some itemEligibilityResult.eligible values return true (and others false) in a multiple line-item order.
orderEligibilityResult
  .itemEligibilityResult
  .cancelQuantity
integer Conditionally The number of items from the specified line item that are being canceled from the order.

This value must be equal-to or less-than the quantity of items ordered on the specified line item of the order.
orderEligibilityResult
  .itemEligibilityResult
  .eligible
boolean Always When set to true, the identified 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 token Conditionally A list containing one or more reasons why a line item has been found ineligible for cancellation. This field repeats for each applicable failure reason.

This field is not returned if the value of the itemEligibilityResult.eligible field is true.
orderEligibilityResult
  .itemEligibilityResult.itemId
string Always The unique eBay-assigned ID for a item in an order.

Note: This field in conjunction with the transactionId field uniquely identify a line item within an order.

orderEligibilityResult
  .itemEligibilityResult
  .transactionId
string Always The unique eBay-assigned ID for the order (transaction) associated with the cancellation.
orderEligibilityResult
  .legacyOrderId
string Always A unique eBay-assigned ID for the order being considered for cancellation.

Note: This is the value of the OrderID field returned by the Trading API's GetOrders call.

warnings array of ErrorData Conditionally This complex object returns a list of warnings generated by the request, if any exist.
warnings.category token Conditionally The category type for this error or warning.

The response contains one of three values:
  • APPLICATION: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.
  • SYSTEM: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors.
  • REQUEST: Used when there is an error with the request. Possible culprits are an authentication error or missing headers, syntactical errors, rate limiting factors, and so on.


Applicable values: See ErrorCategory
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.
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 Name of the parameter that caused the error.
warnings.parameter.value string Conditionally The value of the parameter that caused the error.
warnings.severity token 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: See ErrorSeverity



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": "170006494376-8756205007",
  "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, 1170006494376-8756205007, 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": "5000018282",
"orderEligibilityResult":
    { 
    "eligible": "true",
    "itemEligibilityResult": [
        { 
        "eligible": "true",
        "itemId": "1170006494376",
        "transactionId": "8756205007"
        }
      ],
    "legacyOrderId": "1170006494376-8756205007"
    }
}



Change History

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