Disputes API v1 (1.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 the dispute loss.

Klarna merchants consuming Disputes API are authenticated via the OAuth 2.0 protocol. As part of your credentials you have the possibility to specify a webhook endpoint to receive notifications when your input is needed for a dispute.

Authentication

apiUser

Security Scheme Type	API Key
Header parameter name:	Authorization

List disputes

Get a list of disputes, segregated by a variety of filter parameters

Request

Security:

apiUser

query Parameters

merchant_id	Array of strings Merchant ID to filter by
order_id	Array of strings Order ID to filter by
merchant_reference1	Array of strings Merchant Reference 1 to filter by
merchant_reference2	Array of strings Merchant Reference 2 to filter by
dispute_id	Array of strings Dispute ID to filter by
investigation_status	Array of strings Investigation status of disputes to filter by Items Enum: "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"
opened_after	string <date-time> Start of dispute opened date interval to filter by
opened_before	string <date-time> End of dispute opened date interval to filter by
deadline_expires_after	string <date-time> Start of dispute deadline expiration interval to filter by
deadline_expires_before	string <date-time> End of dispute deadline expiration interval to filter by
sort_by	Array of strings Default: ["dispute_id"] 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: "dispute_id" "-dispute_id" "merchant_id" "-merchant_id" "deadline_expires_at" "-deadline_expires_at" "opened_at" "-opened_at"
offset	integer <int32> maximum number of results to return
size	integer <int32> How many elements to include in the result

Responses

200

A paginated list of authorized disputes

get/v1/disputes

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/v1/disputes?merchant_id=string&order_id=string&merchant_reference1=string&merchant_reference2=string&dispute_id=string&investigation_status=unresolved&reason=goods_not_received&opened_after=2019-08-24T14%3A15%3A22Z&opened_before=2019-08-24T14%3A15%3A22Z&deadline_expires_after=2019-08-24T14%3A15%3A22Z&deadline_expires_before=2019-08-24T14%3A15%3A22Z&sort_by=dispute_id&offset=0&size=0' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

application/json

{"disputes": [{"capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
"closed_at": "2018-12-03T10:26:06.000Z",
"closing_reason": "resolved",
"closing_reason_detailed": "merchant_did_not_reply_to_dispute_request",
"deadline_expires_at": "2018-12-03T00:00:00.000Z",
"dispute_id": "256947",
"dispute_krn": "krn:klarna:eu:dispute:return:123456",
"disputed_order_lines": [{"disputed_quantity": 2,
"reference": "45aa52f387871e3a210645d4"
}
],
"investigation_status": "closed",
"merchant": {"merchant_id": "K000001",
"name": "Klarna"
},
"opened_at": "2018-12-03T10:26:06.000Z",
"order": {"created_at": "2018-12-03T10:26:06.000Z",
"merchant_data": "{'foo':'bar','baz':true }",
"merchant_reference1": "45aa52f387871e3a210645d4",
"merchant_reference2": "45aa52f387871e3a210645d4",
"order_amount": 1947,
"order_id": "8922c722-bd7a-449b-ad54-d9c2cc52dff9",
"purchase_currency": "SEK"
},
"reason": "goods_not_received",
"requests": [{"responses": [{"attachments": [null
],
"comment": "All the requested fields are addressed as requested",
"created_at": "2018-12-03T10:26:06.000Z",
"requested_fields": {"customer_has_been_contacted": null,
"delivered_with_proof": null,
"delivery_address": null,
"goods_returned": null,
"is_travel_order": null,
"last_digits_of_phone_for_delivery_notification": null,
"order_already_shipped": null,
"order_already_used": null,
"order_is_cancellable": null,
"order_is_refundable": null,
"order_type": null,
"proof_of_delivery": [ ],
"received_payment": null,
"return_info": null,
"service_already_used": null,
"service_delivered_by": null,
"shipment_country": null,
"shipping_carrier": null,
"shipping_date": null,
"tracking_id": null
},
"response_id": 2
}
],
"attachments": [{"attachment_id": 3,
"filename": "receipt.pdf"
}
],
"comment": "Consumer claimed delivered goods were faulty",
"created_at": "2018-12-03T10:26:06.000Z",
"optional_requested_fields": ["tracking_id",
"shipping_date"
],
"request_id": 1,
"requested_fields": ["tracking_id",
"shipping_date"
]
}
]
}
],
"pagination": {"count": 10,
"offset": 30,
"total": 100
}
}

Get dispute details

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

Request

Security:

apiUser

path Parameters

dispute_id

required

string

ID of dispute to fetch

Responses

200

Complete dispute with all requests and responses

404

Dispute not found

get/v1/disputes/{dispute_id}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/v1/disputes/{dispute_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

application/json

{"capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
"closed_at": "2018-12-03T10:26:06.000Z",
"closing_reason": "resolved",
"closing_reason_detailed": "merchant_did_not_reply_to_dispute_request",
"deadline_expires_at": "2018-12-03T00:00:00.000Z",
"dispute_id": "256947",
"dispute_krn": "krn:klarna:eu:dispute:return:123456",
"disputed_order_lines": [{"disputed_quantity": 2,
"reference": "45aa52f387871e3a210645d4"
}
],
"investigation_status": "closed",
"merchant": {"merchant_id": "K000001",
"name": "Klarna"
},
"opened_at": "2018-12-03T10:26:06.000Z",
"order": {"created_at": "2018-12-03T10:26:06.000Z",
"merchant_data": "{'foo':'bar','baz':true }",
"merchant_reference1": "45aa52f387871e3a210645d4",
"merchant_reference2": "45aa52f387871e3a210645d4",
"order_amount": 1947,
"order_id": "8922c722-bd7a-449b-ad54-d9c2cc52dff9",
"purchase_currency": "SEK"
},
"reason": "goods_not_received",
"requests": [{"responses": [{"attachments": [{"attachment_id": 3,
"filename": "receipt.pdf"
}
],
"comment": "All the requested fields are addressed as requested",
"created_at": "2018-12-03T10:26:06.000Z",
"requested_fields": {"customer_has_been_contacted": "yes",
"delivered_with_proof": "yes",
"delivery_address": "Sveavägen 46, 111 34 Stockholm",
"goods_returned": "yes_in_full",
"is_travel_order": "yes_will_cancel",
"last_digits_of_phone_for_delivery_notification": "123",
"order_already_shipped": "yes_in_full",
"order_already_used": "yes_in_full",
"order_is_cancellable": "yes_will_cancel",
"order_is_refundable": "yes_in_full",
"order_type": "services",
"proof_of_delivery": [{"attachment_id": null,
"filename": null
}
],
"received_payment": "yes_will_make_changes_to_order",
"return_info": "yes_will_make_changes_to_order",
"service_already_used": "yes",
"service_delivered_by": "email",
"shipment_country": "at",
"shipping_carrier": "postnord",
"shipping_date": "2020-07-27",
"tracking_id": "15505460368542E"
},
"response_id": 2
}
],
"attachments": [{"attachment_id": 3,
"filename": "receipt.pdf"
}
],
"comment": "Consumer claimed delivered goods were faulty",
"created_at": "2018-12-03T10:26:06.000Z",
"optional_requested_fields": ["tracking_id",
"shipping_date"
],
"request_id": 1,
"requested_fields": ["tracking_id",
"shipping_date"
]
}
]
}

Download request attachment

Download a file attachment linked to a specific request.

Request

Security:

apiUser

path Parameters

dispute_id required	string ID 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/v1/disputes/{dispute_id}/requests/{request_id}/attachments/{attachment_id}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/v1/disputes/{dispute_id}/requests/{request_id}/attachments/{attachment_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

No sample

Upload evidence attachment

Uploads an attachment to be linked to a dispute reponse

Request

Security:

apiUser

path Parameters

dispute_id

required

string

ID of dispute for which the request to add response to belongs

Request Body schema: multipart/form-data

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

Responses

201

Attachment uploaded successfully

400

Incomplete request, missing required parameters.

404

Dispute not found

post/v1/disputes/{dispute_id}/attachments

Request samples

curl
JavaScript
Node.js

curl -i -X POST \
  'https://api.klarna.com/v1/disputes/{dispute_id}/attachments' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: multipart/form-data' \
  -F filename=string \
  -F file=string

Response samples

application/json

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

Respond to a dispute

Respond to a Dispute request.

Request

Security:

apiUser

path Parameters

dispute_id required	string ID 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	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 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

post/v1/disputes/{dispute_id}/requests/{request_id}/responses

Request samples

Payload
curl
JavaScript
Node.js

application/json

{"attachments": [0
],
"comment": "All the requested fields are addressed as requested",
"requested_fields": {"customer_has_been_contacted": "yes",
"delivered_with_proof": "yes",
"delivery_address": "Sveavägen 46, 111 34 Stockholm",
"goods_returned": "yes_in_full",
"is_travel_order": "yes_will_cancel",
"last_digits_of_phone_for_delivery_notification": "123",
"order_already_shipped": "yes_in_full",
"order_already_used": "yes_in_full",
"order_is_cancellable": "yes_will_cancel",
"order_is_refundable": "yes_in_full",
"order_type": "services",
"proof_of_delivery": [0
],
"received_payment": "yes_will_make_changes_to_order",
"return_info": "yes_will_make_changes_to_order",
"service_already_used": "yes",
"service_delivered_by": "email",
"shipment_country": "at",
"shipping_carrier": "postnord",
"shipping_date": "2020-07-27",
"tracking_id": "15505460368542E"
}
}

Response samples

application/json

{"attachments": [{"attachment_id": 3,
"filename": "receipt.pdf"
}
],
"comment": "All the requested fields are addressed as requested",
"created_at": "2018-12-03T10:26:06.000Z",
"requested_fields": {"customer_has_been_contacted": "yes",
"delivered_with_proof": "yes",
"delivery_address": "Sveavägen 46, 111 34 Stockholm",
"goods_returned": "yes_in_full",
"is_travel_order": "yes_will_cancel",
"last_digits_of_phone_for_delivery_notification": "123",
"order_already_shipped": "yes_in_full",
"order_already_used": "yes_in_full",
"order_is_cancellable": "yes_will_cancel",
"order_is_refundable": "yes_in_full",
"order_type": "services",
"proof_of_delivery": [{"attachment_id": 3,
"filename": "receipt.pdf"
}
],
"received_payment": "yes_will_make_changes_to_order",
"return_info": "yes_will_make_changes_to_order",
"service_already_used": "yes",
"service_delivered_by": "email",
"shipment_country": "at",
"shipping_carrier": "postnord",
"shipping_date": "2020-07-27",
"tracking_id": "15505460368542E"
},
"response_id": 2
}

Download response attachment

Download a file attachment linked to a specific request response.

Request

Security:

apiUser

path Parameters

dispute_id required	string ID 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/v1/disputes/{dispute_id}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/v1/disputes/{dispute_id}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

No sample

Accept loss

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

Request

Security:

apiUser

path Parameters

dispute_id

required

string

ID of dispute to accept loss for

Responses

204

204 no content response

404

Dispute not found

post/v1/disputes/{dispute_id}/accept-loss

Request samples

curl
JavaScript
Node.js

curl -i -X POST \
  'https://api.klarna.com/v1/disputes/{dispute_id}/accept-loss' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

application/json

{"error_code": "MISSING_PARAMETER",
"error_message": "Invalid request received, missing request body"
}