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)
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
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
| Parameter | Type | Description |
|---|---|---|
| order_id | string | This 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_username | string | This 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_from | string | The 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_to | string | The 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_status | array of string | This 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 |
| limit | string | The 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 |
| offset | string | This 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/field | Type | Description |
|---|---|---|
| href | string | The URI of the getPaymentDisputeSummaries call request that produced the current page of the result set. Occurrence: Always |
| limit | integer | 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 Occurrence: Always |
| next | string | 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: Occurrence: Conditional |
| offset | integer | 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 Occurrence: Always |
| paymentDisputeSummaries | array 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.amount | SimpleAmount | 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.currency | CurrencyCodeEnum | A three-letter ISO 4217 code (such as Occurrence: Conditional |
| paymentDisputeSummaries.amount.value | string | The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container. Occurrence: Conditional |
| paymentDisputeSummaries.buyerUsername | string | This is the buyer's eBay user ID. This field is returned for all payment disputes returned in the response. Occurrence: Conditional |
| paymentDisputeSummaries.closedDate | string | 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 Occurrence: Conditional |
| paymentDisputeSummaries.openDate | string | 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. Occurrence: Conditional |
| paymentDisputeSummaries.orderId | string | This is the unique identifier of the order involved in the payment dispute. Occurrence: Conditional |
| paymentDisputeSummaries.paymentDisputeId | string | 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.paymentDisputeStatus | DisputeStateEnum | The enumeration value in this field gives the current status of the payment dispute. Occurrence: Conditional |
| paymentDisputeSummaries.reason | DisputeReasonEnum | 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.respondByDate | string | 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 Occurrence: Conditional |
| prev | string | 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: Occurrence: Conditional |
| total | integer | 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 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.
| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 33000 | API_FULFILLMENT | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 33001 | API_FULFILLMENT | REQUEST | Invalid 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.