Disputes states

Complete reference of all dispute states, reason codes, outcome codes, and their meanings.

10 min read

Overview

A dispute progresses through several states from initiation to resolution. Each state represents a phase in the dispute lifecycle where specific actions are available to you. Understanding these states helps you respond appropriately and resolve disputes efficiently.

States at a glance

State	Description	Partner actions available	Key endpoints
`INITIATED`	Dispute opened. You must respond before deadline.	Review details, submit evidence, accept loss	respondToDisputeRequest acceptLoss uploadAttachment
`REPRESENTMENT`	Your evidence is under review by Klarna.	Monitor progress (no new actions)	getDisputeDetails
`PRE_ARBITRATION`	Preliminary decision made. You can appeal within 10 days.	Review preliminary decision, accept loss, or appeal	appealDispute acceptLoss
`ARBITRATION`	Final review in progress after appeal submission.	Monitor progress (no new actions)	getDisputeDetails
`CLOSED`	Final resolution determined (`WON` or `LOST`).	No actions available (final state)	getDisputeDetails

Quick tip

The most critical actions happen in the INITIATED state. Missing the deadline results in automatic loss.

Dispute lifecycle states

Initiated

What happens: When a dispute is initiated, Klarna notifies you and immediately withholds the disputed amount. The dispute fee is charged when the dispute is decided against you, and the disputed amount will be refunded if you win.

Webhook: payment.dispute.state-change.initiated

Your options: You must take action before the deadline expires:

Accept the loss - If you agree with the dispute, accept the full disputed amount as a loss
Defend the dispute - Submit evidence to challenge the dispute (fully or partially)

Recommended for integration

For partial disputes, specify a partner_proposed_refund_amount in your defense along with evidence for the remaining amount. It is the part of the disputed amount you are willing to accept as a loss; Klarna may take it into account when deciding and does not show or offer it to the customer. Don't include refunds you have already issued; attach evidence of those instead.

Response deadline:

Dispute reason	Response time
Purchase Unauthorized	7 days
• Return not possible • Refund not processed • Products or services not received • Products defective or not as described • Incorrect amount	21 days

Missed deadline consequence

Important: If you don't respond within the deadline, the dispute automatically moves to CLOSED with a LOST outcome.

When to accept a loss:

Consider accepting a loss rather than defending when:

The customer's evidence is compelling (clear proof of non-receipt, defects, or errors)
The cost of gathering evidence exceeds the disputed amount
Maintaining customer relationship is more valuable than the disputed amount
The disputed amount is small relative to defense costs

Accepting loss implications:

The disputed amount is refunded to the customer
Dispute fees are applied
Payouts are adjusted accordingly
Quick resolution can enhance customer satisfaction

Example: FashionFusion receives a dispute from a customer who received a damaged handbag. The customer provides clear photos of the damage, and the shipping cost for a replacement is minimal. After reviewing the evidence, FashionFusion accepts the loss and issues a prompt refund. This saves time and resources while maintaining customer satisfaction.

Representment

What happens: You've submitted your defense evidence within the deadline. Klarna's dispute team is now reviewing your case and the evidence provided.

Webhook: payment.dispute.state-change.representment

Your action: No action required. Wait for Klarna's review to complete within 30 days. You cannot submit additional evidence during this state.

Representment substates:

The REPRESENTMENT state includes several substates that indicate progress:

Substate	Meaning
`EVIDENCE_REQUESTED`	You can still submit evidence before deadline (during INITIATED state)
`EVIDENCE_RECEIVED`	Your evidence is under review by Klarna
`EVIDENCE_REQUEST_EXPIRED`	Deadline passed without response - dispute will close as LOST
`EVIDENCE_WAIVED`	You accepted the loss during INITIATED state
`REPRESENTMENT_AUTOMATICALLY_REJECTED`	Dispute amount fell below your configured threshold - automatically accepted as LOST

Pre-Arbitration

What happens: Klarna has issued a preliminary decision in favor of the customer. If Klarna offers you an appeal, you can appeal this decision if you believe there was an error in Klarna's assessment. Klarna decides which disputes can be appealed: an appeal is only offered if the evidence you submitted in response to Klarna's request, while the dispute was in the INITIATED state, included all the information requested.

Webhook: payment.dispute.state-change.pre-arbitration

Your options:

Appeal the decision - Submit a summary explaining errors in Klarna's assessment (only full appeals allowed, no partial appeals)
Accept the preliminary decision - Take no action and the dispute closes as LOST after 10 days

Appeal deadline

Important: You have 10 days to file an appeal. If no appeal is submitted, the dispute automatically closes with Klarna's preliminary decision.

How the appeal process works:

1.
Preliminary outcome provided
- 1.1.
  Klarna provides a preliminary outcome: LOST
- 1.2.
  The preliminary_outcome_detailed field contains the specific reason code
2.
Submit your appeal (if needed)
- 2.1.
  Via Klarna Partner Portal: Click "Appeal" button and complete the form with your summary
- 2.2.
  Via API: Use the Appeal dispute preliminary decision endpoint
- 2.3.
  Include a clear summary of the perceived error
- 2.4.
  Reference only evidence already submitted - no new evidence is accepted
- 2.5.
  Only one appeal is permitted per dispute
- 2.6.
  An appeal is only offered if the evidence you submitted while the dispute was in the INITIATED state, before it moved to REPRESENTMENT, included all the information Klarna requested
3.
Dispute moves to Arbitration
- 3.1.
  Upon receiving your appeal, the dispute transitions to ARBITRATION
- 3.2.
  Klarna re-investigates the case with a fresh review
4.
Final decision within 14 days
- 4.1.
  If appeal succeeds: Dispute closes as WON
- 4.2.
  If appeal fails: Original decision stands, dispute closes as LOST

Appeal fee

Note: If you file an appeal, a non-refundable appeal fee is charged when the dispute closes, only if the appeal fails. No appeal fee is charged if the appeal succeeds. Only submit appeals when you have strong grounds to challenge the preliminary decision.

Arbitration

What happens: You've appealed Klarna's preliminary decision. Klarna's dispute team is conducting a thorough review of your appeal and the evidence to make a final decision.

Webhook: payment.dispute.state-change.arbitration

Your action: No action required. Klarna will review and resolve the case within 14 days.

Closed

What happens: The dispute has reached a final resolution - either WON (in your favor) or LOST (in customer's favor).

Webhook: payment.dispute.state-change.closed

Possible paths to closure:

Dispute WON by Partner:

Path 1: Successful defense during Representment
- INITIATED → REPRESENTMENT → CLOSED (WON)
- Reason: Klarna accepts your evidence and rules in your favor
Path 2: Successful appeal after Pre-Arbitration
- INITIATED → REPRESENTMENT → PRE_ARBITRATION (LOST) → ARBITRATION → CLOSED (WON)
- Reason: Your appeal convinces Klarna to overturn the preliminary decision

Dispute LOST by Partner:

Path 1: Accepted loss or no response at initiation
- INITIATED → CLOSED (LOST)
- Reason: You accepted the dispute or didn't respond
Path 2: Missed response deadline
- INITIATED → CLOSED (LOST)
- Reason: No response provided within allowed timeframe
Path 3: Unsuccessful defense without appeal
- INITIATED → REPRESENTMENT → PRE_ARBITRATION (LOST) → CLOSED (LOST)
- Reason: Klarna ruled against you and you didn't appeal
Path 4: Unsuccessful appeal
- INITIATED → REPRESENTMENT → PRE_ARBITRATION → ARBITRATION → CLOSED (LOST)
- Reason: Klarna upheld its decision after final review

Settlement details:

Dispute WON: Klarna refunds the withheld dispute amount. No dispute fee is charged.
Dispute LOST: The withheld dispute amount is not refunded and the dispute fee is charged.

Your action: No further action required.

Dispute outcomes

When a dispute reaches the CLOSED state, it has one of two outcomes:

Outcome	Description	Financial impact
`WON`	You won the dispute	Disputed amount released back to you. No dispute fee is charged.
`LOST`	Customer won the dispute	Disputed amount goes to customer. The dispute fee is charged.

For card chargebacks, the dispute fee is charged regardless of the outcome, except for unauthorized purchase disputes where your representment meets the requirements.

For complete information about dispute fees, see Dispute fees.

Detailed outcome codes

The dispute_outcome_detailed field provides a specific reason code explaining why the dispute was resolved the way it was. These codes help you understand the decision and identify areas for improvement.

Recommended for integration

Important: The dispute_outcome_detailed field is an open enum - new values may be added in the future. Your integration should handle unknown values gracefully.

Common outcome categories

Outcome codes fall into several categories:

Outcomes favorable to you (WON):

Valid shipping proof provided
Valid return/refund documentation
Dispute resolved directly with customer
Customer cancelled the dispute
Dispute filed under wrong reason code

Outcomes requiring action (may trigger fees):

Refund issued to customer during dispute
Refund issued after escalation
Payment issues resolved

Outcomes unfavorable to you (LOST):

No response or missed deadline
Insufficient or missing shipping proof
Didn't follow Klarna's shipping or return policies
Service or product issues without adequate evidence
Failed to perform promised actions (refund, cancellation, updates)

For a complete reference of all outcome codes, their descriptions, and when they apply, see the Payment Dispute API Reference API

Handling outcome codes in your integration

Use outcome codes to:

Track which issues cause the most disputes
Identify patterns in lost disputes
Generate reports on dispute resolution effectiveness
Improve processes based on common failure reasons

Handle unknown codes gracefully:

Your integration should accept any string value for dispute_outcome_detailed since new codes may be added:

JAVASCRIPT

1 2 3 4 5 6 7 8 9 10

function getOutcomeDescription(outcomeCode) {
  const knownOutcomes = {
    'PARTNER_PROVIDED_VALID_SHIPPING_DETAILS': 'Valid shipping proof submitted',
    'PARTNER_DID_NOT_REPLY_TO_DISPUTE_REQUEST': 'No response before deadline',
    // ... other known codes
  };

  return knownOutcomes[outcomeCode] || `Unknown outcome: ${outcomeCode}`;
}

Outcome explanation

When a dispute closes as LOST, the closed state_context and the payment.dispute.state-change.closed webhook can include dispute_outcome_explanation, a short explanation in English of why the dispute was decided against you. dispute_outcome_detailed gives the category of the decision. The explanation describes what applied to this particular dispute.

JSON

1 2 3 4 5 6

"state_context": {
  "dispute_outcome": "LOST",
  "dispute_outcome_detailed": "INSUFFICIENT_PROOF_OF_DELIVERY",
  "closed_at": "2025-11-25T11:20:00Z",
  "dispute_outcome_explanation": "The tracking information provided did not confirm delivery to the customer's address, so the dispute was resolved in the customer's favor."
}

The field is optional and up to 500 characters long.
It's only present when dispute_outcome is LOST. Won disputes never include it.
Not every lost dispute has an explanation, so treat a missing field as normal.

Display guidance

Show the explanation as-is next to the outcome, to whoever handles your disputes. Don't parse it or match on its wording, since it's free text and can change. Use dispute_outcome_detailed for reporting and automation.

Disputes lifecycle

Disputes fees

API & SDK references

Respond to representment request

Accept dispute loss

Upload partner evidence attachment

Get dispute

Appeal pre-arbitration decision

Jump to section...