---
updatedAt: 2026-07-13T21:18:18.000Z
agentTools:
  siteIndex: https://docs.affirm.com/llms.txt
  projectIndex: https://docs.affirm.com/developers/llms.txt
---

# About Disputes API V3

Affirm has created a new version of our Disputes API to enable both Merchants and Partners to more seamlessly monitor and manage disputes.

# Overview

Disputes API V3 is the current recommended integration for all partners and merchants wanting to manage Affirm disputes from their own systems.

***

## Benefits

Dispute API V3 replaces Disputes API V1 with the following improvements:

* **Multi-file support**: V3 supports multiple files per evidence submission.
* **List Disputes**: V3 supports querying disputes by Merchant ID, opened date, and more.
* **More dispute details from the customer**: V3 provides new details that Affirm now collects from customers during dispute intake, such as return info and when the customer first contacted the merchant.
* **Clearer statuses**: V3 uses a new set of status enums that provide a clearer indication of when you need to take action.
* **Improved webhooks**: V3 provides enhanced dispute webhooks, which offer more information such as dispute status.

***

## API Reference

Explore the sections below to learn about the dispute endpoints and their requirements:

* <Anchor target="_blank" href="https://docs.affirm.com/developers/reference/get_dispute">Get Dispute</Anchor>
* <Anchor target="_blank" href="https://docs.affirm.com/developers/reference/close_dispute">Close Dispute</Anchor>
* <Anchor target="_blank" href="https://docs.affirm.com/developers/reference/submit_dispute_evidence">Submit Dispute Evidence</Anchor>
* <Anchor target="_blank" href="ref:listdisputes">List Disputes</Anchor>

***

## Dispute Lifecycle

```mermaid
flowchart LR
    %% Nodes
    Start([Start])
    End([End])

    ARCust[Action Required<br/>Customer]
    ARMerch[Action Required<br/>Merchant]
    ARAgent[Action Required<br/>Agent]

    ClosedCust[Closed<br/>Customer Favor]
    ClosedMerch[Closed<br/>Merchant Favor]

    %% Start paths
    Start -->|Customer evidence provided| ARMerch
    Start -->|No evidence| ARCust

    %% Customer action required
    ARCust -->|Evidence provided / declined| ARMerch
    ARAgent -->|More evidence requested| ARCust

    %% Merchant action required
    ARMerch -->|Evidence provided| ARAgent
    ARAgent -->|More evidence requested| ARMerch
    ARMerch -->|Merchant accepts and refunds| ClosedCust

    %% Agent adjudication
    ARAgent -->|Adjudication| ClosedCust
    ARAgent -->|Adjudication| ClosedMerch

    %% End states
    ClosedCust --> End
    ClosedMerch --> End

    %% Styling
    classDef action fill:#FFD84D,stroke:#000,color:#000,font-weight:bold;
    classDef terminal fill:#FFFFFF,stroke:#000,color:#000,font-weight:bold;

    class ARCust,ARMerch,ARAgent,ClosedCust,ClosedMerch action;
    class Start,End terminal;

```

***

## Basic Requirements

### Authentication

Dispute API V3 supports both partner and merchant level API keys. Partners can only access dispute information for disputes that are for merchants on their platform.

### Idempotency

For idempotent requests, the idempotency key has an **expiration date of 24 hours**. Idempotency keys are passed in using the **Idempotency-Key header**.

***

## Dispute Webhooks

When a dispute is **created**, **updated** or **resolved**, we send webhooks to inform you of a change in the state of the dispute. You can then use our `get_dispute` endpoint to review the latest dispute snapshot after the state change.

### Dispute Events

The following are instances where webhooks are sent as part of the Disputes API:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Dispute Event Description
      </th>

      <th>
        Event Type
      </th>

      <th>
        Additional Notes
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Dispute opened
      </td>

      <td>
        `purchase_dispute_opened`
      </td>

      <td>
        Webhook sent when a new dispute is opened and funds are withheld from the merchant.

        The dispute may or may not require merchant action (conveyed via `dispute_status`), depending on if customer evidence was already collected.

        Possible `dispute_status` values:

        - `action_required_merchant`
        - `no_merchant_action_needed`
      </td>
    </tr>

    <tr>
      <td>
        Merchant submits evidence
      </td>

      <td>
        `purchase_dispute_updated`
      </td>

      <td>
        Webhook sent whenever a dispute is updated and requires action from the merchant.

        Possible `dispute_status` values:

        - `action_required_merchant`
      </td>
    </tr>

    <tr>
      <td>
        Dispute closed
      </td>

      <td>
        `purchase_dispute_resolved`
      </td>

      <td>
        Webhook sent after the dispute has been closed in favor of either the merchant or customer.

        Possible `dispute_status` values:

        - `closed_customer_favor`
        - `closed_merchant_favor`
        - `closed_customer_partial_favor`
      </td>
    </tr>
  </tbody>
</Table>

### purchase\_dispute\_opened

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Data Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `event_type`
      </td>

      <td>
        string
      </td>

      <td>
        `purchase_dispute_opened`
      </td>
    </tr>

    <tr>
      <td>
        event\_id
      </td>

      <td>
        string
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        event\_timestamp
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `created`
      </td>

      <td>
        date-time
      </td>

      <td>
        The date and time of the event.
      </td>
    </tr>

    <tr>
      <td>
        `transaction_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of transaction that dispute is for
      </td>
    </tr>

    <tr>
      <td>
        `order_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of provided by partner/merchant for transaction (see checkout and transaction APIs)
      </td>
    </tr>

    <tr>
      <td>
        `dispute_id`
      </td>

      <td>
        string
      </td>

      <td>
        Unique identifier for the dispute that the webhook corresponds to.
      </td>
    </tr>

    <tr>
      <td>
        `merchant_id`
      </td>

      <td>
        string
      </td>

      <td>
        Unique Affirm identifier for the merchant.
      </td>
    </tr>

    <tr>
      <td>
        `dispute_status`
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the status of a dispute. Possible values:

        - `action_required_merchant`
        - `no_merchant_action_needed`
      </td>
    </tr>

    <tr>
      <td>
        `dispute_reason`
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the reason for a dispute status. Possible values:

        - `cancellation_or_return_not_processed`
        - `incorrect_amount`
        - `product_not_received`
        - `product_unacceptable`
        - `cancellation_not_processed`
        - `return_not_processed`
      </td>
    </tr>

    <tr>
      <td>
        `transaction_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Amount of transaction that dispute is associated with in the smallest denomination of the currency, such as cents.
      </td>
    </tr>

    <tr>
      <td>
        `dispute_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Dispute amount in the smallest denomination of the currency, such as cents.
      </td>
    </tr>

    <tr>
      <td>
        `currency`
      </td>

      <td>
        string
      </td>

      <td>
        The local currency of the dispute. Must be a valid subset of the ISO 4217 currency code.
      </td>
    </tr>

    <tr>
      <td>
        `response_due_by`
      </td>

      <td>
        date-time
      </td>

      <td>
        Deadline for evidence submission, will be null until merchant action is required
      </td>
    </tr>

    <tr>
      <td>
        `customer_won_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Amount of dispute that customer has won, will be null until the dispute is closed
      </td>
    </tr>
  </tbody>
</Table>

#### Example:

```json
{
created: "2026-03-09T16:58:18.377000Z",
currency: "USD",
customer_won_amount: null,
dispute_amount: 11500,
dispute_id: "EKZP6EBDPBANQE7T",
dispute_reason: "cancellation_or_return_not_processed",
dispute_status: "no_merchant_action_needed",
event_id: "239fbad1-2d78-42d3-9f05-697a5a12fdfd",
event_timestamp: "2026-03-09T16:58:19Z",
event_type: "purchase_dispute_opened",
merchant_id: "0XWX3IT8HD2VOH4Q",
order_id: "test",
response_due_by: null,
transaction_amount: 11500,
transaction_id: "5S30-RRG7"

}
```

### purchase\_dispute\_updated

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Data Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `event_type`
      </td>

      <td>
        string
      </td>

      <td>
        `purchase_dispute_updated`
      </td>
    </tr>

    <tr>
      <td>
        `created`
      </td>

      <td>
        date-time
      </td>

      <td>
        The date and time of the event.
      </td>
    </tr>

    <tr>
      <td>
        `transaction_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of transaction that dispute is for
      </td>
    </tr>

    <tr>
      <td>
        `order_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of provided by partner/merchant for transaction (see checkout and transaction APIs)
      </td>
    </tr>

    <tr>
      <td>
        `dispute_id`
      </td>

      <td>
        string
      </td>

      <td>
        Unique identifier for the dispute that the webhook corresponds to.
      </td>
    </tr>

    <tr>
      <td>
        `merchant_id`
      </td>

      <td>
        string
      </td>

      <td>
        Unique Affirm identifier for the merchant.
      </td>
    </tr>

    <tr>
      <td>
        `dispute_status`
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the status of a dispute. Possible values:

        - `action_required_merchant`
      </td>
    </tr>

    <tr>
      <td>
        `dispute_reason`
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the reason for a dispute status. Possible values:

        - `cancellation_or_return_not_processed`
        - `incorrect_amount`
        - `product_not_received`
        - `product_unacceptable`
        - `cancellation_not_processed`
        - `return_not_processed`
      </td>
    </tr>

    <tr>
      <td>
        `transaction_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Amount of transaction that dispute is associated with in the smallest denomination of the currency, such as cents.
      </td>
    </tr>

    <tr>
      <td>
        `dispute_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Dispute amount in the smallest denomination of the currency, such as cents.
      </td>
    </tr>

    <tr>
      <td>
        `currency`
      </td>

      <td>
        string
      </td>

      <td>
        The local currency of the dispute. Must be a valid subset of the ISO 4217 currency code.
      </td>
    </tr>

    <tr>
      <td>
        `response_due_by`
      </td>

      <td>
        date-time
      </td>

      <td>
        Deadline for evidence submission, will be null until merchant action is required
      </td>
    </tr>

    <tr>
      <td>
        `customer_won_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Amount of dispute that customer has won, will be null until the dispute is closed
      </td>
    </tr>
  </tbody>
</Table>

#### Example:

```json
{
created: "2026-03-09T17:41:37.277000Z",
currency: "USD",
customer_won_amount: null,
dispute_amount: 11500,
dispute_id: "EKZP6EBDPBANQE7T",
dispute_reason: "cancellation_or_return_not_processed",
dispute_status: "action_required_merchant",
event_id: "1512005e-807b-404c-8d2b-5cfff33f13e1",
event_timestamp: "2026-03-09T17:41:38Z",
event_type: "purchase_dispute_updated",
merchant_id: "0XWX3IT8HD2VOH4Q",
order_id: "test",
response_due_by: "2026-03-24T17:41:37.257000Z",
transaction_amount: 11500,
transaction_id: "5S30-RRG7"

}
```

### purchase\_dispute\_resolved

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Data Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `event_type`
      </td>

      <td>
        string
      </td>

      <td>
        `purchase_dispute_resolved`
      </td>
    </tr>

    <tr>
      <td>
        `created`
      </td>

      <td>
        date-time
      </td>

      <td>
        The date and time of the event.
      </td>
    </tr>

    <tr>
      <td>
        `transaction_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of transaction that dispute is for
      </td>
    </tr>

    <tr>
      <td>
        `order_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of provided by partner/merchant for transaction (see checkout and transaction APIs)
      </td>
    </tr>

    <tr>
      <td>
        `dispute_id`
      </td>

      <td>
        string
      </td>

      <td>
        Unique identifier for the dispute that the webhook corresponds to.
      </td>
    </tr>

    <tr>
      <td>
        `merchant_id`
      </td>

      <td>
        string
      </td>

      <td>
        Unique Affirm identifier for the merchant.
      </td>
    </tr>

    <tr>
      <td>
        `dispute_status`
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the status of a dispute. Possible values:

        - `closed_merchant_favor `
        - `closed_customer_favor`
        - `closed_customer_partial_favor`
      </td>
    </tr>

    <tr>
      <td>
        `dispute_reason`
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the reason for a dispute status. Possible values:

        - `cancellation_or_return_not_processed`
        - `incorrect_amount`
        - `product_not_received`
        - `product_unacceptable`
        - `cancellation_not_processed`
        - `return_not_processed`
      </td>
    </tr>

    <tr>
      <td>
        `transaction_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Amount of transaction that dispute is associated with in the smallest denomination of the currency, such as cents.
      </td>
    </tr>

    <tr>
      <td>
        `dispute_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Dispute amount in the smallest denomination of the currency, such as cents.
      </td>
    </tr>

    <tr>
      <td>
        `currency`
      </td>

      <td>
        string
      </td>

      <td>
        The local currency of the dispute. Must be a valid subset of the ISO 4217 currency code.
      </td>
    </tr>

    <tr>
      <td>
        `response_due_by`
      </td>

      <td>
        date-time
      </td>

      <td>
        Deadline for evidence submission, will be null until merchant action is required
      </td>
    </tr>

    <tr>
      <td>
        `customer_won_amount`
      </td>

      <td>
        integer
      </td>

      <td>
        Amount of dispute that customer has won, will be null until the dispute is closed
      </td>
    </tr>
  </tbody>
</Table>

#### Example:

```json
{
created: "2026-03-09T17:54:22.435000Z",
currency: "USD",
customer_won_amount: 11500,
dispute_amount: 11500,
dispute_id: "EKZP6EBDPBANQE7T",
dispute_reason: "cancellation_or_return_not_processed",
dispute_status: "closed_customer_favor",
event_id: "cf35caa0-19f1-48b6-9607-71dfd04c1202",
event_timestamp: "2026-03-09T17:54:22Z",
event_type: "purchase_dispute_resolved",
merchant_id: "0XWX3IT8HD2VOH4Q",
order_id: "test",
response_due_by: null,
transaction_amount: 11500,
transaction_id: "5S30-RRG7"

}
```

<br />

# Sibling pages

* [Dispute API V1 to V3 Changelog](https://docs.affirm.com/developers/reference/dispute-api-v1-to-v3-changelog.md)
* [Disputes API (V3)](https://docs.affirm.com/developers/reference/disputes-api-v3.md)