Skip to main content
POST
/
v1
/
conversions
curl -X POST "https://api.affonso.io/v1/conversions" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "sale_amount": 99.00,
    "sale_amount_currency": "USD",
    "external_event_id": "inv_2026_000145",
    "sales_status": "complete",
    "is_subscription": true,
    "interval": "monthly",
    "price_ids": ["price_monthly_usd"]
  }'

{
  "success": true,
  "data": {
    "id": "com_abc123",
    "referral_id": "ref_456def",
    "affiliate_id": "aff_789ghi",
    "program_id": "prog_123xyz",
    "sale_amount": 99,
    "sale_amount_currency": "USD",
    "commission_amount": 29.7,
    "commission_currency": "USD",
    "status": "ready_for_payment",
    "sales_status": "complete",
    "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": "inc_monthly_001",
    "created_at": "2026-06-22T12:00:00.000Z",
    "updated_at": "2026-06-22T12:00:00.000Z"
  }
}
Use this endpoint for automatic server-side conversion tracking. Affonso will resolve the referral, match the incentive, calculate the commission, and create the earning when eligible.
external_event_id must be stable across retries. Reuse the exact same value if you retry the same billing event, order, invoice, or checkout completion.

​
Body Parameters

​
referral_id
string
Referral ID to credit directly. Optional if you provide customer_id, external_user_id, or click_id.
​
customer_id
string
Your internal customer identifier. Optional if you provide referral_id, external_user_id, or click_id.
​
external_user_id
string
Your external application user ID. Optional if you provide referral_id, customer_id, or click_id.
​
click_id
string
Click ID returned by POST /clicks. Optional if you provide referral_id, customer_id, or external_user_id.
​
sale_amount
number
required
Total sale amount for the purchase. Must be a positive number.
​
sale_amount_currency
string
default:"USD"
Three-letter currency code for the sale amount, such as USD or EUR. If the sale currency differs from your team currency, Affonso converts the sale amount and preserves the original values internally.
​
product_ids
string[]
Optional product identifiers to help match product-specific incentives.
​
price_ids
string[]
Optional price identifiers to help match price-based incentives.
​
interval
string
Subscription interval for the conversion. Valid values: monthly, yearly.
​
is_subscription
boolean
Whether the conversion comes from a subscription purchase.
​
external_event_id
string
required
Provider-side idempotency key for the conversion event. Use a stable unique identifier from your system, such as an order ID, invoice ID, checkout session ID, or payment event ID.
​
status
string
Optional commission status override. Valid values: pending, pending_manual_approval, ready_for_payment, processing_payout, paid, declined, refunded, dispute. If omitted, Affonso derives the status from the matched incentive’s approval settings.
​
sales_status
string
default:"complete"
Purchase status. Valid values: open, complete, trialing, failed, refunded, partial_refunded.
​
created_at
string
Optional ISO 8601 timestamp for the conversion.
​
metadata
object
Optional metadata object stored on the created affiliate earning when a commission is created.

​
Validation Rules

  • At least one of referral_id, customer_id, external_user_id, or click_id is required.
  • interval should only be sent for subscription conversions.
  • Reusing the same external_event_id returns the existing conversion instead of creating a duplicate.

​
Response

The response includes the created conversion object. On a duplicate external_event_id, the API returns the existing conversion with HTTP 200.
​
success
boolean
Always true for successful responses.
​
data
object
The conversion object.

​
Example Request

curl -X POST "https://api.affonso.io/v1/conversions" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "sale_amount": 99.00,
    "sale_amount_currency": "USD",
    "external_event_id": "inv_2026_000145",
    "sales_status": "complete",
    "is_subscription": true,
    "interval": "monthly",
    "price_ids": ["price_monthly_usd"]
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "com_abc123",
    "referral_id": "ref_456def",
    "affiliate_id": "aff_789ghi",
    "program_id": "prog_123xyz",
    "sale_amount": 99,
    "sale_amount_currency": "USD",
    "commission_amount": 29.7,
    "commission_currency": "USD",
    "status": "ready_for_payment",
    "sales_status": "complete",
    "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": "inc_monthly_001",
    "created_at": "2026-06-22T12:00:00.000Z",
    "updated_at": "2026-06-22T12:00:00.000Z"
  }
}