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"
}
}
Commissions
Create Commission
Create a new commission transaction manually
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
string
required
ID of the referral this commission belongs to.
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.
number
required
Commission amount earned. Must be a non-negative number (can be 0).
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.string
default:"USD"
Currency code (3 letters). Defaults to
USD.boolean
default:"false"
Whether this commission is from a subscription.
string
default:"pending"
Commission status. Valid values:
pending, pending_manual_approval, ready_for_payment, paid, declined. Defaults to pending.string
default:"complete"
Status of the customer’s purchase. Valid values:
open, complete, trialing, failed, refunded, partial_refunded. Defaults to complete.string
Payment provider’s intent ID. If provided, must be unique across all commissions. Used to prevent duplicate commissions for the same payment.
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.boolean
Always
true for successful responsesobject
The created commission object.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the commission
string
The referral ID this commission is associated with
string
The affiliate ID who will receive this commission
string
The affiliate program ID
number
The total sale/transaction amount (automatically converted to team currency if different)
string
The currency code for the sale (3 letters, e.g., USD, EUR). Represents the team’s currency after conversion if applicable.
number
The commission amount to be paid
string | null
The currency code for the commission amount. Can be
null when the transaction exists without an affiliate earning.string
The commission status. Valid values:
pending (on hold period, auto-updates to ready_for_payment when period expires), pending_manual_approval (same as pending but requires manual approval), ready_for_payment (approved and ready for payout in next cycle, not yet paid), paid (confirmed and already paid out), declined (rejected, not paid and excluded from payouts).string
The sales/transaction status. Valid values:
open (sale is open/pending), complete (sale completed successfully), trialing (customer is in trial period), failed (sale failed), refunded (sale fully refunded), partial_refunded (sale partially refunded).integer | null
Number of days commission is on hold before becoming available for payment
string | null
Payment intent ID if provided
string | null
Invoice ID if linked to a payout invoice
string
ISO 8601 timestamp of when the commission was created
string
ISO 8601 timestamp of when the commission was last updated
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"
}
}
Was this page helpful?