POST

Refund an order

https://api.kustom.co/ordermanagement/v1/orders/{order_id}/refunds

Create a refund. Read more on Refunds

Parameters2 fields

order_idstring · uuidrequiredin path
Order id
Klarna-Idempotency-Keystringoptionalin header
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. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

Request body24 fields

descriptionstringoptional
Description of the refund shown to the customer. Max length is 255 characters.
order_lines[]array<object>optional
Order lines for the refund shown to the customer. Optional but increases the customer experience. Maximum 1000 order lines.
20 fields in order_lines
- image_urlstringoptional
  URL to an image that can be embedded in communications between Klarna and the customer.
- merchant_datastringoptional
  Data about the order line.
- namestringrequired
  Descriptive item name.
- product_identifiersobjectoptional
  product_identifiers
  6 fields in product_identifiers
  - brandstringoptional
    The product’s brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value. Maximum 70 characters. Example: Intel
  - category_pathstringoptional
    The product’s category path as used in the merchant’s webshop. Include the full and most detailed category and separate the segments with ’ > ’. Maximum 750 characters. Example: Electronics Store > Computers & Tablets > Desktops
  - colorstringoptional
    Color to be shown to the end customer (max 64 characters). Example: Denim blue
  - global_trade_item_numberstringoptional
    The product’s Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible. Maximum 50 characters. Example: 735858293167
  - manufacturer_part_numberstringoptional
    The product’s Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible. Maximum 70 characters. Example: BOXNUC5CPYH
  - sizestringoptional
    Size to be shown to the end customer (max 64 characters). Example: 4
- product_urlstringoptional
  URL to the product that can be used in communications between Klarna and the customer.
- quantityinteger · int64required
  Item quantity.
- quantity_unitstringoptional
  Unit used to describe the quantity.
- referencestringoptional
  Article number, SKU, or similar identifier on the product variant level.
- tax_rateinteger · int32optional
  The tax rate in percent with two implicit decimals.
- total_amountinteger · int64required
  Total amount including tax and discounts (quantity * unit_price - total_discount_amount).
- total_discount_amountinteger · int64optional
  The discount amount in minor units. Includes tax. Example: 1200 = $12. Max value: 200000000
- total_tax_amountinteger · int64optional
  The total tax amount in minor units.
- typestringoptional
  Order line type.
  - physical
  - discount
  - shipping_fee
  - sales_tax
  - store_credit
  - gift_card
  - digital
  - surcharge
  - return_fee
  - package
- unit_priceinteger · int64required
  Unit price including tax without applying discounts in minor units.
referencestringoptional
Internal reference to the refund. This will be included in the settlement files. Max length is 255 characters.
refunded_amountinteger · int64required
Refunded amount in minor units.

201

Response0 fields

Refund created

No response body — this status returns headers only.

403

Response3 fields

Refund not allowed

correlation_idstringoptional
Correlation id. For searching logs.
error_codestringoptional
Error code
error_messages[]array<string>optional
Error messages

404

Response3 fields

Order not found.

correlation_idstringoptional
Correlation id. For searching logs.
error_codestringoptional
Error code
error_messages[]array<string>optional
Error messages

409

Response0 fields

Conflict

No response body — this status returns headers only.

Errors

Code	Status	What it means	Retry
`REFUND_NOT_ALLOWED`	403	The order has no captured amount to refund. Needs `CAPTURED`.	Never retry
`NO_SUCH_ORDER`	404	The order_id does not exist, or belongs to the other environment.	Never retry

POST https://api.kustom.co/ordermanagement/v1/orders/{order_id}/refunds

Request body· application/json

{
  "description": "<string>",
  "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": 0,
      "total_discount_amount": 0,
      "total_tax_amount": 0,
      "type": "physical",
      "unit_price": 0
    }
  ],
  "reference": "<string>",
  "refunded_amount": 0
}

30 lines

Response 201· Refund created

"<string>"

1 lines

Response 403· Refund not allowed

{
  "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  "error_code": "REFUND_NOT_ALLOWED",
  "error_messages": [
    "<string>"
  ]
}

7 lines

Response 404· Order not found.

{
  "correlation_id": "66782175-ae05-44fc-9eb3-eeceadbad271",
  "error_code": "NOT_FOUND",
  "error_messages": [
    "<string>"
  ]
}

7 lines

Response 409· Conflict

"<string>"

1 lines

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.