fulfillment API1.11.0

getPaymentDisputeSummaries

GET
/payment_dispute_summary
This method is used retrieve one or more payment disputes filed against the seller. These payment disputes can be open or recently closed. The following filter types are available in the request payload to control the payment disputes that are returned:
  • Dispute filed against a specific order (order_id parameter is used)
  • Dispute(s) filed by a specific buyer (buyer_username parameter is used)
  • Dispute(s) filed within a specific date range (open_date_from and/or open_date_to parameters are used)
  • Disputes in a specific state (payment_dispute_status parameter is used)
More than one of these filter types can be used together. See the request payload request fields for more information about how each filter is used.

If none of the filters are used, all open and recently closed payment disputes are returned.

Pagination is also available. See the limit and offset fields for more information on how pagination is used for this method.

Input

Resource URI (production)

GET https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute_summary?

URI parameters

ParameterTypeDescription
order_idstringThis filter is used if the seller wishes to retrieve one or more payment disputes filed against a specific order. It is possible that there can be more than one dispute filed against an order if the order has multiple line items. If this filter is used, any other filters are ignored.

Note: The order identifier passed into this field must be an Order ID in the new format. The legacy APIs still support the old and new order ID format to identify orders, but only the new order ID format is supported in REST-based APIs. eBay rolled out a new Order ID format in June 2019.

Occurrence: Optional

buyer_usernamestringThis filter is used if the seller wishes to retrieve one or more payment disputes opened by a specific seller. The string that is passed in to this query parameter is the eBay user ID of the buyer.

Occurrence: Optional

open_date_fromstringThe open_date_from and/or open_date_to date filters are used if the seller wishes to retrieve payment disputes opened within a specific date range. A maximum date range that may be set with the open_date_from and/or open_date_to filters is three months. These date filters use the ISO-8601 24-hour date and time format, and time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu.

The open_date_from field sets the beginning date of the date range, and can be set as far back as 18 months from the present time. If a open_date_from field is used, but a open_date_to field is not used, the open_date_to value will default to three months after the date specified in the open_date_from field, or to the present time if less than three months in the past.

The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Optional

open_date_tostringThe open_date_from and/or open_date_to date filters are used if the seller wishes to retrieve payment disputes opened within a specific date range. A maximum date range that may be set with the open_date_from and/or open_date_to filters is three months. These date filters use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu.

The open_date_to field sets the ending date of the date range, and can be set up to three months from the date set in the open_date_from field.

The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Optional

payment_dispute_statusarray of stringThis filter is used if the seller wishes to only retrieve payment disputes in a specific state. More than one value can be specified. If no payment_dispute_status filter is used, payment disputes in all states are returned in the response. See DisputeStateEnum type for supported values.

Occurrence: Optional

limitstringThe value passed in this query parameter sets the maximum number of payment disputes to return per page of data. The value passed in this field should be an integer from 1 to 200. If this query parameter is not set, up to 200 records will be returned on each page of results.

Min: 1; Max: 200; Default: 100

Occurrence: Optional

offsetstringThis field is used to specify the number of records to skip in the result set before returning the first payment dispute in the paginated response. A zero-based index is used, so if you set the offset value to 0 (default value), the first payment dispute in the result set appears at the top of the response.

Combine offset with the limit parameter to control the payment disputes returned in the response. For example, if you supply an offset value of 0 and a limit value of 10, the response will contain the first 10 payment disputes from the result set that matches the input criteria. If you supply an offset value of 10 and a limit value of 20, the response will contain payment disputes 11-30 from the result set that matches the input criteria.

Min: 0; Max: total number of payment disputes - 1; Default: 0

Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.payment.dispute

See OAuth access tokens for more information.

Output

HTTP response headers

Output container/fieldTypeDescription
paymentDisputeSummariesarray of PaymentDisputeSummaryEach payment dispute that matches the input criteria is returned under this array. If no payment disputes are found, an empty array is returned.

Occurrence: Always

paymentDisputeSummaries.paymentDisputeIdstringThis is the unique identifier of the payment dispute. This identifier is automatically created by eBay once the payment dispute comes into the eBay managed payments system. This identifier is passed in at the end of the getPaymentDispute call URI to retrieve a specific payment dispute. The getPaymentDispute method returns more details about a payment dispute than the getPaymentDisputeSummaries method.

Occurrence: Conditional

paymentDisputeSummaries.paymentDisputeStatusDisputeStateEnumThe enumeration value in this field gives the current status of the payment dispute.

Occurrence: Conditional

paymentDisputeSummaries.reasonDisputeReasonEnumThe enumeration value in this field gives the reason why the buyer initiated the payment dispute. See DisputeReasonEnum type for a description of the supported reasons that buyers can give for initiating a payment dispute.

Occurrence: Conditional

paymentDisputeSummaries.orderIdstringThis is the unique identifier of the order involved in the payment dispute.

Note: eBay rolled out a new Order ID format in June 2019. The legacy APIs still support the old and new order ID format to identify orders, but only the new order ID format is supported in REST-based APIs.

Occurrence: Conditional

paymentDisputeSummaries.openDatestringThe timestamp in this field shows the date/time when the payment dispute was opened. This field is returned for payment disputes in all states.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

paymentDisputeSummaries.closedDatestringThe timestamp in this field shows the date/time when the payment dispute was closed, so this field is only returned for payment disputes in the CLOSED state.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

paymentDisputeSummaries.respondByDatestringThe timestamp in this field shows the date/time when the seller must response to a payment dispute, so this field is only returned for payment disputes in the ACTION_NEEDED state. For payment disputes that require action by the seller, that same seller must call getPaymentDispute to see the next action(s) that they can take against the payment dispute.

The timestamps returned here use the ISO-8601 24-hour date and time format, and the time zone used is Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT), or Zulu. The ISO-8601 format looks like this: yyyy-MM-ddThh:mm.ss.sssZ. An example would be 2019-08-04T19:09:02.768Z.

Occurrence: Conditional

paymentDisputeSummaries.buyerUsernamestringThis is the buyer's eBay user ID. This field is returned for all payment disputes returned in the response.

Occurrence: Conditional

paymentDisputeSummaries.amountSimpleAmountThis container shows the dollar value associated with the payment dispute in the currency used by the seller's marketplace. This container is returned for all payment disputes returned in the response.

Occurrence: Conditional

paymentDisputeSummaries.amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code (such as USD for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

paymentDisputeSummaries.amount.valuestringThe monetary amount of the refund. Only use a maximum of two digits to the right of the decimal point. Both the value and currency fields are required when expressing the amount of the refund or the amount involved in a payment dispute.

Occurrence: Conditional

totalintegerThis integer value is the total number of payment disputes that matched the input criteria. If the total number of entries exceeds the value that was set for limit in the request payload, you will have to make multiple API calls to see all pages of the results set. This field is returned even if it is 0.

Occurrence: Always

hrefstringThe URI of the getPaymentDisputeSummaries call request that produced the current page of the result set.

Occurrence: Always

nextstringThe getPaymentDisputeSummaries call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 11 thru 20 from the collection of payment disputes:

path/payment_dispute_summary?limit=10&offset=10

This field is only returned if there is a next page of results to view based on the current input criteria.

Occurrence: Conditional

prevstringThe getPaymentDisputeSummaries call URI to use if you wish to view the previous page of the result set. For example, the following URI returns records 1 thru 10 from the collection of payment disputes:

path/payment_dispute_summary?limit=10&offset=0

This field is only returned if there is a previous page of results to view based on the current input criteria.

Occurrence: Conditional

limitintegerThis value shows the maximum number of payment disputes that will appear on one page of the result set. The limit value can be passed in as a query parameter in the request, or if it is not used, it defaults to 200. If the value in the total field exceeds this limit value, there are multiple pages in the current result set.

Min: 1; Max: 200; Default: 200

Occurrence: Always

offsetintegerThis integer value indicates the number of payment disputes skipped before listing the first payment dispute from the result set. The offset value can be passed in as a query parameter in the request, or if it is not used, it defaults to 0 and the first payment dispute of the result set is shown at the top of the response.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
33000API_FULFILLMENTAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
33100API_FULFILLMENTREQUESTInvalid input request

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get a summary of current payment disputes

Get a summary of buyer-inititated payment disputes

Input

The seller wants to retrieve summary data of any payment disputes opened by a specific eBay buyer with an eBay user ID of rlagersandboxtestbuyer.

To find any payment disputes opened by this buyer, the seller uses the buyer_username. The seller also wants to limit the number of payment disputes displayed per page to 2, so the seller also uses the limit query parameter and sets its value to 2.
GET
https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute_summary?limit=2&offset=0&buyer_username=rlagersandboxtestbuyer

Output

A total of five payment disputes are disovered for the buyer named rlagersandboxtestbuyer, and a summary of the first two of these payment disputes are shown on the first page of results. One payment dispute was opened due to possible fraud, and the other payment dispute was opened because the buyer was possibly charged twice. If the seller wants to see the next page of payment disputes in the result set, the partial URI in the next field can be used in the subsequent call.

If the seller wants to get more detail on one or more of these payment disputes, the seller can grab the payment dispute IDs and then run a getPaymentDispute call.