Skip to content
Last updated

Refund orders

Here you find details of the calls that enable you to refund 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:

MERCHANTKUSTOMProvide the refund amount (full or partial)alt[SUCCESSFUL][ERROR]POST /ordermanagement/v1/orders/{order_id}/refunds1201: Created includes refund_id, location2403: correlation_id, error_code, error_message3MERCHANTKUSTOM

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",
      "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.

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.

Previous page
Next page