Skip to main content
POST
/
v1
/
commissions
curl -X POST "https://api.affonso.io/v1/commissions" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_id": "ref_456def",
    "sale_amount": 99.00,
    "commission_amount": 9.90,
    "sale_amount_currency": "USD",
    "commission_currency": "USD",
    "sales_status": "complete"
  }'

{
  "success": true,
  "data": {
    "id": "com_abc123",
    "referral_id": "ref_456def",
    "affiliate_id": "aff_789ghi",
    "program_id": "prog_123xyz",
      "sale_amount": 99.00,
      "sale_amount_currency": "USD",
      "commission_amount": 9.90,
    "commission_currency": "USD",
    "status": "pending",
    "sales_status": "complete",
    "hold_period_days": null,
    "payment_intent_id": null,
    "invoice_id": null,
    "created_at": "2024-01-20T15:30:00Z",
    "updated_at": "2024-01-20T15:30:00Z"
  }
}
This endpoint is for manual commission creation. If you want Affonso to resolve the referral, match the incentive, calculate the commission, and deduplicate retries automatically, use POST /conversions instead.

​
Body Parameters

​
referral_id
string
required
ID of the referral this commission belongs to.
​
sale_amount
number
required
Total sale/transaction amount (not the commission amount). Must be a positive number. Will be automatically converted to your team’s currency if different.
​
commission_amount
number
required
Commission amount earned. Must be a non-negative number (can be 0).
​
sale_amount_currency
string
default:"USD"
Currency code for the sale (3 letters, e.g., USD, EUR). Defaults to USD. If different from your team currency, automatic conversion will occur and original values will be preserved in separate fields.
​
commission_currency
string
default:"USD"
Currency code (3 letters). Defaults to USD.
​
is_subscription
boolean
default:"false"
Whether this commission is from a subscription.
​
status
string
default:"pending"
Commission status. Valid values: pending, pending_manual_approval, ready_for_payment, paid, declined. Defaults to pending.
​
sales_status
string
default:"complete"
Status of the customer’s purchase. Valid values: open, complete, trialing, failed, refunded, partial_refunded. Defaults to complete.
​
payment_intent_id
string
Payment provider’s intent ID. If provided, must be unique across all commissions. Used to prevent duplicate commissions for the same payment.
​
hold_period_days
integer
Number of days to hold commission before it’s ready for payment. Must be a non-negative integer. If not provided, uses the program’s default hold period.

​
Response

The response includes the created commission object.
​
success
boolean
Always true for successful responses
​
data
object
The created commission object.
curl -X POST "https://api.affonso.io/v1/commissions" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_id": "ref_456def",
    "sale_amount": 99.00,
    "commission_amount": 9.90,
    "sale_amount_currency": "USD",
    "commission_currency": "USD",
    "sales_status": "complete"
  }'

{
  "success": true,
  "data": {
    "id": "com_abc123",
    "referral_id": "ref_456def",
    "affiliate_id": "aff_789ghi",
    "program_id": "prog_123xyz",
      "sale_amount": 99.00,
      "sale_amount_currency": "USD",
      "commission_amount": 9.90,
    "commission_currency": "USD",
    "status": "pending",
    "sales_status": "complete",
    "hold_period_days": null,
    "payment_intent_id": null,
    "invoice_id": null,
    "created_at": "2024-01-20T15:30:00Z",
    "updated_at": "2024-01-20T15:30:00Z"
  }
}