eBay Post-Order APIVersion 2

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

See also Samples.

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

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 */
    "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.



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.