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

# List Disputes

`GET /v1/disputes`

Returns a list of your disputes, most recent first.

Evidence is omitted by default; pass `expand=evidence` to include the parsed evidence for each dispute.

## Query parameters

- `limit` integer, nullable — Maximum number of disputes to return (default 20, max 100).
- `starting_after` string, nullable — A cursor for use in pagination. `starting_after` is a dispute ID that defines your place in the list. For instance, if you make a list request and receive 20 disputes, ending with `fdp_xyz`, your subsequent call can include `starting_after=fdp_xyz` to fetch the next page of the list.
- `ending_before` string, nullable — A cursor for use in pagination. `ending_before` is a dispute ID that defines your place in the list. For instance, if you make a list request and receive 20 disputes, starting with `fdp_abc`, your subsequent call can include `ending_before=fdp_abc` to fetch the previous page of the list.
- `charge` string, nullable — Filter by charge ID.
- `payment_intent` string, nullable — Filter by payment intent ID.
- `statuses` DisputeStatus[], nullable — Filter by dispute statuses (comma-separated, e.g. `?statuses=needs_response,under_review`).
  - union — The current status of a dispute.
    - 'lost' | 'needs_response' | 'under_review' | 'warning_closed' | 'warning_needs_response' | 'warning_under_review' | 'won'
    - 'prevented' — The dispute was prevented before reaching the card network.
- `expand` string — Comma-separated list of fields to expand (e.g., `?expand=evidence`).

## Response `200`

An envelope wrapping a list of dispute objects.

- MultipleDisputesBodyForDispute — An envelope wrapping a list of dispute objects.
  - `disputes` Dispute[], required — The list of disputes.
    - `dispute_id` string, required — Unique identifier for the dispute, prefixed with `fdp_`.
    - `payment_intent_id` string, required — ID of the PaymentIntent that was disputed.
    - `checkout_session_id` string, nullable — ID of the Checkout Session associated with the disputed payment. `null` if the payment was not created via a checkout session.
    - `amount` integer, required — Disputed amount, in the smallest currency unit (e.g., `2500` = $25.00 USD). Usually the full amount of the disputed payment.
    - `currency` string, required — Three-letter ISO currency code, in lowercase (e.g., `usd`).
    - `charge_id` string, nullable — ID of the Charge that was disputed. `null` if the originating charge could not be resolved.
    - `metadata` object, required — Set of key-value pairs attached to the dispute for storing additional structured information.
    - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
    - `status` union, required — The current status of a dispute.
      - 'lost' | 'needs_response' | 'under_review' | 'warning_closed' | 'warning_needs_response' | 'warning_under_review' | 'won'
      - 'prevented' — The dispute was prevented before reaching the card network.
    - `reason` 'bank_cannot_process' | 'check_returned' | 'credit_not_processed' | 'customer_initiated' | 'debit_not_authorized' | 'duplicate' | 'fraudulent' | 'general' | 'incorrect_account_details' | 'insufficient_funds' | 'noncompliant' | 'product_not_received' | 'product_unacceptable' | 'subscription_canceled' | 'unrecognized', required — The reason for the dispute, as reported by the card network.
    - `is_charge_refundable` boolean, required — Whether the disputed charge can still be refunded. Once a payment is disputed, refunding it is typically no longer possible.
    - `evidence` DisputeEvidenceResponse — Evidence collected to respond to a dispute, with file references resolved to Flex file IDs.
      - `access_activity_log` string, nullable — A description of the activity on the customer's account or the order, showing that they accessed or used the product or service.
      - `customer_name` string, nullable — The name of the customer.
      - `customer_email_address` string, nullable — The email address of the customer.
      - `customer_purchase_ip` string, nullable — The IP address from which the customer made the purchase.
      - `billing_address` string, nullable — The billing address provided by the customer.
      - `shipping_address` string, nullable — The address to which a physical product was shipped.
      - `shipping_tracking_number` string, nullable — The tracking number for a physical product shipped to the customer.
      - `shipping_carrier` string, nullable — The delivery service that shipped a physical product (e.g., `usps`, `fedex`).
      - `shipping_date` string, nullable — The date on which a physical product was shipped to the customer.
      - `service_date` string, nullable — The date on which the service was provided to the customer.
      - `product_description` string, nullable — A description of the product or service purchased and an explanation of why the customer's claim is unwarranted.
      - `refund_policy_disclosure` string, nullable — Your refund policy as shown to the customer.
      - `refund_refusal_explanation` string, nullable — An explanation of why the customer is not entitled to a refund.
      - `cancellation_policy_disclosure` string, nullable — Your cancellation policy as shown to the customer.
      - `cancellation_rebuttal` string, nullable — An explanation of how the customer was shown that the subscription or service was not canceled.
      - `duplicate_charge_explanation` string, nullable — An explanation of the difference between the disputed payment and the charge the customer believes is a duplicate.
      - `duplicate_charge_id` string, nullable — The ID of the charge the customer claims is a duplicate of the disputed charge.
      - `uncategorized_text` string, nullable — Any additional evidence as free-form text.
      - `customer_communication` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `customer_signature` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `shipping_documentation` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `receipt` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `duplicate_charge_documentation` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `service_documentation` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `uncategorized_file` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `cancellation_policy` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
      - `refund_policy` EvidenceFileInfo — A reference to a file attached as dispute evidence.
        - `file_id` string, nullable — The Flex file ID (e.g., `ffile_xxx`).
        - `filename` string, nullable — The original filename from upload.
        - `stripe_file_id` string, nullable — Underlying card-network file ID, present when the file could not be matched to a Flex file ID.
    - `evidence_details` EvidenceDetails — Details about the evidence submission deadline and status.
      - `due_by` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
      - `has_evidence` boolean, required — Whether evidence has been submitted
      - `past_due` boolean, required — Whether the evidence deadline has passed
      - `submission_count` integer, required — Number of times evidence has been submitted
    - `balance_transactions` DisputeBalanceTransactionInfo[], nullable — Balance transactions that record the funds withdrawn and returned as the dispute progresses (e.g., the initial debit and any reversal). An empty array when there are none.
      - `balance_transaction_id` string, required — ID of the balance transaction, prefixed with `fbtxn_`.
      - `amount` integer, required — Gross amount of the transaction, in the smallest currency unit (e.g., `2500` = $25.00 USD). Negative when funds are withdrawn from your balance.
      - `fee` integer, required — Fee applied to the transaction, in the smallest currency unit (e.g., `1500` = $15.00 USD). For a dispute, this is typically the dispute (chargeback) fee.
      - `net` integer, required — Net amount applied to your balance after fees, in the smallest currency unit (`net = amount - fee`).
      - `status` 'available' | 'pending', required — Availability status of the funds in a balance transaction. - `available`: Funds have settled and are available to be paid out. - `pending`: Funds are not yet available.
      - `type` string, nullable — The type of balance transaction (e.g., `adjustment`). `null` when not classified.
      - `reporting_category` string, nullable — The reporting category used to group the transaction in financial reports.
      - `category` string, nullable — The role this transaction plays within the dispute (e.g., the initial debit or a reversal). `null` when not categorized.
      - `created_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
    - `payment_method_details` DisputePaymentMethodDetails — Details of the payment method that was disputed.
      - `type` string, required — The type of payment method that was disputed (e.g., `card`).
      - `card` DisputePaymentMethodCard — Card-specific details for a disputed payment made with a card.
        - `brand` string, nullable — The card brand. `null` when unknown.
        - `network_reason_code` string, nullable — The reason code the card network assigned to the dispute, as reported by the issuer.
    - `test_mode` boolean, required — Whether the dispute was created in test mode. `true` for disputes created with test API keys.
    - `client_reference_id` string, nullable — Your own identifier for the customer or payment this dispute relates to, copied from the originating payment.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too Many Requests

---

[API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)