Skip to main content
POST
/
v2
/
refunds
Create Refund
curl --request POST \
  --url https://api.example.com/v2/refunds

​
Create Refund

Issue a full or partial refund for a completed order. Refunds are processed back to the original payment method (HSA/FSA card or regular card).

​
Authentication

Authorization: Bearer glm_test_YOUR_API_KEY

​
Request Body

{
  "order_id": "ord_abc123xyz",
  "amount": 4235,
  "reason": "customer_request",
  "notes": "Customer requested refund due to delayed shipping",
  "metadata": {
    "support_ticket": "TICKET-12345"
  }
}
All monetary amounts are integers in cents (e.g., 4995 = $49.95).

​
Parameters

ParameterTypeRequiredDescription
order_idstringYesID of the order to refund
amountintegerNoAmount to refund in cents (omit for full refund)
reasonenumYesRefund reason (see below)
notesstringNoAdditional notes (max 500 chars)
metadataobjectNoCustom key-value pairs
Finding Order ID: You can get the order_id from:
  • Webhook event data (order.created event)
  • Order API response (GET /v2/orders)
  • Your database (store it when receiving order.created webhook)
  • Dashboard order details

​
Refund Reasons

ReasonDescriptionExample Use Case
customer_requestCustomer requested refundCustomer changed mind, no longer needed
duplicateDuplicate paymentCustomer accidentally paid twice
fraudulentFraudulent orderDetected fraudulent transaction
product_unavailableProduct out of stockItem went out of stock after order
damaged_productProduct arrived damagedItem damaged during shipping
wrong_productWrong product shippedFulfillment error, sent wrong item
otherOther reasonAny other reason (explain in notes)

​
Request

POST /v2/refunds

​
Response

{
  "id": "ref_xyz789",
  "order_id": "ord_abc123xyz",
  "amount": 4235,
  "reason": "customer_request",
  "notes": "Customer requested refund due to delayed shipping",
  "status": "pending",
  "order": {
    "id": "ord_abc123xyz",
    "order_number": "ORD-2025-001234",
    "payment_status": "refunded"
  },
  "refund_breakdown": {
    "hsa_amount": 2995,
    "regular_amount": 1240
  },
  "metadata": {
    "support_ticket": "TICKET-12345"
  },
  "created_at": "2025-10-18T16:00:00Z",
  "processed_at": null,
  "estimated_arrival": "2025-10-25T16:00:00Z"
}

​
Response Fields

FieldTypeDescription
idstringUnique refund identifier
statusenumRefund status: pending, succeeded, failed, cancelled
refund_breakdownobjectSplit of refund by payment type
processed_attimestampWhen refund was processed (null if pending)
estimated_arrivaltimestampEstimated date funds return to customer

​
Examples

​
Full Refund

curl -X POST https://api.withgale.com/v2/refunds \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_abc123xyz",
    "reason": "customer_request",
    "notes": "Customer not satisfied with product"
  }'

​
Partial Refund

curl -X POST https://api.withgale.com/v2/refunds \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_abc123xyz",
    "amount": 1000,
    "reason": "damaged_product",
    "notes": "Partial refund for damaged item"
  }'

​
Refund Status

StatusDescription
pendingRefund initiated, processing
succeededRefund processed successfully
failedRefund failed
cancelledRefund cancelled

​
Split Card Refunds (Automatic)

Gale automatically handles split card refunds. You don’t need to specify how much goes to each card. When an order is paid with both HSA/FSA and regular card: 
{
  "order": {
    "amounts": {
      "hsa_amount": 4995,       // Paid with HSA/FSA card
      "regular_amount": 895,    // Paid with regular card
      "total": 5890
    }
  }
}

​
Full Refund

Just provide the order_id - Gale splits automatically: 
POST /v2/refunds
{
  "order_id": "ord_abc123",
  "reason": "customer_request"
}
Response shows the breakdown: 
{
  "id": "ref_xyz789",
  "amount": 5890,
  "refund_breakdown": {
    "hsa_amount": 4995,       // Refunded to HSA/FSA card
    "regular_amount": 895     // Refunded to regular card
  }
}

​
Partial Refund

Gale splits proportionally based on the original payment ratio: 
POST /v2/refunds
{
  "order_id": "ord_abc123",
  "amount": 2945,  // Partial refund
  "reason": "damaged_product"
}
Response: 
{
  "id": "ref_xyz789",
  "amount": 2945,
  "refund_breakdown": {
    "hsa_amount": 2498,       // ~84.7% (same ratio as original)
    "regular_amount": 447     // ~15.3%
  }
}
Key Points:
  • You only specify total amount
  • Gale calculates the split automatically
  • Each amount refunds to its original payment method
  • Response shows the breakdown for your records

​
Webhooks

Refunds trigger the following webhook events: 
{
  "type": "refund.created",
  "data": {
    "id": "ref_xyz789",
    "order_id": "ord_abc123xyz",
    "amount": 4235,
    "status": "pending"
  }
}

{
  "type": "refund.succeeded",
  "data": {
    "id": "ref_xyz789",
    "order_id": "ord_abc123xyz",
    "status": "succeeded",
    "processed_at": "2025-10-18T16:05:00Z"
  }
}
See Webhooks Reference for all refund events.

​
Errors

Status CodeError CodeDescription
400invalid_amountRefund amount exceeds order total
400already_refundedOrder already fully refunded
400invalid_stateOrder not in refundable state
401unauthorizedInvalid or missing API key
404not_foundOrder not found
422validation_errorField validation failed

​
Amount Too Large

{
  "error": {
    "code": "invalid_amount",
    "message": "Refund amount exceeds order total",
    "details": {
      "requested": 10000,
      "maximum": 4235
    }
  }
}

​
Already Refunded

{
  "error": {
    "code": "already_refunded",
    "message": "Order has already been fully refunded"
  }
}

​
Invalid State

{
  "error": {
    "code": "invalid_state",
    "message": "Cannot refund order with payment status 'pending'"
  }
}

​
Refund Timeline

Payment MethodTypical Arrival Time
HSA/FSA Card5-10 business days
Regular Card5-10 business days
Note: Actual timing depends on the customer’s card issuer.

​
Important Notes

Refunds cannot be undone. Once a refund is processed, it cannot be reversed. Double-check order ID and amount before submitting.
Partial refunds are supported. You can issue multiple partial refunds up to the order total. The remaining refundable amount is tracked automatically.