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:

Dispute Lifecycle

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:

Dispute Event Description

Event Type

Additional Notes

Dispute opened

purchase_dispute_opened

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

Merchant submits evidence

purchase_dispute_updated

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

Possible dispute_status values:

action_required_merchant

Dispute closed

purchase_dispute_resolved

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

purchase_dispute_opened

Field Name	Data Type	Description
`event_type`	string	`purchase_dispute_opened`
event_id	string
event_timestamp
`created`	date-time	The date and time of the event.
`transaction_id`	string	ID of transaction that dispute is for
`order_id`	string	ID of provided by partner/merchant for transaction (see checkout and transaction APIs)
`dispute_id`	string	Unique identifier for the dispute that the webhook corresponds to.
`merchant_id`	string	Unique Affirm identifier for the merchant.
`dispute_status`	string	An enum indicating the status of a dispute. Possible values: `action_required_merchant` `no_merchant_action_needed`
`dispute_reason`	string	An enum indicating the reason for a dispute status. Possible values: `cancellation_or_return_not_processed` `incorrect_amount` `product_not_received` `product_unacceptable`
`transaction_amount`	integer	Amount of transaction that dispute is associated with in the smallest denomination of the currency, such as cents.
`dispute_amount`	integer	Dispute amount in the smallest denomination of the currency, such as cents.
`currency`	string	The local currency of the dispute. Must be a valid subset of the ISO 4217 currency code.
`response_due_by`	date-time	Deadline for evidence submission, will be null until merchant action is required
`customer_won_amount`	integer	Amount of dispute that customer has won, will be null until the dispute is closed

Example:

{
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

Field Name	Data Type	Description
`event_type`	string	`purchase_dispute_updated`
`created`	date-time	The date and time of the event.
`transaction_id`	string	ID of transaction that dispute is for
`order_id`	string	ID of provided by partner/merchant for transaction (see checkout and transaction APIs)
`dispute_id`	string	Unique identifier for the dispute that the webhook corresponds to.
`merchant_id`	string	Unique Affirm identifier for the merchant.
`dispute_status`	string	An enum indicating the status of a dispute. Possible values: `action_required_merchant`
`dispute_reason`	string	An enum indicating the reason for a dispute status. Possible values: `cancellation_or_return_not_processed` `incorrect_amount` `product_not_received` `product_unacceptable`
`transaction_amount`	integer	Amount of transaction that dispute is associated with in the smallest denomination of the currency, such as cents.
`dispute_amount`	integer	Dispute amount in the smallest denomination of the currency, such as cents.
`currency`	string	The local currency of the dispute. Must be a valid subset of the ISO 4217 currency code.
`response_due_by`	date-time	Deadline for evidence submission, will be null until merchant action is required
`customer_won_amount`	integer	Amount of dispute that customer has won, will be null until the dispute is closed

Example:

{
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

Field Name	Data Type	Description
`event_type`	string	`purchase_dispute_resolved`
`created`	date-time	The date and time of the event.
`transaction_id`	string	ID of transaction that dispute is for
`order_id`	string	ID of provided by partner/merchant for transaction (see checkout and transaction APIs)
`dispute_id`	string	Unique identifier for the dispute that the webhook corresponds to.
`merchant_id`	string	Unique Affirm identifier for the merchant.
`dispute_status`	string	An enum indicating the status of a dispute. Possible values: `closed_merchant_favor` `closed_customer_favor` `closed_customer_partial_favor`
`dispute_reason`	string	An enum indicating the reason for a dispute status. Possible values: `cancellation_or_return_not_processed` `incorrect_amount` `product_not_received` `product_unacceptable`
`transaction_amount`	integer	Amount of transaction that dispute is associated with in the smallest denomination of the currency, such as cents.
`dispute_amount`	integer	Dispute amount in the smallest denomination of the currency, such as cents.
`currency`	string	The local currency of the dispute. Must be a valid subset of the ISO 4217 currency code.
`response_due_by`	date-time	Deadline for evidence submission, will be null until merchant action is required
`customer_won_amount`	integer	Amount of dispute that customer has won, will be null until the dispute is closed

Example:

{
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"

}