Create Conversion

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

POST

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, or external_user_id is required.
affonso_id is also accepted instead of referral_id for 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_id first, then referral_id, then customer_id.
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.

boolean

Always true for successful responses.

object

The conversion object.

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

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Validation Rules

Response

Example Request

Example Response

​Body Parameters

​Validation Rules

​Response

​Example Request

​Example Response

Body Parameters

Validation Rules

Response

Example Request

Example Response