Create a refund - Kelviq Documentation

curl --request POST \ --url https://sandboxapi.kelviq.com/api/v1/refunds/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "orderId": "ORD-20260715123000-A1B2C", "amountUnits": 2500, "reason": "REQUESTED_BY_CUSTOMER", "internalNote": "Customer requested a partial refund." } '

{ "id": "7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11", "reason": "REQUESTED_BY_CUSTOMER", "amountUnits": 2500, "amount": 25, "internalNote": "Customer requested a partial refund.", "failureReason": null, "status": "SUCCEEDED", "order": {} }

Authorizations

Authorization

string

header

required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Body

application/json

Parameters for a full or partial refund. Omit both amount fields to refund the order's entire remaining refundable balance.

orderId

string

required

The ID of an order owned by the authenticated organization.

Example:

"ORD-20260715123000-A1B2C"

amountUnits

integer<int64>

Amount to refund in the currency's minor unit (for example, cents for USD). Takes precedence when amount is also provided.

Required range: x >= 1

Example:

2500

amount

number<decimal>

Amount to refund in the currency's major unit (for example, dollars for USD). Used only when amountUnits is omitted. For zero-decimal currencies, provide a whole number.

Required range: x > 0

Example:

25

reason

enum<string>

Reason for the refund. Defaults to REQUESTED_BY_CUSTOMER.

Available options:

DUPLICATE,

FRAUDULENT,

REQUESTED_BY_CUSTOMER,

OTHER

Example:

"REQUESTED_BY_CUSTOMER"

internalNote

string | null

Optional internal note associated with the refund.

Example:

"Customer requested a partial refund."

Response

Refund initiated. The returned status reflects the payment provider's current result.

A refund returned by list, create, and retrieve operations.

string<uuid>

Example:

"7c2f3a91-2d4e-4a8b-9b1c-6f0a2e5d9c11"

reason

enum<string> | null

Available options:

DUPLICATE,

DASHBOARD_INITIATED,

FRAUDULENT,

REQUESTED_BY_CUSTOMER,

OTHER

Example:

"REQUESTED_BY_CUSTOMER"

amountUnits

integer<int64>

Example:

2500

amount

number<decimal>

Example:

25

internalNote

string | null

Example:

"Customer requested a partial refund."

failureReason

string | null

Example:

null

status

enum<string>

Available options:

PENDING,

PROCESSING,

SUCCEEDED,

FAILED,

CANCELED

Example:

"SUCCEEDED"

order

object

The complete serialized order associated with the refund.