Search Cases

GET /post-order/v2/casemanagement/search

This call is used to search for cases using multiple filter types.

Input

Resource URI (production)

GET https://api.ebay.com/post-order/v2/casemanagement/search?
  case_creation_date_range_from=string&
  case_creation_date_range_to=string&
  case_status_filter=CaseStatusFilter&
  fieldgroups=CaseSearchFieldGroupEnum&
  item_id=string&
  limit=integer&
  offset=integer&
  order_id=string&
  return_id=string&
  sort=string&
  transaction_id=string

URI parameters

Parameter	Type	Required?	Meaning
case_creation_date_range_from	string	Optional	The case_creation_date_range_from and case_creation_date_range_to query parameters are used if the user wants to retrieve cases that were created during a specific time range. The starting date range is input into the case_creation_date_range_from query parameter. The case_creation_date_range_from date must be older than the case_creation_date_range_to date, and it cannot be set back more than 18 months in the past. If the case_creation_date_range_from query parameter is used, but the case_creation_date_range_to query parameter is not used, the call will look for all cases 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`.
case_creation_date_range_to	string	Optional	The case_creation_date_range_from and case_creation_date_range_to query parameters are used if the user wants to retrieve cases that were created during a specific time range. The ending date range is input into the case_creation_date_range_to query parameter. The case_creation_date_range_to date must be more recent than the case_creation_date_range_from date. If the case_creation_date_range_from query parameter is used, but the case_creation_date_range_to query parameter is not used, the call will look for all cases created at or after the case_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`.
case_status_filter	string	Optional	This query parameter is used if the user wants to search for cases in a specific state. The possible states are defined in the CaseStatusFilter type. Applicable values are from CaseStatusFilter.
fieldgroups	string	Optional	The fieldgroups query parameter can be used in the call URI to control the detail level that is returned in the response. See the CaseSearchFieldGroupEnum type for more information on the values that may be used in this query parameter. b>Note: Using the fieldGroups query parameter is not recommended at this time, as the two supported enumeration values for this field will have the same effect on the Search Cases call response. Applicable values are from CaseSearchFieldGroupEnum.
item_id	string	Optional	The unique identifier of a listing. An item_id and a transaction_id value are both needed if the user wants to find any cases filed against a specific order line item. If these query parameters are used, any other query parameters that are used are ignored.
limit	integer	Optional	This integer value is used to specify the maximum number of cases to display on a single 'page' of data. This value, along with the number of cases that match the input criteria, will determine the total pages (see paginationOutput.totalPages) in the result set. The maximum value is 200 and the default value is 25 cases per page. The cases that are actually retrieved (and those that are left out) will be determined by the settings specified in the sort field.
offset	integer	Optional	This integer value sets the results page to return in the current call. Page '1' of results is returned if this query parameter isn't used. Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results in the paginationOutput container of your initial call).
order_id	string	Optional	The unique ID of an order. An order_id value is provided as a query parameter if the user wants to see if an case was filed against one or more order line items in the order specified in this field. Note: The order ID value changes as an order goes from the unpaid to the paid state.
return_id	string	Optional	The unique identifier of a return. A return_id value is provided as a query parameter if the user wants to find cases that started as return requests but were escalated to a case.
sort	string	Optional	This query parameter is used if you want to sort the retrieved cases by creation date. The two supported values for this query parameter are 'Ascending' and 'Descending'. If the value is set to 'Descending', the most recently opened cases are returned at the top of the response. If the value is set to 'Ascending', the oldest cases are returned at the top of the response.
transaction_id	string	Optional	The unique identifier of an order line item. An item_id and a transaction_id value are both needed if the user wants to find any cases filed against a specific order line item. If these query parameters are used, any other query parameters that are used are 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.

{ /* CaseSearchResponse */
"members": [
    { /* CaseSummaryType */
    "buyer": string,
    "caseId": integer,
    "caseStatusEnum": string,
    "claimAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "exchangeRate": string,
        "value": number
        },
    "creationDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "itemId": integer,
    "lastModifiedDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "respondByDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        },
    "seller": string,
    "transactionId": integer
    }
    /* More CaseSummaryType nodes here */
  ],
"paginationOutput":
    { /* PaginationOutput */
    "limit": integer,
    "offset": integer,
    "totalEntries": integer,
    "totalPages": integer
    },
"totalNumberOfCases": integer
}

Response field descriptions

Output Container/Field	Type	Occurrence	Meaning
members	array of CaseSummaryType	Always	This container is an array of cases that match the query parameters in the call request.
members.buyer	string	Always	The eBay user ID of the buyer involved in the case.
members.caseId	integer	Always	The unique identifier of the case.
members.caseStatusEnum	string	Always	This enumeration value indicates the current status of the case. Applicable values are from CaseStatusEnum:See caseStatusEnum. Code so that your app gracefully handles any future changes to this list.
members.claimAmount	Amount	Always	This container displays the dollar value of the order line item associated with the case, which is generally the amount of the refund that the buyer will receive if the buyer is looking for a refund, or if the seller voluntarily refunds the buyer.
members.claimAmount .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.
members.claimAmount .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.
members.claimAmount.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.
members.claimAmount .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.
members.claimAmount.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.
members.creationDate	DateTime	Always	This timestamp indicates when the case was created.
members.creationDate .formattedValue	string	Conditionally	Reserved for future use.
members.creationDate.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`
members.itemId	integer	Always	The unique identifier for the eBay listing where the item was purchased. This field is used in conjunction with the transactionId field to identify a line item within an order.
members.lastModifiedDate	DateTime	Always	This timestamp indicates when the last action was performed on the case.
members.lastModifiedDate .formattedValue	string	Conditionally	Reserved for future use.
members.lastModifiedDate.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`
members.respondByDate	DateTime	Conditionally	This timestamp indicates the deadline for when a buyer or seller must perform the next action on the case. This field will only be returned if there is a deadline associated with the next action.
members.respondByDate .formattedValue	string	Conditionally	Reserved for future use.
members.respondByDate.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`
members.seller	string	Always	The eBay user ID of the seller involved in the case.
members.transactionId	integer	Always	The unique identifier for the purchase of a item. This value is created right when the buyer is committed to buying the item, whether that buyer uses a 'Buy it Now' capability, is the winning bidder of an auction, or the buyer's Best Offer is accepted by the seller. This field is used in conjunction with the itemId field to identify a line item within an order.
paginationOutput	PaginationOutput	Always	This container consists of metadata related to the current response page. It contains the page number and the cases per page, as well as the total amount of response pages and cases.
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.
totalNumberOfCases	integer	Always	This integer value indicates the total number of cases that were found based on the input filter(s) in the request.

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: Basic Call

Search for open cases

Description

This call searches for open cases filed against the seller.

Input

To retrieve open cases only, the case_status_filter query parameter is used, and its value is set to OPEN.

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

GET https://api.ebay.com/post-order/v2/casemanagement/search?
   case_status_filter=OPEN

Output

The search revealed that the seller has only one open case filed against their account. To retrieve more information about the case, the seller will want to grab the caseId value and run a 'Get Case' call using that ID value.

JSON format.
{ 
"members": [
    { 
    "buyer": "s*************4",
    "caseId": "5********3",
    "caseStatusEnum": "OPEN",
    "claimAmount":
        { 
        "currency": "USD",
        "value": "81.0"
        },
    "creationDate":
        { 
        "value": "2015-08-29T20:18:17.000Z"
        },
    "itemId": "2**********1",
    "lastModifiedDate":
        { 
        "value": "2015-08-29T20:18:17.000Z"
        },
    "respondByDate":
        { 
        "value": "2015-09-01T20:18:17.000Z"
        },
    "seller": "f***********6",
    "transactionId": "8********1"
    }
  ],
"paginationOutput":
    { 
    "limit": 25,
    "offset": 0,
    "totalEntries": 1,
    "totalPages": 1
    },
"totalNumberOfCases": 1
}

Change History

Change Date	Description