List disputes

Query Parameters

date-time

RFC 3339 timestamp for filtering by created date, inclusive.

page_size

• Type: integer
• Range: 1 to 100, Defaults to 50
  Number of items to return.

starting_after

• Type: string
  A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item.

ending_before

• Type: string
  A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item.

disputed_transaction_token

• Type: uuid
  Filter by the token of the transaction being disputed. Corresponds with transaction_series.related_transaction_token in the Dispute.

card_token

• Type: uuid
  Filter by card token.

account_token

• Type: uuid
  Filter by account token.

Response Format

200 OK

An object representing the response for listing disputes.

data

• Type: array of objects, required
  Array of dispute objects.

Dispute Object

• case_id: string | null, required
  Identifier assigned by the network for this dispute.
• token: uuid, required
  Token assigned by Lithic for the dispute, in UUID format.
• card_token: uuid, required
  Token for the card used in the dispute, in UUID format.
• account_token: uuid, required
  Token for the account associated with the dispute, in UUID format.
• network: string, enum, required
  Card network handling the dispute. (VISA, MASTERCARD)
• currency: string, required
  Three-letter ISO 4217 currency code.
• created: date-time, required
  When the dispute was created.
• updated: date-time, required
  When the dispute was last updated.
• merchant: object, required
  Merchant object.
• transaction_series: object, required
  Transaction Series object.
• liability_allocation: object, required
  Current breakdown of how liability is allocated for the disputed amount.
• status: string | null, enum, required
  Current status of the dispute. (OPEN, CLOSED, null)
• disposition: string | null, enum, required
  Dispute resolution outcome. (WON, LOST, PARTIALLY_WON, WITHDRAWN, DENIED, null)
• events: array of objects, required
  Chronological list of events that have occurred in the dispute lifecycle.

Event Object

• token: uuid, required
  Unique identifier for the event, in UUID format.
• type: string, enum, required
  Type of event (WORKFLOW, FINANCIAL, CARDHOLDER_LIABILITY).
• created: date-time, required
  When the event occurred.
• data: required
  Details specific to the event type.

has_more

• Type: boolean, required
  Whether there are more results available.

Example Request

curl --request GET \
     --url 'https://sandbox.lithic.com/v2/disputes?page_size=50' \
     --header 'accept: application/json'

Example Response

{
  "data": [
    {
      "case_id": "string",
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "network": "VISA",
      "currency": "string",
      "created": "2026-07-18T00:25:37.021Z",
      "updated": "2026-07-18T00:25:37.021Z",
      "merchant": {
        "acceptor_id": "333301802529120",
        "acquiring_institution_id": "191231",
        "city": "NEW YORK",
        "country": "USA",
        "descriptor": "COFFEE SHOP",
        "mcc": "5812",
        "state": "NY"
      },
      "transaction_series": {
        "type": "DISPUTE",
        "related_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "related_transaction_event_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "liability_allocation": {
        "original_amount": 0,
        "recovered_amount": 0,
        "written_off_amount": 0,
        "denied_amount": 0,
        "remaining_amount": 0
      },
      "status": "OPEN",
      "disposition": "WON",
      "events": [
        {
          "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "type": "WORKFLOW",
          "created": "2026-07-18T00:25:37.021Z",
          "data": {
            "type": "string",
            "stage": "CLAIM",
            "action": "OPENED",
            "reason": "string",
            "amount": 0,
            "disposition": "WON"
          }
        }
      ]
    }
  ],
  "has_more": true
}

Error Codes

• 400: A parameter in the query given in the request does not match the valid queries for the endpoint.
• 401: User has not been authenticated or invalid/missing API key.
• 422: Unprocessable entity.
• 429: Client has exceeded the number of allowed requests in a given time period.