Refund and extend orders

Here you find details of the calls that enable you to refund and extend your orders. For each call, you can find a description, technical details, and sample requests and responses.

Refund an order

Use the Order management API to refund the items on a captured order. When your customers return items, use this API call to credit the amount back to them.

The following diagram depicts how this API call works:

If you want to learn how to correctly allocate refunds when delivering in multiple shipments, see the Refund allocation section.

Refund a captured order amount

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

Header:

• Klarna-Idempotency-Key: Guarantees idempotency (unique key, recommended UUID v4). Retries are safe for network errors, etc.

Body:

• refunded_amount (required): Total order amount to be refunded (must be less than or equal to the captured amount).
• reference (optional): Internal refund reference.
• description (optional): Description of the refund for the customer.
• order_lines (optional): Details associated with the refund.

{
  "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": {
        "brand": "Intel",
        "category_path": "Electronics Store > Computers & Tablets > Desktops",
        "color": "Denim blue",
        "global_trade_item_number": "735858293167",
        "manufacturer_part_number": "BOXNUC5CPYH",
        "size": "4"
      },
      "product_url": "https://yourstore.example/product/headphones",
      "quantity": 1,
      "quantity_unit": "pcs.",
      "reference": "75001",
      "subscription": {
        "interval": "MONTH",
        "interval_count": 1,
        "name": "string"
      },
      "tax_rate": 0,
      "total_amount": 100000000,
      "total_discount_amount": 0,
      "total_tax_amount": 100000000,
      "type": "physical",
      "unit_price": 100000000
    }
  ]
}

Success Response: 201 Created, including refund_id and location headers.

Error Response: Error code and message, along with correlation_id for troubleshooting.

Refund with return fees

This API call refunds with fees for customer returns. Applicable for orders in Austria 🇦🇹, Germany 🇩🇪, Denmark 🇩🇰, Finland 🇫🇮, France 🇫🇷, Netherlands 🇳🇱, Norway 🇳🇴, and Sweden 🇸🇪. The order must be a single, fully captured order.

Conditions:

• Fully captured order (single capture).
• Total order lines amount must equal the refunded amount.

Body (additional parameter):

• order_lines: Include a new order line with type: return_fee to represent the 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,
      "total_amount": 10000
    },
    {
      "name": "Return fee",
      "type": "return_fee",
      "quantity": 1,
      "unit_price": -500,
      "total_amount": -500
    }
  ]
}

Success Response: 201 Created, including refund_id and location headers.

Error Response: Error code and message, with correlation_id for troubleshooting.

Extend order authorization

Extends an order's authorization date to give you more time for capturing and fulfilling the order. Extends by adding the account's expiry duration. Maximum extension is 180 days after the order creation date.

• Send a POST request to /ordermanagement/v1/orders/{order_id}/extend-authorization-time.
• No request body required.

Success Response: 204 No Content.

Error Response: Error code and message, with correlation_id and order_id for troubleshooting.

Release order authorization

Releases the authorization of an order if you don't intend to capture the full amount.

• Send a POST request to {apiUrl}/ordermanagement/v1/orders/{order_id}/release-remaining-authorization.
• No request body required.

Success Response: 204 No Content.

Error Response: Error code and message, with correlation_id and order_id for troubleshooting.

Extend payment date

Extends an order's payment due date for pay-later methods.

Step 1: Get available extension options:

• Send a GET request to {apiUrl}/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date-options.
• Response includes number_of_days for extension options.

Step 2: Extend due date:

• Send a PATCH request to {apiUrl}/ordermanagement/v1/orders/{order_id}/captures/{capture_id}/extend-due-date-options.
• Request body includes the number_of_days for the chosen option.

Success Responses:

• Step 1: Response body with number_of_days.
• Step 2: 204 No Content.

Error Responses: Error code and message, with correlation_id and order_id for troubleshooting.