Reward custom events with fixed cash
Pay a fixed cash bonus when a referred customer completes a custom action that is not a sale. A dedicated non-sale bonus endpoint is not available yet. This is the supported path today.
Example event ideas, not a required list: qualified visit, newsletter signup, first deposit, completed onboarding, KYC approved, first content publish.
Approval Type on the incentive decides when the earning can pay out. Immediate makes it ready for the next payout as soon as the event is accepted. Hold Period waits the configured days. Manual Review waits until someone approves it. Managed Payouts still needs that setting on and a payment method on the affiliate.
Before you begin
Make sure you have:
- an Affonso API key with
write:commissionspermission - access to Groups
- a referral to credit, identified by
referral_id,customer_id, orexternal_user_id - affiliate tracking already installed so that identifier matches an existing referral
Do not send POST /v1/commissions with sale_amount 0. That endpoint requires a positive sale_amount.
Steps
Add a fixed cash incentive
Open Groups, click the group, then Incentives Setup. Click Add Incentive.
On Apply to, choose Specific products.
Create a product or select an existing one. Set Price or Plan ID to a stable ID you control. That is the product ID you send later in product_ids. Add one product per bonus type you want to pay.
On Select or Create an Incentive, click Create New Incentive. Set Incentive Type to Fixed amount and enter the cash amount. Set Approval Type to Immediate, Hold Period, or Manual Review.
Click Create Incentive, then Add Incentive. The incentive is assigned to this group.
Do not use Percentage. A percent of a $0 sale is $0.
Send a conversion event for each bonus
For each bonus, send POST /v1/events with:
event_name: a name from your system, required by the Create Event APIevent_type:conversionsale_amount:0sale_amount_currency: for exampleUSDproduct_ids: the matching product, using the product ID you setreferral_idorcustomer_idorexternal_user_id- a unique
external_event_idfor idempotency. A new ID lets the same bonus type pay again.
AFFONSO_API_HOST=api.affonso.io
curl -X POST "https://${AFFONSO_API_HOST}/v1/events" \
-H "Authorization: Bearer sk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"event_name": "visit_completed",
"event_type": "conversion",
"sale_amount": 0,
"sale_amount_currency": "USD",
"product_ids": ["visit"],
"external_user_id": "usr_104982",
"external_event_id": "evt_visit_20260907_001"
}'See the Create Event API for every field.
Confirm the earning and payout
The earning shows on Earnings. With Immediate, it is ready for the next payout right away. With Managed Payouts, it is included when that setting is on and the affiliate has a payment method.
Do not use Signups (Pay Per Lead), Trials (Pay Per Trial), or a milestone event for this. Those types do not match Specific products. Lead and Trial pay only once per referral.
Common issues
POST /v1/commissions with sale_amount 0 is rejected
Cause: That endpoint requires a positive sale_amount.
Solution: Use POST /v1/events with event_type conversion and sale_amount 0, plus a matching Specific products fixed incentive.
The event is accepted but no cash earning is created
Cause: The group incentive is a percentage, or product_ids does not match the product ID you set, or Apply to is Lead, Trial, or a plan-wide sale option instead of Specific products.
Solution: Use Fixed amount, Apply to Specific products, and send the matching product_ids.
Lead or trial paid once, then nothing
Cause: Lead and Trial incentives are one-shot per referral. They also do not match Specific products. Milestone events do not match Specific products either.
Solution: Send event_type conversion against a Specific products fixed incentive. Use a new external_event_id for each repeat.
Repeating the same bonus did not pay again
Cause: Affonso reused the same external_event_id and returned the prior result.
Solution: Send a unique external_event_id for each occurrence.
