Skip to main content

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

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

This method is supported in Sandbox environment. To access the endpoint, just replace the apiz.ebay.com root URI with apiz.sandbox.ebay.com

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.

Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.

Occurrence: Optional

buyer_usernamestringThis filter is used if the seller wishes to retrieve one or more payment disputes opened by a specific buyer. 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 90 days. 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 90 days after the date specified in the open_date_from field, or to the present time if less than 90 days 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: Conditional

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 90 days. 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 90 days 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 one or more specific states. To filter by more than one status value, a separate payment_dispute_status filter must be used for each value, as shown below:

https://apiz.ebay.com/sell/fulfillment/v1/payment_dispute_summary?payment_dispute_status=OPEN&payment_dispute_status=ACTION_NEEDED

If no payment_dispute_status filter is used, payment disputes in all states are returned in the response.

See DisputeStatusEnum 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: 200

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

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.

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

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.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
hrefstring

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

Occurrence: Always

limitinteger

This 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

nextstring

The 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

offsetinteger

This 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

paymentDisputeSummariesarray of PaymentDisputeSummary

Each 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.amountSimpleAmount

This 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.currencyCurrencyCodeEnum

A 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 always returned with the amount container.

Occurrence: Conditional

paymentDisputeSummaries.amount.valuestring

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

Occurrence: Conditional

paymentDisputeSummaries.buyerUsernamestring

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

Occurrence: Conditional

paymentDisputeSummaries.closedDatestring

The 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.openDatestring

The 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.orderIdstring

This is the unique identifier of the order involved in the payment dispute.

Occurrence: Conditional

paymentDisputeSummaries.paymentDisputeIdstring

This is the unique identifier of the payment dispute. This identifier is automatically created by eBay once the payment dispute comes into the eBay 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.paymentDisputeStatusDisputeStateEnum

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

Occurrence: Conditional

paymentDisputeSummaries.reasonDisputeReasonEnum

The 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.respondByDatestring

The 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

prevstring

The 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

totalinteger

This 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

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.
33001API_FULFILLMENTREQUESTInvalid input request

Warnings

This call has no warnings.

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 r********r.

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.

GEThttps://apiz.ebay.com/sell/fulfillment/v1/payment_dispute_summary?limit=2&offset=0&buyer_username=r********r

Output

A total of five payment disputes are disovered for the buyer named r********r, 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.