Use the Order management API to refund the items on a captured order.

When your customers return the items they bought and you need to refund that order, use this API call to credit the amount back to your customers.

The following diagram depicts how this API call works:

To refund the amount of an order, send a POST  request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/refunds  endpoint.

Include the following in your request:

Header

• 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.

Body

• 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 (optional): list of details associated with this refund. We highly recommend you send order lines as they allow us to locate the refund to the right capture (consumer invoice). Order lines are also helpful for your customers to visualize the refunded amount in the Klarna app

{
  "refunded_amount": 100000000",
  "reference": "9dfcd4b6-9428-4835-ad93-3720ea808608",
  "description": "Description of the refund shown to the customer",
  "order_lines": [
    {
      "image_url": "https://yourstore.example/product/headphones.png",
      "merchant_data": "Some metadata",
      "name": "string",
      "product_identifiers": {

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

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

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:

Header

• 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.

Body

• 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,

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

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

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.

Use the Order management API to extend the authorization date and allow yourself more time to capture the order.

When you need more time to capture and fulfill an order before it expires, you can extend its authorization time using this API call.

Extend the order authorization by adding the number of expiration days associated with your account to the date at the moment of extension. For example, let's say you place the order on the 1st of January and your account is configured for 28 days of order expiry; if you make an extension on the 15th of January, the new expiry date will be the 13th of February (adding 28 more days).

If you try to extend an order multiple times on the same day, you'll get the same expiry date each time you try. You can extend an order up to 180 days after it’s created, making extensions at different times on different dates.

After an order has expired, you can't extend it with this API call anymore.

To extend the authorization date of an order, send a POST request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/extend-authorization-time endpoint.

Provide order_id as a path parameter. The order_id is the identifier you get in a successful response when placing a new order.

You don't need a request body for this POST method.

If the request is successful, you'll receive a 204 No content response.

{
  "error_code": "NOT_ALLOWED",
  "error_messages": [
    "Order is expired. Authorization time cannot be extended."
  ],
  "correlation_id": "ef30ffe5-5c42-485a-85b6-8aeb24689bc8"
}

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

Use the Order management API to release the authorization of an order.

When you have an order that isn't fully captured and you don't plan to perform more captures on it, you should cancel it by releasing the order's authorization.

With this action, your customers won't be debited for the remaining authorized order amount. If your customers paid by card, we'll refund the remaining amount to their account.

To release the authorization of an order, send a POST request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/release-remaining-authorization endpoint.

Provide the order_id as path parameters. The order_id is the identifier you get in a successful response when placing a new order.

You don't need a request body for this POST method.

If the request is successful, you'll receive a 204 No content response.

{
  "error_code": "NOT_ALLOWED",
  "error_messages": [
    "Order is fully captured. Remaining authorization cannot be released."
  ],
  "correlation_id": "fefd0ea8-6899-41f9-93a7-ccd125c1af86"
}

Use the Order management API to extend the order’s payment due date.

When you want to give your customers more time to pay for their purchase, you have to extend the order's payment due date.

To get an extension for the payment date, follow these steps:

1. Get the available options for extending the due date of a specific order.
2. Extend the due date using one of the available options from the previous call.

As we relate every capture with an individual invoice for the customer, you can extend the payment due date per capture.

Extending the payment date is only possible for orders associated with a pay-later method, such as Pay in 30 days or Pay in 4 installments.

To get the available options for extending an order's payment due date, send a GET request to the {apiUrl}/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date-options endpoint.

Provide order_id and capture_id as path parameters. The order_id is the identifier you get in a successful response when placing a new order, and the capture_id is the identifier you get when successfully capturing an order.

You don't need a request body for this POST method.

{
  "currency": "usd",
  "options": [
    {
      "amount": 0,
      "number_of_days": 0
    }
  ]
}

{
  "correlation_id": "string",
  "error_code": "string",
  "error_messages": [
    "string"
  ]
}

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

{
  "number_of_days": 0
}

Provide one of the extension options you got as number_of_days from Step 1.

If the request is successful, you'll receive a 204 No content response.

{
  "correlation_id": "string",
  "error_code": "string",
  "error_messages": [
    "string"
  ]
}

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