eBay Post-Order APIVersion 2

Search Cancellations

GET /post-order/v2/cancellation/search

Use this method to search for and retrieve one or more order cancellations.

Specify the search criteria using query parameters.

The result set is paginated and returned one page at a time. Depending on the settings of the limit and offset parameters, you might need to issue several calls to in order to retrieve all the cancellations in the result set.

Input

See also Samples.

Resource URI (production)

GET https://api.ebay.com/post-order/v2/cancellation/search?
  cancel_id=string&
  creation_date_range_from=string&
  creation_date_range_to=string&
  item_id=string&
  legacy_order_id=string&
  limit=string&
  offset=string&
  role=UserRoleFilterEnum&
  sort=CancelSortField&
  transaction_id=string

URI parameters

Parameter Type Required? Meaning
cancel_id string Optional The identifier of a specific cancellation. If you supply this parameter, any other query parameters you include are ignored and summary information for the specified cancellation will be returned.
creation_date_range_from string Optional Use the creation_date_range_from and creation_date_range_to query parameters to retrieve cancellation requests that were created during a specific time range.

Set creation_date_range_from to the beginning of the time range and set creation_date_range_to to a date that's after the start date. Do not set the start date more than 18 months in the past.

If you set creation_date_range_from but do not set creation_date_range_to, the service searches through all cancellation requests created at or after the specified time, and searches forward 90 days from there.

This parameter takes an ISO 8601-formatted date. For example:
2015-05-15T03:00:00.000Z.
creation_date_range_to string Optional Use creation_date_range_to in conjunction with the creation_date_range_from query parameter. See creation_date_range_to for details on how to set this parameter.

This parameter takes an ISO 8601-formatted date.
item_id string Optional The unique eBay-assigned ID of an item listing associated with a cancellation to be returned.

Note: This parameter must be combined with the transaction_id parameter to uniquely identify a specific order line item associated with a cancellation. However, for multiple-quantity, fixed-price listings, it is also possible to include just item_id as a query parameter. In this case, any and all cancellations made against the listing by any and all buyers are returned.

legacy_order_id string Optional The unique eBay-assigned ID of an order. This ID value must be associated with a cancellation that has been returned.

Note: The legacy_order_id value is the value of the OrderID field that's returned by the GetOrders call in the Trading API.

limit string Optional Specifies the maximum number of cancellations to return on a page in the paginated response.
offset string Optional Specifies the number of items to skip in the result set before returning the first item in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.

Default: 0

role string --- Use this query parameter to filter the results based on the user role. Set this parameter to either BUYER or SELLER.

Default: SELLER

Applicable values are from UserRoleFilterEnum.
sort string Optional This query parameter specifies how you want to sort the cancellation records returned by the request.

Specify a value that consists of the field to sort by preceded by a character that indicates the direction in which you'd like the fields to be sorted. A value of + (plus sign) indicates that the returned cancellations will be sorted in ascending order based on the specified field. A value of - (minus sign) indicates descending order.

Applicable values:
  • +CANCEL_ID or -CANCEL_ID
    Sorts the response by the cancelId field in ascending or descending order, respectively.
  • +CANCEL_REQUEST_DATE or -CANCEL_REQUEST_DATE
    Sorts the response by the cancelRequestDate field in ascending or descending order, respectively.

Note: The CancelSortField type provides the underlying data structure used by this parameter; however, do not use that structure for the input to this parameter.



Applicable values are from CancelSortField.
transaction_id string Optional The unique eBay-assigned ID of the purchase associated with a cancellation to be returned.

Note: If you supply this query parameter, you must also supply the item_id query parameter to uniquely identify an order line item. If you use transaction_id without supplying an item_id, this parameter is ignored.



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

This call has no request payload.


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 FindCancelResponse 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

{ /* FindCancelResponse */
"cancellations": [
    { /* CancelSummary */
    "buyerLoginName": string,
    "buyerResponseDueDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "cancelCloseDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "cancelCloseReason": token,
    "cancelId": string,
    "cancelReason": token,
    "cancelRequestDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "cancelState": token,
    "cancelStatus": token,
    "legacyOrderId": string,
    "marketplaceId": token,
    "partialOrderType": token,
    "paymentStatus": token,
    "payoutRecoupInfo":
        { /* PayoutRecoupInfo */
        "amountToRecoup":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "value": number
            },
        "payoutId": integer
        },
    "requestorType": token,
    "requestRefundAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "value": number
        },
    "sellerLoginName": string,
    "sellerResponseDueDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "shipmentDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        }
    }
    /* More CancelSummary nodes here */
  ],
"paginationOutput":
    { /* PaginationOutput */
    "limit": integer,
    "offset": integer,
    "totalEntries": integer,
    "totalPages": integer
    },
"total": integer
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
cancellations array of CancelSummary Conditionally A list containing one or more cancellation requests that match the request criteria.

This container is not returned if no cancellation requests match the input criteria.
cancellations.buyerLoginName string Conditionally The unique eBay-assigned username of the account that represents the buyer in the transaction.
cancellations
  .buyerResponseDueDate
DateTime Conditionally A timestamp that indicates the time by which the buyer is required to respond to an active cancellation request.

This container is not returned if the cancellation request does not currently require a response from the buyer.
cancellations
  .buyerResponseDueDate
  .formattedValue
string Conditionally Reserved for future use.
cancellations
  .buyerResponseDueDate.value
datetime Conditionally 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
cancellations.cancelCloseDate DateTime Conditionally A timestamp that indicates the time when the cancellation request was closed.

This field is only applicable and returned when the cancellation request is closed (regardless of outcome).
cancellations.cancelCloseDate
  .formattedValue
string Conditionally Reserved for future use.
cancellations.cancelCloseDate
  .value
datetime Conditionally 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
cancellations
  .cancelCloseReason
token Conditionally The reason why the cancel request was closed.

This field is only applicable and returned if cancellation request was closed or if the buyer attempted to close the cancellation request.

Applicable values: See CancelCloseReasonEnum
cancellations.cancelId string Always A unique eBay-assigned ID for an order cancellation. All data in the cancelSummary container refers to this specific order cancellation.
cancellations.cancelReason token Always The reason why the user (either the buyer or the seller, as defined in the requestorType field) initiated the cancellation request.

Applicable values: See CancelReasonEnum
cancellations
  .cancelRequestDate
DateTime Always A timestamp that indicates the time when the cancellation request was created.
cancellations
  .cancelRequestDate
  .formattedValue
string Conditionally Reserved for future use.
cancellations
  .cancelRequestDate.value
datetime Conditionally 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
cancellations.cancelState token Always The current stage or condition of the cancellation process.

This value, combined with the value of the cancelStatus field, can help you determine upcoming cancellation events and the appropriate actions you can take.

Applicable values: See CancelStateEnum
cancellations.cancelStatus token Always The last action taken by one of the parties associated with the cancellation.

This value, combined with the value of the cancelState field, can help you determine upcoming events and the appropriate actions you can take with the cancellation.

Applicable values: See CancelStatusEnum
cancellations.legacyOrderId string Always A unique eBay-assigned ID for the order being canceled or considered for cancellation.

Note: This is the value of the OrderId field returned by a Trading API GetOrders call.

cancellations.marketplaceId token Always A unique eBay-assigned ID for the eBay marketplace where the cancellation was created.

Applicable values: See MarketplaceIdEnum
cancellations.partialOrderType token Conditionally This value indicates whether the cancellation is for either a full or partial order.

Currently, only full orders are eligible for cancellation.

Applicable values: See PartialOrderTypeEnum
cancellations.paymentStatus token Always The current status of the buyer's payment for the order that is being canceled or considered for cancellation.

Applicable values: See PaymentStatusEnum
cancellations.payoutRecoupInfo PayoutRecoupInfo Conditionally Defines the monetary amount of a payout.

Payout amount data includes the sale price in the original currency with it's currency code, and any currency conversion information (as necessary), which includes the current currency code.
cancellations.payoutRecoupInfo
  .amountToRecoup
Amount Conditionally The monetary amount of the payout (paid by the payment system to the buyer) to recoup from the seller.
cancellations.payoutRecoupInfo
  .amountToRecoup
  .convertedFromCurrency
string Conditionally This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
Code so that your app gracefully handles any future changes to this list.
cancellations.payoutRecoupInfo
  .amountToRecoup
  .convertedFromValue
number Conditionally This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
cancellations.payoutRecoupInfo
  .amountToRecoup.currency
string Conditionally This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
cancellations.payoutRecoupInfo
  .amountToRecoup.value
number Conditionally The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
cancellations.payoutRecoupInfo
  .payoutId
integer Conditionally An unique eBay-assigned ID that identifies the payout to the buyer.
cancellations.requestorType token Always The party who made the initial cancellation request (either the buyer or the seller).

Applicable values: See PartyEnum
cancellations
  .requestRefundAmount
Amount Conditionally The amount of the refund that the buyer is expecting to receive if the order is successfully canceled.

The monetary amount indicated here is typically the full amount that the buyer paid for the order, including the item price and shipping fees.

The information returned also includes any currency conversion information (as necessary), the current currency code, the value in the original currency, and the original currency's code.
cancellations
  .requestRefundAmount
  .convertedFromCurrency
string Conditionally This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
Code so that your app gracefully handles any future changes to this list.
cancellations
  .requestRefundAmount
  .convertedFromValue
number Conditionally This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
cancellations
  .requestRefundAmount.currency
string Conditionally This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
cancellations
  .requestRefundAmount.value
number Conditionally The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
cancellations.sellerLoginName string Conditionally The eBay-assigned username of the account that represents the seller in the transaction.
cancellations
  .sellerResponseDueDate
DateTime Conditionally A timestamp that indicates the time by which the seller is required to respond to an active cancellation request.

This container is not returned if the cancellation request does not currently require a response from the seller.
cancellations
  .sellerResponseDueDate
  .formattedValue
string Conditionally Reserved for future use.
cancellations
  .sellerResponseDueDate.value
datetime Conditionally 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
cancellations.shipmentDate DateTime Conditionally A timestamp that indicates the time when the seller shipped the order (or a line item within the order) that the buyer is attempting to cancel.

Once a seller ships one or more line items within an order, the order is no longer eligible for cancellation. This container is only applicable and returned if the seller shipped one or more line items in order, thus making it impossible for the cancel request to be granted.
cancellations.shipmentDate
  .formattedValue
string Conditionally Reserved for future use.
cancellations.shipmentDate
  .value
datetime Conditionally 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
paginationOutput PaginationOutput Conditionally The result set from this call is paginated because the request can result in a large number of matches. This container consists of metadata related to the current response page.

It contains the page number and the cancellation entries per page, as well as the total amount of response pages and cancellation entries. This container is not be returned if no cancellation requests match the input criteria.
paginationOutput.limit integer Always The maximum number of entries to return per request. The value of the totalEntries field divided by the value of this field determines the value of the totalPages field. This value cannot be higher than the number of entries that match the input criteria.
paginationOutput.offset integer Always Identifies the specific page of data to be returned by the request.

The total number of pages in the result set is determined by the total number of entries matching the request criteria (totalEntries), divided by the number of entries to display per page of data (as specified by limit). If there are multiple pages of entries to view (see totalPages), make multiple requests to view all entries and increment the page number by 1 in each subsequent request.

Default: 1
paginationOutput.totalEntries integer Always The total number of entries that match the current input criteria of the request. This value divided by the value of the limit field determines the value of the totalPages field.

Once this number of response set is known, you can modify the input to get the results you desire.
paginationOutput.totalPages integer Always The total number of pages of entries that match the current input criteria of the request.

This value is determined by dividing the value of the totalEntries field by the value of the limit field. If totalPages is more than 1, this call must be issued multiple times to view all result pages, with the page number value being incremented by 1 in each subsequent call.
total integer Conditionally The total number of cancellation requests that match the input criteria.



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: Search for Cancellations

A search with query filters and a sort.

Description

This call sample is used to search for order cancellations requested within a specific time period. The order cancellations are sorted by cancel request date in ascending order.

Input

The GET /cancellation/search operation uses the creation_date_range_from and creation_date_range_to query parameters to retrieve cancellation requests that were created within this time period. The sort query parameter sets the order in which the cancellation requests will be retrieved. The +CANCEL_REQUEST_DATE value means that order cancellations will be sorted based on their request date in ascending order, which means the oldest order cancellations (within the specified time period will be returned first).

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

GET https://api.ebay.com/post-order/v2/cancellation/search?
   creation_date_range_from=2015-05-15T00:00:01.000Z&
   creation_date_range_to=2015-06-15T23:59:59.000Z&
   sort=+CANCEL_REQUEST_DATE

Output

Six order cancellations were found based on the input criteria. These order cancellations appear in ascending order based on the cancellation request date (shown in the cancelRequestDate field). Three of the cancellation requests were made by the seller and three were made by the buyer (indicated by the value in the requestorType field). All order cancellations are in the closed state (indicated by the cancelState field) and the reason for closure varies for each cancellation (reason indicated in the cancelCloseReason field).

JSON format.
{
  "cancellations": [
    {
      "cancelId": "5000018282",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "170007292461-9190794007",
      "requestorType": "SELLER",
      "cancelReason": "OUT_OF_STOCK_OR_CANNOT_FULFILL",
      "cancelState": "CLOSED",
      "cancelStatus": "CANCEL_CLOSED_WITH_REFUND",
      "cancelCloseReason": "FULL_REFUNDED",
      "paymentStatus": "UNKNOWN",
      "requestRefundAmount": {
        "value": 0,
        "currency": "USD"
      },
      "cancelRequestDate": {
        "value": "2015-05-18T22:42:11.000Z",
      },
      "cancelCloseDate": {
        "value": "2015-05-18T22:42:11.000Z",
      }
    },
    {
      "cancelId": "5000018576",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "170007673121-9384079007",
      "requestorType": "SELLER",
      "cancelReason": "OUT_OF_STOCK_OR_CANNOT_FULFILL",
      "cancelState": "CLOSED",
      "cancelStatus": "CANCEL_CLOSED_UNKNOWN_REFUND",
      "cancelCloseReason": "BUYER_CONFIRM_TIMEOUT_NON_PAYPAL_PAID",
      "buyerResponseDueDate": {
        "value": "2015-05-29T06:00:00.000Z",
      },
      "paymentStatus": "UNKNOWN",
      "requestRefundAmount": {
        "value": 1.23,
        "currency": "USD"
      },
      "cancelRequestDate": {
        "value": "2015-05-26T19:03:45.000Z",
      },
      "cancelCloseDate": {
        "value": "2015-05-29T06:05:38.000Z",
      }
    },
    {
      "cancelId": "5000018578",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "170007673122-9384080007",
      "requestorType": "BUYER",
      "cancelState": "CLOSED",
      "cancelStatus": "CANCEL_CLOSED_FOR_COMMITMENT",
      "cancelCloseReason": "SELLER_APPROVE_TIMEOUT_UNPAID",
      "sellerResponseDueDate": {
        "value": "2015-05-30T06:00:00.000Z",
      },
      "paymentStatus": "NOT_PAID",
      "requestRefundAmount": {
        "value": 1.23,
        "currency": "USD"
      },
      "cancelRequestDate": {
        "value": "2015-05-26T19:32:22.000Z",
      },
      "cancelCloseDate": {
        "value": "2015-05-30T06:25:48.000Z",
      }
    },
    {
      "cancelId": "5000018608",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "170007673123-9384081007",
      "requestorType": "BUYER",
      "cancelState": "CLOSED",
      "cancelStatus": "CANCEL_CLOSED_FOR_COMMITMENT",
      "cancelCloseReason": "SELLER_APPROVE_TIMEOUT_UNPAID",
      "sellerResponseDueDate": {
        "value": "2015-05-31T06:00:00.000Z",
      },
      "paymentStatus": "NOT_PAID",
      "requestRefundAmount": {
        "value": 1.23,
        "currency": "USD"
      },
      "cancelRequestDate": {
        "value": "2015-05-27T18:26:44.000Z",
      },
      "cancelCloseDate": {
        "value": "2015-05-31T06:11:20.000Z",
      }
    },
    {
      "cancelId": "5000019540",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "170007646169-9373761007",
      "requestorType": "BUYER",
      "cancelState": "CLOSED",
      "cancelStatus": "CANCEL_REJECTED",
      "cancelCloseReason": "SELLER_DECLINE",
      "shipmentDate": {
        "value": "2015-06-03T07:00:00.000Z",
      },
      "sellerResponseDueDate": {
        "value": "2015-06-07T06:00:00.000Z",
      },
      "paymentStatus": "MARK_AS_PAID",
      "requestRefundAmount": {
        "value": 1.23,
        "currency": "USD"
      },
      "cancelRequestDate": {
        "value": "2015-06-03T16:26:05.000Z",
      },
      "cancelCloseDate": {
        "value": "2015-06-03T16:34:29.000Z",
      }
    },
    {
      "cancelId": "5000020253",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "170007591793-9351013007",
      "requestorType": "SELLER",
      "cancelReason": "OUT_OF_STOCK_OR_CANNOT_FULFILL",
      "cancelState": "CLOSED",
      "cancelStatus": "CANCEL_CLOSED_WITH_REFUND",
      "cancelCloseReason": "FULL_REFUNDED",
      "paymentStatus": "PAYPAL_PAID",
      "requestRefundAmount": {
        "value": 2.46,
        "currency": "USD"
      },
      "cancelRequestDate": {
        "value": "2015-06-13T00:32:09.000Z",
      },
      "cancelCloseDate": {
        "value": "2015-06-13T00:37:06.000Z",
      }
    }
  ],
  "total": 6,
  "paginationOutput": {
    "offset": 1,
    "limit": 6,
    "totalPages": 1,
    "totalEntries": 6
  }
}



Change History

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