> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Commission

> Create a new commission transaction manually

<Info>
  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
  <a href="/api/endpoint/conversions/create">POST /conversions</a>
  instead.
</Info>

## Body Parameters

<ParamField body="referral_id" type="string" required>
  ID of the referral this commission belongs to.
</ParamField>

<ParamField body="sale_amount" type="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.
</ParamField>

<ParamField body="commission_amount" type="number" required>
  Commission amount earned. Must be a non-negative number (can be 0).
</ParamField>

<ParamField body="sale_amount_currency" type="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.
</ParamField>

<ParamField body="commission_currency" type="string" default="USD">
  Currency code (3 letters). Defaults to `USD`.
</ParamField>

<ParamField body="is_subscription" type="boolean" default="false">
  Whether this commission is from a subscription.
</ParamField>

<ParamField body="status" type="string" default="pending">
  Commission status. Valid values: `pending`, `pending_manual_approval`, `ready_for_payment`, `paid`, `declined`. Defaults to `pending`.
</ParamField>

<ParamField body="sales_status" type="string" default="complete">
  Status of the customer's purchase. Valid values: `open`, `complete`, `trialing`, `failed`, `refunded`, `partial_refunded`. Defaults to `complete`.
</ParamField>

<ParamField body="payment_intent_id" type="string">
  Payment provider's intent ID. If provided, must be unique across all commissions. Used to prevent duplicate commissions for the same payment.
</ParamField>

<ParamField body="hold_period_days" type="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.
</ParamField>

## Response

The response includes the created commission object.

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="object">
  The created commission object.

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the commission
    </ResponseField>

    <ResponseField name="referral_id" type="string">
      The referral ID this commission is associated with
    </ResponseField>

    <ResponseField name="affiliate_id" type="string">
      The affiliate ID who will receive this commission
    </ResponseField>

    <ResponseField name="program_id" type="string">
      The affiliate program ID
    </ResponseField>

    <ResponseField name="sale_amount" type="number">
      The total sale/transaction amount (automatically converted to team currency if different)
    </ResponseField>

    <ResponseField name="sale_amount_currency" type="string">
      The currency code for the sale (3 letters, e.g., USD, EUR). Represents the team's currency after conversion if applicable.
    </ResponseField>

    <ResponseField name="commission_amount" type="number">
      The commission amount to be paid
    </ResponseField>

    <ResponseField name="commission_currency" type="string | null">
      The currency code for the commission amount. Can be `null` when the transaction exists without an affiliate earning.
    </ResponseField>

    <ResponseField name="status" type="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).
    </ResponseField>

    <ResponseField name="sales_status" type="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).
    </ResponseField>

    <ResponseField name="hold_period_days" type="integer | null">
      Number of days commission is on hold before becoming available for payment
    </ResponseField>

    <ResponseField name="payment_intent_id" type="string | null">
      Payment intent ID if provided
    </ResponseField>

    <ResponseField name="invoice_id" type="string | null">
      Invoice ID if linked to a payout invoice
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the commission was created
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of when the commission was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>