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

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 order ID value changes as an order goes from the unpaid to the paid state.
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	Optional	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

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,
            "exchangeRate": string,
            "value": number
            },
        "payoutId": integer
        },
    "requestorType": token,
    "requestRefundAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "exchangeRate": 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: The order ID value changes as an order goes from the unpaid to the paid state.
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	The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. 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	The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated.
cancellations.payoutRecoupInfo .amountToRecoup.currency	string	Conditionally	A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. Default: The currency of the authenticated user'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.exchangeRate	string	Conditionally	This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version.
cancellations.payoutRecoupInfo .amountToRecoup.value	number	Conditionally	The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
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	The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. 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	The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated.
cancellations .requestRefundAmount.currency	string	Conditionally	A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. Default: The currency of the authenticated user's country. Applicable values are from CurrencyCodeEnum:See currency. Code so that your app gracefully handles any future changes to this list.
cancellations .requestRefundAmount .exchangeRate	string	Conditionally	This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version.
cancellations .requestRefundAmount.value	number	Conditionally	The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
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.

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: 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": "5********2",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "1**********1-9********7",
      "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": "5********6",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "1**********1-9********7",
      "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": "5********8",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "1**********2-9********8",
      "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": "5********8",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "1**********3-9********8",
      "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": "5********0",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "1**********9-9********9",
      "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": "5********3",
      "marketplaceId": "EBAY_US",
      "legacyOrderId": "1**********3-9********6",
      "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.