Search Cancellations

GET /post-order/v2/cancellation/search

This call is used to search for and retrieve one or more order cancellations. Search criteria are passed in as query parameters in the call URI.

Based on how many order cancellations match the search criteria (including the limit and offset values), a user may need to issue this call multiple times to retrieve all order cancellations that match the search criteria. Each result set is returned as a page of order cancellations. Use the limit and offset parameters to control the maximum number of entries to retrieve with each call, and the page number to retrieve, respectively.

Input

Resource URI (production)

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

URI parameters

Parameter	Type	Required?	Meaning
buyer_login_name	string	Optional	This parameter is for internal use only.
cancel_id	string	Optional	The identifier of a specific cancellation. If you supply this parameter, any other query parameters you include will be ignored, and summary information for the specified cancellation will be returned.
creation_date_range_from	string	Optional	The creation_date_range_from and creation_date_range_to query parameters are used if the user wants to retrieve cancellation requests that were created during a specific time range. The starting date range is input into the creation_date_range_from query parameter. The creation_date_range_from date must be older than the creation_date_range_to date, and it cannot be set back more than 18 months in the past. If the creation_date_range_from query parameter is used, but the creation_date_range_to query parameter is not used, the call will look for all cancellation requests created at or after this date/time, going forward 90 days from this date. The ISO date format should be used for this query parameter. Here's a sample of that format: `2015-05-15T03:52:39.000Z`.
creation_date_range_to	string	Optional	The creation_date_range_from and creation_date_range_to query parameters are used if the user wants to retrieve cancellation requests that were created during a specific time range. The ending date range is input into the creation_date_range_to query parameter. The creation_date_range_to date must be more recent than the creation_date_range_from date. If the creation_date_range_from query parameter is used, but the creation_date_range_to query parameter is not used, the call will look for all cancellation requests created at or after the creation_date_range_from value, going forward 90 days from this date. The ISO date format should be used for this query parameter. Here's a sample of that format: `2015-05-15T03:52:39.000Z`.
item_id	string	Optional	The unique 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 just include item_id as a query parameter, and any and all cancellations made against the listing by any and all buyers will be returned.
legacy_order_id	string	Optional	The unique ID of an order that must be associated with any of the cancellations returned. Note: This is the value of the OrderID field returned by the Trading API's GetOrders call.
limit	string	Optional	The maximum number of entries (data records) to retrieve per page of output.
offset	string	Optional	The specific page of data requested by this call. If not specified in the request, this field's value defaults to `1`, which means the first page of entries is returned.
seller_login_name	string	Optional	This parameter is for internal use only.
sort	string	Optional	Contains the specification for sorting the cancellation records returned by this call. This specification consists of the field to sort by, preceded by a character indicating the direction in which to sort. 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`, `-CANCEL_ID` Sort the cancel records by the cancelId field, in ascending or descending order, respectively. `+CANCEL_REQUEST_DATE`, `-CANCEL_REQUEST_DATE` Sort the cancel records by the cancelRequestDate field, in ascending or descending order, respectively. Note: The CancelSortField type provides the underlying data structure for this parameter, but should not be used directly in the call. Applicable values are from CancelSortField.
transaction_id	string	Optional	The unique ID of a purchase associated with a cancellation to be returned. Note: If this query parameter is used, the item_id query parameter must also be used to uniquely identify an order line item. If transaction_id is used, but item_id is omitted, the transaction_id query parameter will have no affect.

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 */
    "buyerResponseDueDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "cancelCloseDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "cancelCloseReason": token,
    "cancelId": string,
    "cancelReason": token,
    "cancelRequestDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "legacyOrderId": string,
    "marketplaceId": string,
    "paymentStatus": token,
    "requestorType": token,
    "requestRefundAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "value": number
        },
    "sellerResponseDueDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "shipmentDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "state": token,
    "status": token
    }
    /* 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 input criteria. This container is not returned if no cancellation requests match the input criteria.
cancellations .buyerResponseDueDate	DateTime	Conditionally	A timestamp that indicates when 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	This field is for internal or future use.
cancellations .buyerResponseDueDate.value	datetime	Conditionally	This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type.
cancellations.cancelCloseDate	DateTime	Conditionally	A timestamp that indicates 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	This field is for internal or future use.
cancellations.cancelCloseDate .value	datetime	Conditionally	This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type.
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 (as defined in the requestorType field) initiated the cancellation request. Applicable values: See CancelReasonEnum
cancellations .cancelRequestDate	DateTime	Always	A timestamp that indicates when the cancellation request was created.
cancellations .cancelRequestDate .formattedValue	string	Conditionally	This field is for internal or future use.
cancellations .cancelRequestDate.value	datetime	Conditionally	This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type.
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 the Trading API's GetOrders call.
cancellations.marketplaceId	string	Always	A unique eBay-assigned ID for the eBay marketplace where the cancellation was created. Applicable values are from MarketplaceIdEnum:See marketplaceId. Code so that your app gracefully handles any future changes to this list.
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.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. This is typically be the full amount that the buyer paid for the order, including the item price and shipping fees. The returned information 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 .sellerResponseDueDate	DateTime	Conditionally	A timestamp that indicates when 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	This field is for internal or future use.
cancellations .sellerResponseDueDate.value	datetime	Conditionally	This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type.
cancellations.shipmentDate	DateTime	Conditionally	A timestamp that indicates 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, it is too late for the order to be canceled. 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	This field is for internal or future use.
cancellations.shipmentDate .value	datetime	Conditionally	This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format: Format: YYYY-MM-DDTHH:MM:SS.SSSZ Example: 2004-08-04T19:09:02.768Z This field is always used for containers using the DateTime type.
cancellations.state	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 events and the appropriate actions you can take. Applicable values: See CancelStateEnum
cancellations.status	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. Applicable values: See CancelStatusEnum
paginationOutput	PaginationOutput	Conditionally	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 will 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 number of cancellations 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": "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.