---
title: "List disputes"
method: GET
path: "/v2/disputes"
tags: ["Managed Disputes"]
---

# List disputes

`GET /v2/disputes`

Returns a paginated list of disputes.

## Query parameters

- `begin` string, date-time
- `end` string, date-time
- `page_size` integer
- `starting_after` string
- `ending_before` string
- `disputed_transaction_token` string, uuid
- `card_token` string, uuid
- `account_token` string, uuid

## Response `200`

OK

- DisputesResponse — Response for listing disputes
  - `data` Dispute[], required — Array of dispute objects
    - `case_id` string, nullable, required — Identifier assigned by the network for this dispute.
    - `token` string, uuid, required — Token assigned by Lithic for the dispute, in UUID format.
    - `card_token` string, uuid, required — Token for the card used in the dispute, in UUID format.
    - `account_token` string, uuid, required — Token for the account associated with the dispute, in UUID format.
    - `network` 'VISA' | 'MASTERCARD', required — Card network handling the dispute.
    - `currency` string, required — Three-letter ISO 4217 currency code.
    - `created` string, date-time, required — When the dispute was created.
    - `updated` string, date-time, required — When the dispute was last updated.
    - `merchant` Merchant, required
      - `acceptor_id` string, required — Unique alphanumeric identifier for the payment card acceptor (merchant).
      - `acquiring_institution_id` string, required — Unique numeric identifier of the acquiring institution.
      - `city` string, required — City of card acceptor. Note that in many cases, particularly in card-not-present transactions, merchants may send through a phone number or URL in this field.
      - `country` string, required — Country or entity of card acceptor. Possible values are: (1) all ISO 3166-1 alpha-3 country codes, (2) QZZ for Kosovo, and (3) ANT for Netherlands Antilles.
      - `descriptor` string, required — Short description of card acceptor.
      - `mcc` string, required — Merchant category code (MCC). A four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides.
      - `state` string, required — Geographic state of card acceptor.
    - `transaction_series` TransactionSeries, required — Contains identifiers for the transaction and specific event within being disputed; null if no transaction can be identified
      - `type` 'DISPUTE', required — The type of transaction series associating the dispute and the original transaction. Always set to DISPUTE
      - `related_transaction_token` string, uuid, required — Token of the original transaction being disputed, in UUID format
      - `related_transaction_event_token` string, uuid, nullable, required — Token of the specific event in the original transaction being disputed, in UUID format; null if no event can be identified
    - `liability_allocation` LiabilityAllocation, required — Current breakdown of how liability is allocated for the disputed amount
      - `original_amount` integer, required — The initial amount disputed
      - `recovered_amount` integer, required — The amount that has been recovered from the merchant through the dispute process
      - `written_off_amount` integer, required — The amount the issuer has chosen to write off
      - `denied_amount` integer, required — The amount that has been denied to the cardholder
      - `remaining_amount` integer, required — Any disputed amount that is still outstanding, i.e. has not been recovered, written off, or denied
    - `status` 'OPEN' | 'CLOSED' | 'null', nullable, required — Current status of the dispute.
    - `disposition` 'WON' | 'LOST' | 'PARTIALLY_WON' | 'WITHDRAWN' | 'DENIED' | 'null', nullable, required — Dispute resolution outcome
    - `events` Event[], required — Chronological list of events that have occurred in the dispute lifecycle
      - `token` string, uuid, required — Unique identifier for the event, in UUID format
      - `type` 'WORKFLOW' | 'FINANCIAL' | 'CARDHOLDER_LIABILITY', required — Type of event
      - `created` string, date-time, required — When the event occurred
      - `data` union, required — Details specific to the event type
        - WorkflowEventData — Details specific to workflow events
          - `type` 'WORKFLOW', required — Event type discriminator
          - `stage` 'CLAIM', required — Current stage of the dispute workflow
          - `action` 'OPENED' | 'CLOSED' | 'REOPENED', required — Action taken in this stage
          - `reason` string, nullable, required — Reason for the action
          - `amount` integer, nullable, required — Amount in minor units
          - `disposition` 'WON' | 'LOST' | 'PARTIALLY_WON' | 'WITHDRAWN' | 'DENIED' | 'null', nullable, required — Dispute resolution outcome
        - FinancialEventData — Details specific to financial events
          - `type` 'FINANCIAL', required — Event type discriminator
          - `stage` 'CHARGEBACK' | 'REPRESENTMENT' | 'PREARBITRATION' | 'ARBITRATION' | 'COLLABORATION', required — Stage at which the financial event occurred
          - `amount` integer, required — Amount in minor units
          - `polarity` 'CREDIT' | 'DEBIT', required — Direction of funds flow
        - CardholderLiabilityEventData — Details specific to cardholder liability events
          - `type` 'CARDHOLDER_LIABILITY', required — Event type discriminator
          - `action` 'PROVISIONAL_CREDIT_GRANTED' | 'PROVISIONAL_CREDIT_REVERSED' | 'WRITTEN_OFF', required — Action taken regarding cardholder liability
          - `amount` integer, required — Amount in minor units
          - `reason` string, required — Reason for the action
  - `has_more` boolean, required — Whether there are more results available

## Other responses

- `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 | Invalid or missing API key | | API key is not active | The API key used is no longer active | | Could not find API key | The API key provided is not associated with any user | | Please provide API key in Authorization header | The Authorization header is not in the request | | Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly | | Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at [lithic.com/contact](https://lithic.com/contact) | | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege | Reach out at [lithic.com/contact](https://lithic.com/contact) |
- `422` — Unprocessable entity.
- `429` — Client has exceeded the number of allowed requests in a given time period. | | | |---|---| | Rate limited, too many requests per second | User has exceeded their per second rate limit | | Rate limited, reached daily limit | User has exceeded their daily rate limit | | Rate limited, too many keys tried | One IP has queried too many different API keys |

---

[API](https://skmtc.net/lithic-com/apis/lithic-developer-api.md) · [All operations](https://skmtc.net/lithic-com/apis/lithic-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lithic-com/lithic-developer-api/revisions/53ab5d4e2adb/schema)