Analytics
API ReferenceAnalyticsDisputes
Dispute Metrics
Returns aggregated dispute metrics over a time window. Useful for tracking chargeback rates and the financial impact of disputes you have lost. The full request shape, scopes, and response envelope are documented in Analytics overview.
POST /analytics/v1/{scope}/metrics/disputes
| Path parameter | Type | Description |
|---|---|---|
scope | string | One of merchant or org. |
Available metrics
| Metric | Type | Description |
|---|---|---|
dispute_status_metric | object | Count of disputes broken down by status. Returned as a map keyed by status when requested without groupByNames. |
total_amount_disputed | integer | Sum of disputed amounts in the window, in the lowest currency unit. |
total_dispute_lost_amount | integer | Sum of amounts on disputes that ended in lost status (you owe the funds back to the customer). |
Available groupByNames
| Name | Description |
|---|---|
dispute_status | Final dispute status. |
dispute_stage | Lifecycle stage (pre_dispute, dispute, pre_arbitration). |
connector | Connector that surfaced the dispute. |
currency | Three-letter ISO currency. |
profile_id | Business profile id. |
Available filters
| Filter | Example |
|---|---|
dispute_status | ["lost", "won"] |
dispute_stage | ["dispute", "pre_arbitration"] |
connector | ["stripe", "adyen"] |
currency | ["USD"] |
profile_id | ["pro_xxx"] |
Request Example
curl -X POST 'https://api.v2.paychtec.com/analytics/v1/merchant/metrics/disputes' \ -H "Content-Type: application/json" \ -H "api-key: snd_YOUR_API_KEY" \ -d '[ { "timeRange": { "startTime": "2024-01-01T00:00:00Z", "endTime": "2024-01-31T23:59:59Z" }, "metrics": [ "dispute_status_metric", "total_amount_disputed", "total_dispute_lost_amount" ], "source": "BATCH", "groupByNames": [ "dispute_status" ] }]'Response
{
"queryData": [
{ "dispute_status": "won", "dispute_status_metric": 12, "total_amount_disputed": 65000 },
{ "dispute_status": "lost", "dispute_status_metric": 4, "total_amount_disputed": 22500, "total_dispute_lost_amount": 22500 },
{ "dispute_status": "challenged", "dispute_status_metric": 7, "total_amount_disputed": 41200 }
],
"metaData": [
{ "total_amount_disputed_overall": 128700, "total_dispute_lost_amount_overall": 22500 }
]
}