Skip to main content
POST
/
v1
/
refunds
Create
curl --request POST \
  --url https://{defaultHost}/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "refund": {
    "amount": 500,
    "reason": "requested_by_customer",
    "charge_id": "aac4386a-ae86-4c87-95f3-93315049fd85"
  }
}
'
{
  "id": "91fef820-b098-46a0-9cb4-58d1484e5589",
  "object": "refund",
  "amount": 500,
  "currency": "usd",
  "external_refund_id": "re_Q0kyiXvwkOureia",
  "failure_reason": null,
  "live_mode": true,
  "metadata": {},
  "reason": "requested_by_customer",
  "status": "succeeded",
  "charge": "aac4386a-ae86-4c87-95f3-93315049fd85",
  "customer": "d300e236-b595-4580-bbe1-85ed2fcb638d",
  "return_request": null,
  "created_at": 1767909758,
  "updated_at": 1767909758
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
update_referral_commission
boolean

When set to true, the associated referral commission amount will be reduced proportionally based on the ratio of the refund amount to the checkout's total amount due.

Body

application/json
​
refund
object

Response

200 - application/json

Success

​
id
string | null

The UUID of the specific object.

​
object
string

A string describing the object type returned.

​
amount
integer

The amount in cents that was refunded, represented as a whole integer. For example 9900 is equivalent to $99.

​
reason
string

The reason for this refund, which can be one of duplicate, fraudulent, requested_by_customer, or expired_uncaptured_charge.

​
metadata
object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

​
charge

Expandable – The associated charge ID.

​
currency
string

Three-letter ISO currency code, in lowercase.

​
customer

Expandable – The associated customer ID.

​
external_refund_id
string

The external processor ID representing this refund.

​
failure_reason
string | null

The reason this refund failed, which can currently only be insufficient_funds.

​
live_mode
boolean

Set to true if this refund is in live mode, and set to false if it is in test mode.

​
refund_items

Expandable – Property not returned unless expanded.

​
return_request

Expandable – The associated return request ID.

​
status
string

The current status of this refund, which can be one of pending, succeeded, failed, or canceled.

​
created_at
integer | null

Time at which the object was created. Measured in seconds since the Unix epoch.

​
updated_at
integer | null

Time at which the object was last updated. Measured in seconds since the Unix epoch.