> ## 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.

# Get Dispute

> Retrieve a single customer-raised invoice dispute by id — the addressable object behind the dashboard's dispute page.

Fetches a single dispute by id — the addressable object behind the
dashboard's dispute page. A dispute is a customer-raised query against one of
their invoices (raised from the [customer portal](/api-reference/portal/raise-dispute));
it is `open` until an admin resolves it with a note.

## Example Request

```bash theme={null}
curl "https://api.recurso.dev/v1/disputes/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" \
  -H "Authorization: Bearer $API_KEY"
```

## 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
  }
}
```

## Fields

| Field         | Type                         | Description                              |
| ------------- | ---------------------------- | ---------------------------------------- |
| `id`          | string (uuid)                | The dispute's id                         |
| `invoice_id`  | string (uuid)                | The disputed invoice                     |
| `customer_id` | string (uuid)                | The customer who raised it               |
| `reason`      | string                       | The customer's stated reason             |
| `status`      | string                       | `open` or `resolved`                     |
| `note`        | string, nullable             | Admin resolution note; `null` while open |
| `created_at`  | string (date-time)           | When the dispute was raised              |
| `resolved_at` | string (date-time), nullable | When it was resolved; `null` while open  |

## Errors

| Status | Code                | When                                                                                              | Fix                                             |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `400`  | `validation_failed` | `id` in the path is not a UUID                                                                    | Use the dispute's UUID                          |
| `404`  | `not_found`         | Dispute doesn't exist, or belongs to another tenant (existence is never confirmed across tenants) | Check the ID from the dashboard's Disputes page |

Errors use the standard envelope — see [Errors](/api-reference/errors).


## OpenAPI

````yaml GET /v1/disputes/{id}
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 <api_key>

    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/{id}:
    get:
      tags:
        - Disputes
      summary: Get one invoice dispute (tenant-scoped)
      description: >
        Fetches a single dispute by id — the addressable object behind the
        dashboard's dispute page. A missing or cross-tenant id returns 404.
      operationId: getDispute
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The dispute.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InvoiceDispute'
        '404':
          description: Dispute not found.
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
        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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Tenant API key obtained from `POST /auth/register` or `POST
        /v1/developer/keys`.

````