Skip to content
Order Management
/
/
Refund an order

Order Management API (1.0.0)

Download OpenAPI description
order-management.json
order-management.yaml
Languages
Servers
Default Server URL
https://api.kustom.co

Orders

Operations

Refunds

Operations

Refund an order

Request

Create a refund. Read more on Refunds

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

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.

Bodyapplication/jsonrequired
descriptionstring[ 0 .. 255 ] characters

Description of the refund shown to the customer. Max length is 255 characters.

order_linesArray of objects(OrderLineDto)[ 0 .. 1000 ] items

Order lines for the refund shown to the customer. Optional but increases the customer experience. Maximum 1000 order lines.

referencestring[ 0 .. 255 ] characters

Internal reference to the refund. This will be included in the settlement files. Max length is 255 characters.

refunded_amountinteger(int64)[ 0 .. 200000000 ]required

Refunded amount in minor units.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/refunds' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "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": 200000000,
        "total_discount_amount": 0,
        "total_tax_amount": 200000000,
        "type": "physical",
        "unit_price": 200000000
      }
    ],
    "reference": "string",
    "refunded_amount": 200000000
  }'

Responses

Refund created

Bodyapplication/json
string
Response
application/json
"string"

Get refund details

Request

Get refund.

Path
order_idstring(uuid)required

Order id

refund_idstringrequired

Refund id

curl -i -X GET \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/refunds/{refund_id}'

Responses

Refund found.

Bodyapplication/json
descriptionstring

Description of the refund shown to the customer. Max length is 255 characters.

Example: "The item was returned and the order refunded."
order_linesArray of objects(OrderLineDto)

Order lines for the refund shown to the customer. Optional but increases the customer experience. Maximum 1000 order lines.

referencestring

Internal reference to the refund that is also included in the settlement files. Max length is 255 characters.

refund_idstring

The refund id. Generated when the refund is created.

Example: "b2cb4f2e-2781-4359-80ad-555735ebb8d8"
refunded_amountinteger(int64)

Refunded amount in minor units.

refunded_atstring(date-time)

The time of the refund. ISO 8601.

Example: "2025-12-04T15:17:40Z"
Response
application/json
{
  "description": "The item was returned and the order refunded.",
  "order_lines": [
    { … }
  ],
  "reference": "string",
  "refund_id": "b2cb4f2e-2781-4359-80ad-555735ebb8d8",
  "refunded_amount": 0,
  "refunded_at": "2025-12-04T15:17:40Z"
}

Captures

Operations