curl --location --request POST 'https://api.stateset.com/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"order_id": "order_123456",
"type": "partial",
"reason": "product_damaged",
"reason_details": "Item arrived with scratches on the surface",
"items": [
{
"line_item_id": "li_abc123",
"quantity": 1,
"restock": false
}
],
"amounts": {
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"total": 5449
},
"payment_method": {
"type": "original_payment",
"payment_id": "pay_xyz789"
},
"processing": {
"auto_approve": true,
"notify_customer": true,
"process_immediately": true
}
}'
const refund = await stateset.refunds.create({
order_id: "order_123456",
type: "partial",
reason: "product_damaged",
reason_details: "Item arrived with scratches on the surface",
items: [
{
line_item_id: "li_abc123",
quantity: 1,
restock: false
}
],
amounts: {
subtotal: 4999,
tax: 450,
shipping: 0,
total: 5449
},
payment_method: {
type: "original_payment",
payment_id: "pay_xyz789"
},
processing: {
auto_approve: true,
notify_customer: true,
process_immediately: true
}
});
refund = stateset.refunds.create(
order_id="order_123456",
type="partial",
reason="product_damaged",
reason_details="Item arrived with scratches on the surface",
items=[
{
"line_item_id": "li_abc123",
"quantity": 1,
"restock": False
}
],
amounts={
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"total": 5449
},
payment_method={
"type": "original_payment",
"payment_id": "pay_xyz789"
},
processing={
"auto_approve": True,
"notify_customer": True,
"process_immediately": True
}
)
{
"id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "refund",
"order_id": "order_123456",
"customer_id": "cust_abc123",
"type": "partial",
"status": "processing",
"reason": "product_damaged",
"reason_details": "Item arrived with scratches on the surface",
"items": [
{
"line_item_id": "li_abc123",
"product_id": "prod_123",
"product_name": "Wireless Headphones",
"quantity": 1,
"refund_amount": 4999,
"restock": false,
"restock_status": "not_restocking"
}
],
"amounts": {
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"adjustment": 0,
"total": 5449,
"currency": "USD"
},
"payment_method": {
"type": "original_payment",
"payment_id": "pay_xyz789",
"last4": "4242",
"brand": "visa"
},
"payment_status": "pending",
"transaction_id": null,
"processing": {
"auto_approved": true,
"approved_at": "2024-01-20T13:30:00Z",
"approved_by": "system"
},
"shipping": {
"return_required": false,
"return_label_id": null
},
"timeline": [
{
"status": "created",
"timestamp": "2024-01-20T13:30:00Z",
"actor": "customer"
},
{
"status": "approved",
"timestamp": "2024-01-20T13:30:01Z",
"actor": "system"
},
{
"status": "processing",
"timestamp": "2024-01-20T13:30:02Z",
"actor": "system"
}
],
"created_at": "2024-01-20T13:30:00Z",
"updated_at": "2024-01-20T13:30:02Z",
"estimated_completion": "2024-01-23T13:30:00Z",
"notes": null,
"metadata": {}
}
Create a refund for an order or specific items
POST
/
v1
/
refunds
curl --location --request POST 'https://api.stateset.com/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"order_id": "order_123456",
"type": "partial",
"reason": "product_damaged",
"reason_details": "Item arrived with scratches on the surface",
"items": [
{
"line_item_id": "li_abc123",
"quantity": 1,
"restock": false
}
],
"amounts": {
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"total": 5449
},
"payment_method": {
"type": "original_payment",
"payment_id": "pay_xyz789"
},
"processing": {
"auto_approve": true,
"notify_customer": true,
"process_immediately": true
}
}'
const refund = await stateset.refunds.create({
order_id: "order_123456",
type: "partial",
reason: "product_damaged",
reason_details: "Item arrived with scratches on the surface",
items: [
{
line_item_id: "li_abc123",
quantity: 1,
restock: false
}
],
amounts: {
subtotal: 4999,
tax: 450,
shipping: 0,
total: 5449
},
payment_method: {
type: "original_payment",
payment_id: "pay_xyz789"
},
processing: {
auto_approve: true,
notify_customer: true,
process_immediately: true
}
});
refund = stateset.refunds.create(
order_id="order_123456",
type="partial",
reason="product_damaged",
reason_details="Item arrived with scratches on the surface",
items=[
{
"line_item_id": "li_abc123",
"quantity": 1,
"restock": False
}
],
amounts={
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"total": 5449
},
payment_method={
"type": "original_payment",
"payment_id": "pay_xyz789"
},
processing={
"auto_approve": True,
"notify_customer": True,
"process_immediately": True
}
)
{
"id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "refund",
"order_id": "order_123456",
"customer_id": "cust_abc123",
"type": "partial",
"status": "processing",
"reason": "product_damaged",
"reason_details": "Item arrived with scratches on the surface",
"items": [
{
"line_item_id": "li_abc123",
"product_id": "prod_123",
"product_name": "Wireless Headphones",
"quantity": 1,
"refund_amount": 4999,
"restock": false,
"restock_status": "not_restocking"
}
],
"amounts": {
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"adjustment": 0,
"total": 5449,
"currency": "USD"
},
"payment_method": {
"type": "original_payment",
"payment_id": "pay_xyz789",
"last4": "4242",
"brand": "visa"
},
"payment_status": "pending",
"transaction_id": null,
"processing": {
"auto_approved": true,
"approved_at": "2024-01-20T13:30:00Z",
"approved_by": "system"
},
"shipping": {
"return_required": false,
"return_label_id": null
},
"timeline": [
{
"status": "created",
"timestamp": "2024-01-20T13:30:00Z",
"actor": "customer"
},
{
"status": "approved",
"timestamp": "2024-01-20T13:30:01Z",
"actor": "system"
},
{
"status": "processing",
"timestamp": "2024-01-20T13:30:02Z",
"actor": "system"
}
],
"created_at": "2024-01-20T13:30:00Z",
"updated_at": "2024-01-20T13:30:02Z",
"estimated_completion": "2024-01-23T13:30:00Z",
"notes": null,
"metadata": {}
}
This endpoint creates a refund request that can process partial or full refunds. It handles payment reversals, inventory adjustments, and customer notifications.
Authentication
This endpoint requires a valid API key withrefunds:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
string
required
Original order ID to refund
string
required
Refund type: “full”, “partial”, “item_return”, “shipping”, “tax_only”
string
required
Refund reason code
string
Detailed explanation of refund reason
array
object
required
object
object
object
string
Internal notes about the refund
object
Additional custom fields
Response
Returns the created refund object.curl --location --request POST 'https://api.stateset.com/v1/refunds' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
"order_id": "order_123456",
"type": "partial",
"reason": "product_damaged",
"reason_details": "Item arrived with scratches on the surface",
"items": [
{
"line_item_id": "li_abc123",
"quantity": 1,
"restock": false
}
],
"amounts": {
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"total": 5449
},
"payment_method": {
"type": "original_payment",
"payment_id": "pay_xyz789"
},
"processing": {
"auto_approve": true,
"notify_customer": true,
"process_immediately": true
}
}'
const refund = await stateset.refunds.create({
order_id: "order_123456",
type: "partial",
reason: "product_damaged",
reason_details: "Item arrived with scratches on the surface",
items: [
{
line_item_id: "li_abc123",
quantity: 1,
restock: false
}
],
amounts: {
subtotal: 4999,
tax: 450,
shipping: 0,
total: 5449
},
payment_method: {
type: "original_payment",
payment_id: "pay_xyz789"
},
processing: {
auto_approve: true,
notify_customer: true,
process_immediately: true
}
});
refund = stateset.refunds.create(
order_id="order_123456",
type="partial",
reason="product_damaged",
reason_details="Item arrived with scratches on the surface",
items=[
{
"line_item_id": "li_abc123",
"quantity": 1,
"restock": False
}
],
amounts={
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"total": 5449
},
payment_method={
"type": "original_payment",
"payment_id": "pay_xyz789"
},
processing={
"auto_approve": True,
"notify_customer": True,
"process_immediately": True
}
)
{
"id": "refund_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
"object": "refund",
"order_id": "order_123456",
"customer_id": "cust_abc123",
"type": "partial",
"status": "processing",
"reason": "product_damaged",
"reason_details": "Item arrived with scratches on the surface",
"items": [
{
"line_item_id": "li_abc123",
"product_id": "prod_123",
"product_name": "Wireless Headphones",
"quantity": 1,
"refund_amount": 4999,
"restock": false,
"restock_status": "not_restocking"
}
],
"amounts": {
"subtotal": 4999,
"tax": 450,
"shipping": 0,
"adjustment": 0,
"total": 5449,
"currency": "USD"
},
"payment_method": {
"type": "original_payment",
"payment_id": "pay_xyz789",
"last4": "4242",
"brand": "visa"
},
"payment_status": "pending",
"transaction_id": null,
"processing": {
"auto_approved": true,
"approved_at": "2024-01-20T13:30:00Z",
"approved_by": "system"
},
"shipping": {
"return_required": false,
"return_label_id": null
},
"timeline": [
{
"status": "created",
"timestamp": "2024-01-20T13:30:00Z",
"actor": "customer"
},
{
"status": "approved",
"timestamp": "2024-01-20T13:30:01Z",
"actor": "system"
},
{
"status": "processing",
"timestamp": "2024-01-20T13:30:02Z",
"actor": "system"
}
],
"created_at": "2024-01-20T13:30:00Z",
"updated_at": "2024-01-20T13:30:02Z",
"estimated_completion": "2024-01-23T13:30:00Z",
"notes": null,
"metadata": {}
}
⌘I