Disputes states

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

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 along with a dispute fee. The dispute fee is non-refundable regardless of outcome, but 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)

For partial disputes, specify a partner_proposed_refund_amount in your defense along with evidence for the remaining amount

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

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. You have the opportunity to appeal this decision if you believe there was an error in Klarna's assessment.

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

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
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, and arbitration fees apply

Note: Arbitration fees apply if you lose the appeal. 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. Dispute fee remains non-refundable.
Dispute LOST: Neither the withheld dispute amount nor the dispute fee is refunded.

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. Dispute fees may still apply depending on circumstances.
`LOST`	Customer won the dispute	Disputed amount goes to customer. Dispute fees apply.

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.

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

Disputes lifecycle

Disputes fees

API & SDK references

Respond to representment request

Accept dispute loss

Upload partner evidence attachment

Get dispute

Appeal pre-arbitration decision