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",
"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"
}
}
Conversions
Refund Conversion
Apply a full or partial refund to an existing server-side conversion
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",
"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
string
required
The unique identifier of the conversion/transaction to refund.
Body Parameters
All body parameters are optional. If you omitamount, Affonso applies a full
refund for the remaining sale balance on the conversion.
number
Refund amount to apply. Must be greater than zero and cannot exceed the
remaining sale amount on the conversion.
string
Optional three-letter currency code for your refund record, such as
USD or
EUR.string
Optional free-form reason, such as
customer_cancellation or chargeback.string
Optional idempotency key for the refund event. Reuse the same value when
retrying the same upstream refund.
string
Optional ISO 8601 timestamp describing when the refund happened upstream.
Refund Behavior
- Omitting
amountcreates a full refund for the remaining balance. - Partial refunds set
sales_statustopartial_refunded. - Full refunds set
sales_statustorefunded. - 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.boolean
Always
true for successful responses.object
Updated conversion object.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the transaction.
string
Referral credited by the original conversion.
string | null
Affiliate who received credit for the conversion.
number
Remaining sale amount after the refund is applied.
string
Stored sale currency for the conversion.
number
Remaining commission amount after the refund adjustment.
string | null
Currency or incentive unit for the commission.
string
Commission status after the refund, such as
pending or refunded.string
Updated sale status:
partial_refunded or refunded.string | null
Original conversion idempotency key.
string
Always
auto for conversion-based flows.string | null
Returns
null for refund responses.string
ISO 8601 timestamp for when the conversion was originally created.
string
ISO 8601 timestamp for the latest refund-related update.
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",
"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.Was this page helpful?