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",
"commission_created": true,
"activity_outcome": "commission_created",
"created_at": "2026-06-22T12:00:00.000Z",
"updated_at": "2026-06-22T12:00:00.000Z"
}
}
Conversions
Create Conversion
Create a server-side conversion and let Affonso calculate the commission automatically
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",
"commission_created": true,
"activity_outcome": "commission_created",
"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
string
Affonso referral ID to credit directly. Optional if you provide
customer_id or external_user_id.string
The customer ID from your payment provider or billing system, such as a
Stripe customer ID. Optional if you provide
referral_id or
external_user_id.string
The user ID from your own product, app, or internal system. Optional if you
provide
referral_id or customer_id.string
Compatibility alias for
referral_id.number
required
Total sale amount for the purchase. Must be a positive number.
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 keeps the original values on the conversion.string[]
Optional product identifiers to help match product-specific incentives.
string[]
Optional price identifiers to help match price-based incentives.
string
Subscription interval for the conversion. Valid values:
monthly,
yearly.boolean
Whether the conversion comes from a subscription purchase.
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.
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.string
default:"complete"
Purchase status. Valid values:
open, complete, trialing, failed,
refunded, partial_refunded.string
Optional ISO 8601 timestamp for the conversion.
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, orexternal_user_idis required. affonso_idis also accepted instead ofreferral_idfor compatibility.- Older field-name variants continue to work for compatibility, but new integrations should standardize on
referral_id. - If you send more than one identifier, Affonso checks
external_user_idfirst, thenreferral_id, thencustomer_id. intervalshould only be sent for subscription conversions.- Reusing the same
external_event_idreturns the existing conversion instead of creating a duplicate.
Response
The response includes the created conversion object. On a duplicateexternal_event_id, the API returns the existing conversion with HTTP 200.
boolean
Always
true for successful responses.object
The conversion object.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the transaction/commission record.
string
Referral ID credited by the conversion.
string | null
Affiliate who received credit for the conversion.
string | null
Affiliate program ID for the conversion.
number
Sale amount stored on the transaction.
string
Stored sale currency. This can be your team currency after conversion.
number
Automatically calculated commission amount. Can be
0 if no affiliate
earning was created.string | null
Currency or incentive unit for the commission. For non-monetary incentives,
this can be
CREDITS, FREE_MONTHS, or POINTS. Returns null when the
transaction was recorded without creating an affiliate earning.string
Commission status. If no affiliate earning was created, this field falls back
to
pending.string
Purchase status.
integer | null
Hold period applied to the earning, if any.
string | null
Payment intent ID. This flow currently returns
null.string | null
Payout invoice ID if linked later.
string | null
Affiliate earning ID if a commission was created.
string | null
Earning type. Typically
direct_commission when an earning exists.string | null
The idempotency key that was used for this conversion.
string
Always
auto for this endpoint.string | null
Incentive ID used during commission calculation, when a match was found.
boolean
Whether the conversion created an affiliate earning.
string
commission_created when an affiliate earning was created, or sale_recorded when the sale was accepted without creating one.string
ISO 8601 timestamp for when the conversion was created.
string
ISO 8601 timestamp for the last update.
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",
"commission_created": true,
"activity_outcome": "commission_created",
"created_at": "2026-06-22T12:00:00.000Z",
"updated_at": "2026-06-22T12:00:00.000Z"
}
}
When a conversion is accepted but no affiliate earning is created, the
response still succeeds with
commission_amount: 0,
commission_currency: null, earning_id: null,
commission_created: false, and activity_outcome: "sale_recorded".Was this page helpful?