Refund Conversion

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"
  }
}

POST

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

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.

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 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.

boolean

Always true for successful responses.

object

Updated conversion object.

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.

string | null

Affiliate program ID 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",
    "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.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Path Parameters

Body Parameters

Refund Behavior

Response

Example Request

Example Response

​Path Parameters

​Body Parameters

​Refund Behavior

​Response

​Example Request

​Example Response

Path Parameters

Body Parameters

Refund Behavior

Response

Example Request

Example Response