Klarna Docs - Refund with return fees

Refund with return fees

Use the Order management API to make a refund with fees when your customers want to return items.

When your customers ask for a refund and want to return the items they bought, you can charge a return fee using this API call.

Your customers are charged with this return fee at the moment of refund, meaning that we take the return fee from the refunded amount they receive.

Charging the return fee is only possible if the orders meet the required conditions:

  • The order is fully captured in one single capture and not in partial captures.
  • The sum of the order lines is exactly equal to the refunded amount.
  • The order corresponds to one of these markets: Austria 🇦🇹, Germany 🇩🇪, Denmark 🇩🇰, Finland 🇫🇮, France 🇫🇷, Netherlands 🇳🇱, Norway 🇳🇴, Sweden 🇸🇪.

To charge return fees, you have to call the same endpoint you use for refunding an order, but with type: return_fee as an additional parameter in order_lines .

Send a POST  request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/refunds  endpoint.

Include the following in your request:


  • Klarna-Idempotency-Key : This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts.


  • refunded_amount (required): the total order amount to be refunded. It must be less or equal to the captured_amount from the order capture
  • reference (optional): Internal reference to the refund. This will be included in the settlement files.
  • description (optional): text to add details of the refunds. Your customers can see this description
  • order_lines (required): list of details associated with this capture. You have to add an extra order line representing the return fee and set its type to return_fee
  "refunded_amount": 9500,
  "reference": "1786c73b-a2be-4d42-a9f7-ff1c4bca5ccc",
  "description": "Description of the refund shown to the customer",
  "order_lines": [
      "name": "T-Shirt",
      "type": "physical",
      "quantity": 1,
      "unit_price": 10000,

Sample request to refund with return fees.

You must add the parameter type: return_fee in the order lines to charge the return fee successfully. Adding this parameter lets your customer visualize the fee in the Klarna app.

If the request is successful, you'll receive a 201 Created response, including refund_id and location as HTTP response headers.

Error response

If your request contains errors, you'll receive an error response. Make sure the order is already captured and the order_id in the request is correct.

You can use the correlation_id, and the order_id values to troubleshoot the call in the Merchant portal logs section.

  "error_code": "REFUND_NOT_ALLOWED",
  "error_messages": [
    "Over refund is not allowed. Refund not possible."
  "correlation_id": "7863c755-eb1b-4b24-a884-06c2368389d7"

Sample of an error response to refund with return fees.

You can also remove the charged fees added in the request explained above. For this action, you have to send a new request to refund an order, including the amount previously charged as a return fee.

Ready to send this request? See the API reference of this call.