> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decisionly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filing a Dispute

> Learn how to file disputes with the card network

## Filing a Case via API

Filing submits a dispute to the card network on behalf of the cardholder. For context on where filing fits in the dispute lifecycle, see [What Are Disputes?](/guide#the-dispute-lifecycle).

You can file a case using the [file case endpoint](/api-reference/v2-cases/file-a-case).

<CodeGroup>
  ```bash File a case with auto mode theme={null}
  curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \
    -u test_d0019b48d05849a6: \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "file_mode": "auto"
    }'
  ```

  ```bash File a case with chargeback mode theme={null}
  curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \
    -u test_d0019b48d05849a6: \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "file_mode": "chargeback"
    }'
  ```
</CodeGroup>

Once a case is filed with the card network, it cannot be modified or deleted.

## file\_mode Options

Cases support two filing modes:

**`auto`** - Your workflow rules will be evaluated and Decisionly will determine whether the case should be filed. This is the recommended mode for most use cases.

**`chargeback`** - Decisionly will attempt to file the case as a chargeback, regardless of your workflow rules. Use this when you want to bypass workflow rule evaluation.

## Queueing a Case That Is Too Early to File

Some card networks require a waiting period before filing for dispute types, for example a `credit_not_processed` chargeback cannot be filed until 15 days after the refund promise date for Visa. See [Filing Timelines](/filing-timelines) for the waiting period that applies to each network and dispute reason.

If you file a case before its waiting period has passed, the request fails with a `filing_too_early` validation error. Instead of tracking the earliest filing date yourself and retrying, you can pass `queue_if_too_early` to queue the case for automatic filing:

```bash Queue a case that is too early to file theme={null}
curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \
  -u test_d0019b48d05849a6: \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "file_mode": "auto",
    "queue_if_too_early": true
  }'
```

If the case is blocked only by a waiting period, the request returns `202 Accepted` and the case is queued. Decisionly will automatically file once its waiting period has passed. If you use file\_mode `auto`, your workflow rules will be run first, and the case will only be queued if it would have been filed but for the waiting period.

You can track queued cases through [webhooks](/webhooks): `case.queued` fires when the case is queued, `case.chargeback_filed` fires when it is later filed automatically, and `case.chargeback_needs_review` fires if it is removed from the queue for manual review.

<Note>
  Queueing is opt-in. Without `queue_if_too_early`, a case that is too early to
  file is rejected with a `filing_too_early` error and is never queued. The flag
  has no effect when the case fails validation for any other reason — those
  requests still return `400` with the full list of errors.
</Note>