---
updatedAt: 2026-05-01T21:11:12.000Z
agentTools:
  siteIndex: https://docs.affirm.com/llms.txt
  projectIndex: https://docs.affirm.com/developers/llms.txt
---

# List disputes

Returns a paginated list of disputes.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "description": "Disputes API",
    "version": "0.0.1",
    "title": "Affirm Disputes API",
    "termsOfService": "https://www.affirm.com/terms",
    "contact": {
      "name": "Merchant Interfaces",
      "url": "https://coda.io/d/Merchant-Interfaces_d8L8vZX7Cbt",
      "email": "mint-eng@affirm.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.affirm.com/api/v3"
    },
    {
      "url": "https://api.affirm.com/api/v3"
    }
  ],
  "paths": {
    "/disputes": {
      "get": {
        "tags": [
          "Disputes API"
        ],
        "summary": "List disputes",
        "operationId": "listDisputes",
        "description": "Returns a paginated list of disputes.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of disputes to return.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "created_after",
            "in": "query",
            "description": "Cursor for forward pagination (return results after this dispute ID).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_before",
            "in": "query",
            "description": "Cursor for backward pagination (return results before this dispute ID).",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resolved_after",
            "in": "query",
            "description": "Return results with a resolved date after this date. Format must be ISO 8601: YYYY-MM-DDTHH:MM:SS.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resolved_before",
            "in": "query",
            "description": "Return results with a resolved date before this date. Format must be ISO 8601: YYYY-MM-DDTHH:MM:SS.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter disputes by status.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "action_required_merchant",
                "no_merchant_action_needed",
                "closed_customer_favor",
                "closed_merchant_favor",
                "closed_customer_partial_favor"
              ]
            }
          },
          {
            "name": "dispute_reason",
            "in": "query",
            "description": "Filter disputes by dispute reason.",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/DisputeReason"
            }
          },
          {
            "name": "merchant_id",
            "in": "query",
            "description": "Filter disputes by merchant ID. Required parameter for Partner based API calls.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page_number",
            "in": "query",
            "description": "Page to return. Set to 1 by default.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/TokenResponse"
                    },
                    {
                      "$ref": "#/components/schemas/DisputeListResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TokenResponse": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          }
        }
      },
      "UnauthorizedError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "api-key-pair-invalid"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human readable message with details about the error"
          }
        }
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "internal_server_error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human readable message with details about the error"
          }
        }
      },
      "DisputeReason": {
        "description": "Enum for dispute reason values.",
        "enum": [
          "cancellation_or_return_not_processed",
          "incorrect_amount",
          "product_not_received",
          "product_unacceptable",
          "cancellation_not_processed",
          "return_not_processed"
        ],
        "title": "DisputeReason",
        "type": "string"
      },
      "DisputeSummary": {
        "description": "Summary information for a single dispute in list response.",
        "properties": {
          "created": {
            "description": "When dispute was created",
            "example": "2024-03-02T14:29:07Z",
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "description": "Currency code (ISO 4217)",
            "example": "USD",
            "type": "string"
          },
          "dispute_amount": {
            "description": "Dispute amount in the smallest denomination of the currency",
            "example": 1000,
            "minimum": 0,
            "type": "integer"
          },
          "dispute_reason": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DisputeReason"
              }
            ],
            "default": null,
            "description": "Dispute reason",
            "example": "product_not_received",
            "nullable": true
          },
          "id": {
            "description": "ID of the dispute",
            "example": "dispute_123",
            "type": "string"
          },
          "merchant_id": {
            "description": "ID of the merchant associated with the dispute",
            "example": "merchant_id:sandbox:1234",
            "type": "string"
          },
          "response_due_by": {
            "default": null,
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "description": "Current status of the dispute",
            "example": "action_required_merchant",
            "type": "string"
          },
          "transaction_id": {
            "description": "ID of the transaction associated with the dispute",
            "example": "AB1D-E2GH",
            "type": "string"
          },
          "updated": {
            "default": null,
            "format": "date-time",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "id",
          "merchant_id",
          "transaction_id",
          "dispute_amount",
          "currency",
          "status",
          "created"
        ],
        "type": "object"
      },
      "PageInfo": {
        "description": "Pagination information.",
        "properties": {
          "has_next": {
            "description": "Whether more results exist after this page",
            "example": true,
            "type": "boolean"
          },
          "has_prev": {
            "description": "Whether previous page exists",
            "example": false,
            "type": "boolean"
          }
        },
        "required": [
          "has_next",
          "has_prev"
        ],
        "type": "object"
      },
      "DisputeListResponse": {
        "description": "Response model for list disputes API.",
        "properties": {
          "disputes": {
            "description": "List of dispute summaries",
            "items": {
              "$ref": "#/components/schemas/DisputeSummary"
            },
            "type": "array"
          },
          "page_info": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PageInfo"
              }
            ],
            "description": "Pagination information"
          }
        },
        "required": [
          "disputes",
          "page_info"
        ],
        "type": "object"
      }
    }
  }
}
```

# Sibling pages

* [Get dispute](https://docs.affirm.com/developers/reference/get_dispute.md)
* [Close dispute](https://docs.affirm.com/developers/reference/close_dispute.md)
* [Submit dispute evidence](https://docs.affirm.com/developers/reference/submit_dispute_evidence.md)