> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # List Disputes > List the tenant's customer-raised invoice disputes, optionally filtered by status. Returns the disputes customers have raised against the tenant's invoices, optionally narrowed to one status. A dispute is a customer's query against one of their invoices, raised from the [customer portal](/api-reference/portal/raise-dispute); it stays `open` until an operator closes it with [Resolve Dispute](/api-reference/disputes/resolve). Fetch a single one with [Get Dispute](/api-reference/disputes/get). There is no admin dashboard for disputes yet — this API is the current surface. ## Query Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------------------------------------------------------------- | | `status` | string | No | Filter to one status: `open`, `resolved` or `rejected`. Omit for all. | | `limit` | integer | No | Maximum rows returned. Default `1000`, capped at `1000`. | | `offset` | integer | No | Rows to skip, for paging past the cap. Default `0`. | ## Example Request ```bash theme={null} curl -G https://api.recurso.dev/v1/disputes \ -H "Authorization: Bearer $API_KEY" \ -d status=open ``` ## Response ```json theme={null} { "data": [ { "id": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8", "tenant_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b", "invoice_id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12", "customer_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f", "reason": "Charged for seats we removed in July", "status": "open", "note": null, "created_at": "2026-08-05T11:20:00Z", "resolved_at": null } ] } ``` The response carries no pagination metadata; page with `limit`/`offset` and stop when a page comes back short. ## Fields | Field | Type | Description | | ------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | | `id` | string (uuid) | The dispute's id | | `tenant_id` | string (uuid) | The tenant that owns the disputed invoice | | `invoice_id` | string (uuid) | The disputed invoice — fetch it with [Get Invoice](/api-reference/invoices/get) | | `customer_id` | string (uuid) | The customer who raised it | | `reason` | string | The customer's stated reason | | `status` | string | `open`, `resolved` (closed in the customer's favor) or `rejected` (reviewed and declined) | | `note` | string, nullable | Operator's resolution note; `null` while open | | `created_at` | string (date-time) | When the dispute was raised | | `resolved_at` | string (date-time), nullable | When it was closed; `null` while open | ## Errors | Status | Code | When | Fix | | ------ | ------------------- | ------------------------------------------------ | ------------------------------------------------- | | `400` | `validation_failed` | `status` is not `open`, `resolved` or `rejected` | Use one of the three statuses, or omit the filter | | `401` | `unauthorized` | Missing or invalid API key | Send a valid key in the `Authorization` header | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/disputes openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/disputes: get: tags: - Disputes summary: List invoice disputes (tenant-scoped) description: > Lists disputes for the authenticated tenant. There is no admin dashboard UI for disputes yet; this API is the current surface. operationId: listDisputes parameters: - name: limit in: query schema: type: integer default: 1000 maximum: 1000 description: Max rows returned (clamped to 1000). - name: offset in: query schema: type: integer minimum: 0 description: Rows to skip, for paging past the clamp. - name: status in: query required: false schema: type: string enum: - open - resolved - rejected description: Filter by dispute status. responses: '200': description: The tenant's disputes. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/InvoiceDispute' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: InvoiceDispute: type: object description: A customer-raised dispute/query against one of their invoices. properties: id: type: string format: uuid tenant_id: type: string format: uuid invoice_id: type: string format: uuid customer_id: type: string format: uuid reason: type: string status: type: string enum: - open - resolved - rejected description: >- open, resolved (closed in the customer's favor) or rejected (reviewed and declined). note: type: - string - 'null' description: Admin resolution note; null while open. created_at: type: string format: date-time resolved_at: type: - string - 'null' format: date-time Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````