Create Commission

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

POST

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 responses

object

The created commission object.

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

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Response

​Body Parameters

​Response

Body Parameters

Response