Skip to main content
POST
/
v1
/
conversions
/
{id}
/
refund
curl -X POST "https://api.affonso.io/v1/conversions/com_abc123/refund" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.50,
    "currency": "USD",
    "reason": "customer_cancellation",
    "external_event_id": "refund_evt_123"
  }'

{
  "success": true,
  "data": {
    "id": "com_abc123",
    "referral_id": "ref_456def",
    "affiliate_id": "aff_789ghi",
    "program_id": "prog_123xyz",
    "sale_amount": 49.5,
    "sale_amount_currency": "USD",
    "commission_amount": 14.85,
    "commission_currency": "USD",
    "status": "ready_for_payment",
    "sales_status": "partial_refunded",
    "hold_period_days": null,
    "payment_intent_id": null,
    "invoice_id": null,
    "earning_id": "earn_123abc",
    "earning_type": "direct_commission",
    "external_event_id": "inv_2026_000145",
    "calculation_mode": "auto",
    "matched_incentive_id": null,
    "created_at": "2026-06-22T12:00:00.000Z",
    "updated_at": "2026-06-22T16:10:00.000Z"
  }
}
Use this endpoint after a conversion has already been recorded in Affonso and you need to reflect a refund or chargeback.

​
Path Parameters

​
id
string
required
The unique identifier of the conversion/transaction to refund.

​
Body Parameters

All body parameters are optional. If you omit amount, Affonso applies a full refund for the remaining sale balance on the conversion.
​
amount
number
Refund amount to apply. Must be greater than zero and cannot exceed the remaining sale amount on the conversion.
​
currency
string
Optional three-letter currency code for your refund record, such as USD or EUR.
​
reason
string
Optional free-form reason, such as customer_cancellation or chargeback.
​
external_event_id
string
Optional idempotency key for the refund event. Reuse the same value when retrying the same upstream refund.
​
refunded_at
string
Optional ISO 8601 timestamp describing when the refund happened upstream.

​
Refund Behavior

  • Omitting amount creates a full refund for the remaining balance.
  • Partial refunds set sales_status to partial_refunded.
  • Full refunds set sales_status to refunded.
  • If an affiliate earning exists, its commission amount is reduced proportionally.
  • A full refund marks the commission status as refunded.

​
Response

The response returns the updated conversion object.
​
success
boolean
Always true for successful responses.
​
data
object
Updated conversion object.

​
Example Request

curl -X POST "https://api.affonso.io/v1/conversions/com_abc123/refund" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.50,
    "currency": "USD",
    "reason": "customer_cancellation",
    "external_event_id": "refund_evt_123"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "com_abc123",
    "referral_id": "ref_456def",
    "affiliate_id": "aff_789ghi",
    "program_id": "prog_123xyz",
    "sale_amount": 49.5,
    "sale_amount_currency": "USD",
    "commission_amount": 14.85,
    "commission_currency": "USD",
    "status": "ready_for_payment",
    "sales_status": "partial_refunded",
    "hold_period_days": null,
    "payment_intent_id": null,
    "invoice_id": null,
    "earning_id": "earn_123abc",
    "earning_type": "direct_commission",
    "external_event_id": "inv_2026_000145",
    "calculation_mode": "auto",
    "matched_incentive_id": null,
    "created_at": "2026-06-22T12:00:00.000Z",
    "updated_at": "2026-06-22T16:10:00.000Z"
  }
}
Full refunds emit transaction.rejected. Partial refunds emit transaction.updated.