Disputes API v2 (2.0.0)

Download OpenAPI specification:Download

The Disputes API offers Klarna partners and merchants an easy way to handle customer disputes.

Use the available endpoints to:

Get a list of disputes, filtered by various parameters.
Get a full, detailed version of a dispute, including all the associated requests and responses.
Respond to a dispute request.
Download/upload a file attachment linked to a specific request response.
Accept loss for a dispute.

Please note that there are two ways to authenticate:

Klarna partners should authenticate via OAuth2 with client credentials. This allows access to multiple merchants in a single API call.
Klarna merchants (not partnered) should authenticate with basic auth credentials. Additionally, please set the x-klarna-basic-mid header to the merchant ID.

Before you get started, please make sure you understand the disputes process.

FAQ

Why is the API returning 403?
- Please make sure your credentials and the endpoint you're calling are correct. Klarna APIs may also respond with a 403 for invalid paths.
Why doesn't the /enroll endpoint work?
- Self-enrollment is currently only supported for basic merchants. If the merchant is a partner or related to a partner, it will fail.
GET v2/disputes returns an empty list, why?
- Are you sure there are disputes to list?
- Since you got through to the endpoint your client credentials are valid. Some partners or merchants may have been onboarded to the api incorrectly.
Why am I getting an invalid date format when responding to a dispute?
- Only the following ISO 8601 format is currently supported: YYYY-MM-DDTHH:mm:ss.sssZ. Please note it includes ms.

Authentication

BasicAuth

Merchants (not partnered) should authenticate with basic auth credentials. Additionally, please set the x-klarna-basic-mid header to the merchant id.

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

OAuth2

Partners should authenticate via OAuth2 with client credentials. This allows access to multiple merchants in a single api call.

Security Scheme Type	OAuth2
clientCredentials OAuth Flow	Token URL: /oauth2/v1/token Scopes: `read` - read:dispute `write` - write:dispute

Enroll to Disputes API

Self onboarding for merchants. Partner related merchants cannot self onboard through this API

Request

Security:

OAuth2 or BasicAuth

Responses

204

Merchant successfully onboarded or was onboarded already

409

Merchant has a partner relation. Enroll is not permitted

post/disputes/v2/enroll

Request samples

curl
JavaScript
Node.js

curl -i -X POST \
  https://api.klarna.com/disputes/v2/enroll \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

List disputes

Get a list of disputes, filtered by a variety of parameters parameters

Request

Security:

OAuth2 or BasicAuth

query Parameters

merchant_id	Array of strings Merchant ID to filter by
order_id	Array of strings Order ID to filter by
investigation_status	Array of strings Investigation status of disputes to filter by Items Enum: "opened" "started" "unresolved" "replied" "closed" "deadline_expired" "loss_accepted"
reason	Array of strings Dispute reason to filter by Items Enum: "goods_not_received" "return" "incorrect_invoice" "already_paid" "faulty_goods" "pandemic_impact" "unauthorized_purchase" "high_risk_order"
sort_by	Array of strings Default: ["opened_at"] Specifies in which order to sort the results. Then results are ordered in ascending order if not prefixed by a - which orders by descending order. Items Enum: "deadline_expires_at" "-deadline_expires_at" "opened_at" "-opened_at"
limit	integer <int32> [ 1 .. 250 ] How many elements to include in the result
next_page	Array of strings The IDs of the next result
merchant_references1	Array of strings Merchant References 1 to filter by
merchant_references2	Array of strings Merchant References 2 to filter by

Responses

200

A paginated list of authorized disputes

400

Invalid request, check query parameters.

403

User not authorized to access the resource.

404

Dispute not found

get/disputes/v2/disputes

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes?merchant_id=string&order_id=string&investigation_status=opened&reason=goods_not_received&sort_by=opened_at&limit=1&next_page=string&merchant_references1=string&merchant_references2=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples

application/json

{"disputes": [{"capture_id": "6f343add-9c3d-4253-b449-fefe89d7b803",
"deadline_expires_at": "2020-05-22T00:00:00.000Z",
"dispute_krn": "krn:klarna:eu1:dispute:return:266091",
"disputed_order_lines": [{"disputed_quantity": 5,
"reference": "45aa52f387871e3a210645d4"
}
],
"investigation_status": "unresolved",
"merchant": {"merchant_id": "K000000",
"name": "Merchant"
},
"opened_at": "2020-05-08T08:31:00.000Z",
"order": {"created_at": "2020-04-14T17:42:12.512Z",
"merchant_reference1": "f420e0e1-971b-417a-8ece-2626387eff36",
"merchant_reference2": "3d29e0e5-3332-480b-a335-2dfe16e7ed5d",
"order_amount": 39900,
"order_id": "922c722-bd7a-449b-ad54-d9c2cc52dff9",
"purchase_currency": "SEK"
},
"reason": "goods_not_received",
"region": "EU",
"requests": [{"responses": [{"attachments": [{"attachment_id": 1,
"filename": "shipment_receipt.pdf"
}
],
"comment": "Comment from merchant",
"created_at": "2020-05-09T09:32:18.315Z",
"requested_fields": {"tracking_id": "ZCFSY3ABH3G2"
},
"response_id": 1
}
],
"attachments": [ ],
"comment": "Please provide tracking ID of shipment",
"created_at": "2020-05-08T08:32:14.642Z",
"optional_requested_fields": ["shipping_date"
],
"request_id": 1,
"requested_fields": ["tracking_id"
]
},
{"attachments": [ ],
"comment": "Follow up comment from agent requesting another field",
"created_at": "2020-05-09T10:15:02.951Z",
"optional_requested_fields": [ ],
"request_id": 2,
"requested_fields": ["shipping_carrier"
]
}
]
}
],
"pagination": {"count": 1,
"limit": 25,
"next_page": ["1636451517476",
"283316"
],
"total": 372
}
}

Get dispute details

Fetch a fully detailed version of a Dispute, including all the associated requests and responses.

Request

Security:

OAuth2 or BasicAuth

path Parameters

dispute_krn

required

string

Klarna Resource Name of dispute to fetch

Responses

200

Complete dispute with all requests and responses

404

Dispute not found

get/disputes/v2/disputes/{dispute_krn}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples

application/json

{"capture_id": "6f343add-9c3d-4253-b449-fefe89d7b803",
"deadline_expires_at": "2020-05-22T00:00:00.000Z",
"dispute_krn": "krn:klarna:eu1:dispute:return:266091",
"investigation_status": "unresolved",
"merchant": {"merchant_id": "K000000",
"name": "Merchant"
},
"opened_at": "2020-05-08T08:31:00.000Z",
"order": {"created_at": "2020-04-14T17:42:12.512Z",
"merchant_reference1": "f420e0e1-971b-417a-8ece-2626387eff36",
"merchant_reference2": "3d29e0e5-3332-480b-a335-2dfe16e7ed5d",
"order_amount": 300,
"order_id": "922c722-bd7a-449b-ad54-d9c2cc52dff9",
"purchase_currency": "EUR"
},
"reason": "goods_not_received",
"region": "EU",
"requests": [{"attachments": [ ],
"comment": "Please provide tracking ID of shipment",
"created_at": "2020-05-08T08:32:14.642Z",
"optional_requested_fields": [ ],
"request_id": 1,
"requested_fields": ["tracking_id"
]
}
]
}

Download request attachment

Download a file attachment linked to a specific request.

Request

Security:

OAuth2 or BasicAuth

path Parameters

dispute_krn required	string Klarna Resource Name of dispute for which the attachment to fetch belongs to
request_id required	integer ID of request for which the attachment to fetch belongs to
attachment_id required	integer ID of the attachment to fetch

Responses

200

File download of attachment

404

Attachment not found

get/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/attachments/{attachment_id}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/attachments/{attachment_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples

application/json

{"error_code": "DISPUTE_NOT_FOUND",
"error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}

Upload evidence attachment

Uploads an attachment to be linked to a dispute reponse. Accepts JPG, JPEG, PNG, PDF and DOCX with a maximum size of 7.3MB.

Request

Security:

OAuth2 or BasicAuth

path Parameters

dispute_krn

required

string

Klarna Resource Name of dispute for which the request to add response to belongs

Request Body schema: multipart/form-data

file required	string <binary>
filename	string Name of a file to upload

Responses

201

Attachment uploaded successfully

400

Incomplete request, missing required parameters.

404

Dispute not found

post/disputes/v2/disputes/{dispute_krn}/attachments

Request samples

curl
JavaScript
Node.js

curl -i -X POST \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/attachments' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F file=string \
  -F filename=receipt.pdf

Response samples

application/json

{"attachment_id": 3,
"filename": "receipt.pdf"
}

Respond to a dispute

Respond to a dispute.

Request

Security:

OAuth2 or BasicAuth

path Parameters

dispute_krn required	string Klarna Resource Name of dispute for which the request to add response to belongs
request_id required	integer ID of request to add response to

Request Body schema: application/json

Response to add to request

attachments required	Array of numbers Attachment IDs of already uploaded attachments to link to the response
comment	string <= 5000 characters Merchant comment regarding the associated response
required	object (RequestedFields) Data associated with the current dispute required by customer service that merchant should respond with

Responses

201

Created response

400

Incomplete request, missing required parameters.

404

Dispute request not found

409

Dispute state incompatible

post/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses

Request samples

Payload
curl
JavaScript
Node.js

application/json

{"attachments": [1
],
"comment": "Comment from Merchant",
"requested_fields": {"shipping_date": "2020-04-23T12:00:00.000Z",
"tracking_id": "JCYPE32JAAR4"
}
}

Response samples

application/json

{"attachments": [{"attachment_id": 1,
"filename": "shipment_receipt.pdf"
}
],
"comment": "Comment from Merchant",
"created_at": "2020-05-08T12:32:55.697Z",
"requested_fields": {"shipping_date": "2020-04-23T12:00:00.000Z",
"tracking_id": "JCYPE32JAAR4"
},
"response_id": 2
}

Download response attachments

Download a file attachment linked to a specific request response.

Request

Security:

OAuth2 or BasicAuth

path Parameters

dispute_krn required	string Klarna Resource Name of dispute for which the attachment to fetch belongs to
request_id required	integer ID of request for which the attachment to fetch belongs to
response_id required	integer ID of response for which the attachment to fetch belongs to
attachment_id required	integer ID of the attachment to fetch

Responses

200

File download of attachment

404

Attachment not found

get/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples

application/json

{"error_code": "DISPUTE_NOT_FOUND",
"error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}

Accept loss

Accept the loss of a dispute, which will be closed with the chargeback activation

Request

Security:

OAuth2 or BasicAuth

path Parameters

dispute_krn

required

string

Klarna Resource Name of dispute to accept loss for

Responses

204

204 no content response

404

Dispute not found

409

Dispute state incompatible

post/disputes/v2/disputes/{dispute_krn}/accept-loss

Request samples

curl
JavaScript
Node.js

curl -i -X POST \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/accept-loss' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Response samples

application/json

{"error_code": "DISPUTE_NOT_FOUND",
"error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}