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

# Resolve Dispute

> Close an open invoice dispute with an operator decision — accept it (optionally issuing an adjustment credit note against the invoice) or reject it — and a note.

Records the operator's decision on an open dispute and closes it. Accepting
(the default) moves the dispute to `resolved`; rejecting moves it to
`rejected`. Either way the optional `note` is stored on the dispute and
`resolved_at` is set. Only an `open` dispute can be resolved — a dispute that
is already closed returns `404`.

On accept you may also issue an adjustment credit note against the disputed
invoice with `issue_credit: true`. The credit goes through the ordinary
[credit-note create path](/api-reference/credit-notes/create) — fully ledgered,
reason `dispute_resolution`, type `adjustment` — and is issued *before* the
dispute is closed: if the credit fails, the dispute stays `open` for a clean
retry, never a resolved dispute with no promised credit. Maker-checker applies:
a credit issued by a non-admin user lands in `pending_approval`; API keys and
admin/owner users issue directly.

Find open disputes with [List Disputes](/api-reference/disputes/list) and read
one with [Get Dispute](/api-reference/disputes/get).

## Path Parameters

| Parameter | Type          | Required | Description       |
| --------- | ------------- | -------- | ----------------- |
| `id`      | string (uuid) | Yes      | The dispute's id. |

## Request Body

The body is optional; an empty body accepts the dispute with no note and no credit.

| Parameter       | Type            | Required | Description                                                                                                                                        |
| --------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcome`       | string          | No       | `accept` (default) closes the dispute in the customer's favor; `reject` declines it.                                                               |
| `note`          | string          | No       | Operator's resolution note, stored on the dispute.                                                                                                 |
| `issue_credit`  | boolean         | No       | Accept only. When `true`, issues an adjustment credit note against the disputed invoice. Ignored on reject.                                        |
| `credit_amount` | integer (int64) | No       | Credit amount in minor units. `0` (or omitted) means the invoice's amount still due, falling back to its total. Must not exceed the invoice total. |

## Example Request

```bash theme={null}
curl -X POST "https://api.recurso.dev/v1/disputes/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8/resolve" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "accept",
    "note": "Seats were removed on 12 July; crediting the two extra seats.",
    "issue_credit": true,
    "credit_amount": 4800
  }'
```

## Response

The response is a bare object — not wrapped in `data`. `status` is `resolved`
on accept and `rejected` on reject. `credit_note` is present only when a
credit was issued.

```json theme={null}
{
  "status": "resolved",
  "credit_note": {
    "id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
    "tenant_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "customer_id": "0b7a3f7e-4a2b-4c1d-9e8f-1a2b3c4d5e6f",
    "invoice_id": "06c151de-8d3a-4b21-9c77-2f0e5a9b4d12",
    "reference": "CN-1757001600",
    "amount": 4800,
    "balance": 4800,
    "currency": "USD",
    "status": "issued",
    "reason": "dispute_resolution",
    "type": "adjustment",
    "refund_status": "none",
    "created_at": "2026-09-04T16:00:00Z",
    "updated_at": "2026-09-04T16:00:00Z"
  }
}
```

A rejection, or an accept without a credit, returns just the status:

```json theme={null}
{
  "status": "rejected"
}
```

## Fields

| Field         | Type   | Description                                                                                                                                                                                                            |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`      | string | `resolved` (accepted) or `rejected` — the dispute's new status                                                                                                                                                         |
| `credit_note` | object | The credit note issued, when `issue_credit` was `true` on accept. Same shape as [Get Credit Note](/api-reference/credit-notes/get); `amount` and `balance` are minor units, `status` is `issued` or `pending_approval` |

## Errors

| Status | Code                | When                                                                                                                                                                                               | Fix                                                                                           |
| ------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `400`  | `validation_failed` | `id` in the path is not a UUID; the body is not valid JSON; `outcome` is not `accept` or `reject`; or `credit_amount` is negative                                                                  | Fix the offending field                                                                       |
| `404`  | `not_found`         | Dispute doesn't exist, belongs to another tenant (existence is never confirmed across tenants), or is no longer `open`                                                                             | Check the dispute via [List Disputes](/api-reference/disputes/list) with `status=open`        |
| `500`  | `internal_error`    | Credit issuance was refused — `credit_amount` exceeds the invoice total, the disputed invoice could not be loaded, or credit issuance is not enabled on this deployment. The dispute stays `open`. | Retry with a `credit_amount` at or below the invoice total, or resolve without `issue_credit` |

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


## OpenAPI

````yaml POST /v1/disputes/{id}/resolve
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}/resolve:
    post:
      tags:
        - Disputes
      summary: Resolve an open dispute (tenant-scoped)
      operationId: resolveDispute
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Dispute ID.
      requestBody:
        required: false
        description: >-
          Optional; an empty body accepts the dispute with no note and no
          credit.
        content:
          application/json:
            schema:
              type: object
              properties:
                outcome:
                  type: string
                  enum:
                    - accept
                    - reject
                  default: accept
                  description: >
                    accept (default) closes the dispute in the customer's favor
                    (status → resolved); reject declines it (status → rejected).
                note:
                  type: string
                  description: Optional admin resolution note.
                issue_credit:
                  type: boolean
                  default: false
                  description: >
                    Accept only. When true, issues an adjustment credit note
                    (reason dispute_resolution) against the disputed invoice
                    before the dispute is closed. Ignored on reject.
                credit_amount:
                  type: integer
                  format: int64
                  minimum: 0
                  description: >
                    Credit amount in minor units. 0 or omitted means the
                    invoice's amount still due (falling back to its total). Must
                    not exceed the invoice total (today that violation surfaces
                    as 500, not 400; 400 covers only a malformed body, an
                    unknown outcome, or a negative credit_amount).
      responses:
        '200':
          description: >
            Dispute resolved. Action-shape `{status}` object (not the Dispute
            resource, not wrapped in data); credit_note is present only when a
            credit was issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - resolved
                      - rejected
                    example: resolved
                  credit_note:
                    $ref: '#/components/schemas/CreditNote'
                    description: Present only when issue_credit was true on accept.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    CreditNote:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        customer_id:
          type: string
          format: uuid
        invoice_id:
          type:
            - string
            - 'null'
          format: uuid
        entity_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Legal entity that issued the credit note (Multi-Entity Books);
            inherits the referenced invoice's entity.
        reference:
          type:
            - string
            - 'null'
        amount:
          type: integer
          format: int64
        subtotal:
          type: integer
          format: int64
          description: >-
            Taxable (net-of-tax) value of the credit, minor units. Present
            (non-zero) when the note recorded a tax breakdown at creation —
            invoice-linked credits slice the invoice's tax proportionally,
            downgrade credits carry the reversed proration tax. 0 on legacy rows
            and standalone goodwill credits (gross-only).
        tax_amount:
          type: integer
          format: int64
          description: Tax reversed by this credit, minor units.
        igst_amount:
          type: integer
          format: int64
        cgst_amount:
          type: integer
          format: int64
        sgst_amount:
          type: integer
          format: int64
        tax_type:
          type: string
          description: >-
            Tax regime of the breakdown (e.g. inter_state, intra_state); empty
            when none recorded.
        hsn_code:
          type: string
        balance:
          type: integer
          format: int64
          description: Remaining unapplied credit.
        currency:
          type: string
        status:
          type: string
          enum:
            - issued
            - used
            - void
            - pending_approval
            - rejected
            - expired
        reason:
          type: string
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When a dated adjustment credit lapses; null = never expires.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        customer:
          $ref: '#/components/schemas/Customer'
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type:
            - string
            - 'null'
        phone:
          type: string
        tax_id:
          type:
            - string
            - 'null'
        billing_address:
          $ref: '#/components/schemas/BillingAddress'
        ledger_account_id:
          type: string
          format: uuid
        gstin:
          type:
            - string
            - 'null'
        tax_type:
          type: string
        place_of_supply:
          type:
            - string
            - 'null'
        tax_exempt:
          type: boolean
        tax_exemption_number:
          type: string
        tax_exemption_code:
          type: string
        tax_exemption_expires_at:
          type:
            - string
            - 'null'
          format: date
        referral_code:
          type:
            - string
            - 'null'
        risk_score:
          type: integer
          minimum: 0
          maximum: 100
        risk_factors:
          type:
            - object
            - 'null'
        card_brand:
          type: string
        card_last4:
          type: string
        card_exp_month:
          type: integer
        card_exp_year:
          type: integer
        card_token_id:
          type: string
        card_fingerprint:
          type: string
        created_at:
          type: string
          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.
    BillingAddress:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        postal_code:
          type: string
          description: Synonym for zip.
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
  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'
    NotFound:
      description: The requested resource does not exist.
      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`.

````