---
updatedAt: 2026-03-18T22:03:53.000Z
agentTools:
  siteIndex: https://docs.affirm.com/llms.txt
  projectIndex: https://docs.affirm.com/developers/llms.txt
---

# Dispute API V1 to V3 Changelog

Learn more about the improvements that come with the V3 Disputes API, which is for both merchants and partners.

## Overview

Affirm delivers the V3 Disputes API, which offers a cleaner API experience with full support for listing disputes via query params and pagination, richer dispute context via structured evidence fields, and a simplified URL structure.

All new integrations should use V3. V1 will remain available for existing partners, but won't receive further enhancements.

### Authentication

While V1 had separate APIs for merchants and partners, V3 is a unified API for both merchant and partner API keys.

### Base URL

```
# V1
/api/partner/v1/merchants/{merchant_id}/disputes

# V3
/api/v3/disputes
```

***

## `GET /{dispute_id}`

### Response body: ` status` updates

The `status` field, which appears on the response object, is also accepted as a query parameter when listing disputes. V3 introduces new status enums with clearer descriptors.

#### V1 to V3 mapping:

| V1 Value        | V3 Equivalent                   |
| --------------- | ------------------------------- |
| `needs_review`  | `action_required_merchant`      |
| `under_review`  | `no_merchant_action_needed`     |
| `lost`          | `closed_customer_favor`         |
| `won`           | `closed_merchant_favor`         |
| `partially_won` | `closed_customer_partial_favor` |

<Callout icon="📘" theme="info">
  **Note:** The five V1 statuses (`lost`, `needs_review`, `partially_won`, `under_review`, `won`) aren't returned by V3 and aren't accepted as `status` filter values. If your V1 integration relied on these values, you must instead map to the 5 new statuses or use a closed-open state logic based on `closed_at`.
</Callout>

### Response body: Renamed fields

| V1 Field                   | V3 Field           | Notes                                                                                              |
| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| `amount`                   | `dispute_amount`   | Same field, only renamed                                                                           |
| `reason`                   | `dispute_reason`   | Same field, only renamed                                                                           |
| `opening_note`             | `comments[]`       | The new field is an array of strings, rather than a single string.                                 |
| `opening_note_attachments` | `attached_files[]` | The new field is an array of `{file_name, file_url}` objects, rather than a single file ID string. |

### Response body: Removed fields

| V1 Field         | Notes                                                          |
| ---------------- | -------------------------------------------------------------- |
| `open`           | Use `status` to determine whether a dispute is open or closed. |
| `closing_reason` | Removed                                                        |
| `closing_note`   | Removed                                                        |

### Response body: New fields

| V3 Field             | Type                | Description                                                                         |
| -------------------- | ------------------- | ----------------------------------------------------------------------------------- |
| `order_id`           | string (nullable)   | Your internal merchant order ID associated with the dispute.                        |
| `transaction_amount` | integer (nullable)  | The original transaction amount in the smallest currency denomination (e.g. cents). |
| `updated`            | datetime (nullable) | Timestamp of when the dispute was last updated.                                     |
| `extra_evidence[]`   | array (nullable)    | Structured evidence submitted against the dispute.                                  |

Each item in `extra_evidence[]` can contain one of the following structured objects:

| Object               | Fields                                                                             |
| -------------------- | ---------------------------------------------------------------------------------- |
| `shipping_info`      | `company_name`, `tracking_number`, `delivery_date`                                 |
| `communication_info` | `contact_type`, `first_contact_date`, `last_contact_date`, `merchant_contact_name` |
| `return_info`        | `type`, `method`, `return_date`, `store_address`, `shipping_information`           |

#### Example:

```json
"extra_evidence": [
      {
          "communication_info": {
              "contact_type": "already_contacted",
              "merchant_contact_name": "Test Contact",
              "first_contact_date": "2025-12-30T00:00:00Z",
              "last_contact_date": "2026-01-30T00:00:00Z"
          }
      },
      {
          "shipping_info": {
              "company_name": "usps",
              "tracking_number": "12312312312",
              "delivery_date": "2025-12-30T00:00:00Z"
          }
      },
      {
          "return_info": {
              "type": "all",
              "return_date": "2025-12-30T00:00:00Z",
              "method": "in_store",
              "store_address": "123 Harbrook Lane"
          }
      }
  ]
```

### Response body: `transition_logs` changes

Within the `transition_logs` object, we simplify the `DisputeEvent` object significantly by removing the following V1 fields:

| Removed V1 Field             | Notes                             |
| ---------------------------- | --------------------------------- |
| `id`                         | Event ID no longer returned.      |
| `dispute_id`                 | Redundant, given request context. |
| `is_financial`               | Removed                           |
| `financial_amount`           | Removed                           |
| `financial_amount_currency`  | Removed                           |
| `financial_transaction_type` | Removed                           |
| `dispute_snapshot`           | Removed                           |

<Callout icon="📘" theme="info">
  **Note:** The V3 `DisputeEvent` field contains only `type` (string) and `created` (datetime).
</Callout>

#### Example:

```json
"transition_logs": [
      {
          "type": "created",
          "created": "2026-03-04T02:29:19Z"
      },
      {
          "type": "customer_evidence_added",
          "created": "2026-03-04T02:29:19Z"
      }
  ]
```

***

## `GET / [List Disputes]`

With the V3 Disputes API, we introduce support for listing disputes via query parameters with pagination. The following parameters are available:

* `merchant_id`: Required for partners.
* `status`
* `dispute_reason`
* `created_before`
* `created_after`
* `resolved_before`
* `resolved_after`
* `limit`
* `page_number`: Set to 1 by default.

***

## `POST /{dispute_id}/close`

No changes to the request body. However, the response body includes the updated `DisputeEvent` object. (See the [Response body: transition\_logs changes](https://docs.affirm.com/developers/reference/dispute-api-v1-to-v3-changelog#response-body-transition_logs-changes) section for details.)

***

## `POST /{dispute_id}/submit_evidence`

### Request body: Renamed or restructured fields

| V1 Field              | V3 Equivalent | Notes                                                                                |
| --------------------- | ------------- | ------------------------------------------------------------------------------------ |
| `evidence_file_token` | `file_ids[]`  | Required. The V3 field is an array of file ID strings, rather than a single value.   |
| *(absent)*            | `comment`     | Required. You can now add a comment or summary accompanying the evidence submission. |

### Request body: New `extra_evidence[]` array

Currently for the new array, merchants and partners can only provide `shipping_info`:

| Object          | Fields                                             |
| --------------- | -------------------------------------------------- |
| `shipping_info` | `company_name`, `tracking_number`, `delivery_date` |

<br />

## Webhooks

Along with updates to the API, we've additionally added new fields to **purchase\_dispute\_opened**, **purchase\_dispute\_updated,** and **purchase\_dispute\_resolved** webhooks.

### purchase\_dispute\_opened

#### Request body: new fields

| Field                 | Type              | Notes                                           |
| :-------------------- | :---------------- | :---------------------------------------------- |
| currency              | string (ISO 4217) |                                                 |
| customer\_won\_amount | integer           | Will be null until dispute is closed            |
| dispute\_amount       | integer           |                                                 |
| dispute\_reason       | string-enum       |                                                 |
| dispute\_status       | string-enum       | Will use same enums as Dispute API V3 responses |
| response\_due\_by     | string (ISO 8601) | Will be null is merchant action is not required |
| transaction\_amount   | integer           |                                                 |
| transaction\_id       | string            |                                                 |

**Example Payload**\*\*

```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\_disputed\_updated

| Field                 | Type              | Notes                                           |
| :-------------------- | :---------------- | :---------------------------------------------- |
| currency              | string (ISO 4217) |                                                 |
| customer\_won\_amount | integer           | Will be null until dispute is closed            |
| dispute\_amount       | integer           |                                                 |
| dispute\_reason       | string-enum       |                                                 |
| dispute\_status       | string-enum       | Will use same enums as Dispute API V3 responses |
| response\_due\_by     | string (ISO 8601) |                                                 |
| transaction\_amount   | integer           |                                                 |
| transaction\_id       | string            |                                                 |

```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\_disputed\_closed

| Field                 | Type              | Notes                                           |
| --------------------- | ----------------- | ----------------------------------------------- |
| currency              | string (ISO 4217) |                                                 |
| customer\_won\_amount | integer           |                                                 |
| dispute\_amount       | integer           |                                                 |
| dispute\_reason       | string-enum       |                                                 |
| dispute\_status       | string-enum       | Will use same enums as Dispute API V3 responses |
| response\_due\_by     | string (ISO 8601) | Will be null is merchant action is not required |
| transaction\_amount   | integer           |                                                 |
| transaction\_id       | string            |                                                 |

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

* [About Disputes API V3](https://docs.affirm.com/developers/reference/about-disputes-api-v3.md)
* [Disputes API (V3)](https://docs.affirm.com/developers/reference/disputes-api-v3.md)