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.
Output Samples Change History |
See also Samples.
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
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 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:
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. |
All requests made to eBay REST operations require you to provide the authorization
HTTP header for authentication.
See HTTP request headers for details.
This call uses standard authorization tokens. See Making a Call for details.
This call has no request payload.
Input Samples Change History |
See also Samples.
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 }
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. |
Input Output Change History |
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.
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
}
}
Input Output Samples |
Change Date | Description |
---|---|
1.0 2015-06-30 |
|
Copyright © 2015–2020 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.