> ## 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.

# Update Commission

> Update a commission's status, transaction status, hold period, or amounts

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the commission to update
</ParamField>

## Body Parameters

All body parameters are optional. Only include the fields you want to update.

<ParamField body="status" type="string">
  Update the commission status. Valid values: `pending`, `pending_manual_approval`, `ready_for_payment`, `paid`, `declined`. Status changes may trigger webhook events (`transaction.approved`, `transaction.rejected`, `transaction.paid`).
</ParamField>

<ParamField body="sales_status" type="string">
  Status of the customer's purchase. Valid values: `open`, `complete`, `trialing`, `failed`, `refunded`, `partial_refunded`.
</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.
</ParamField>

<ParamField body="sale_amount" type="number">
  Update the sale/transaction amount. Must be a positive number.
</ParamField>

<ParamField body="sale_amount_currency" type="string">
  Update the currency code for the sale amount. Must be a 3-letter currency code (e.g., `USD`, `EUR`).
</ParamField>

<ParamField body="commission_amount" type="number">
  Update the commission amount to be paid. Must be a non-negative number.
</ParamField>

<ParamField body="commission_currency" type="string">
  Update the currency code for the commission. Must be a 3-letter currency code (e.g., `USD`, `EUR`).
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  The updated 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
    </ResponseField>

    <ResponseField name="sale_amount_currency" type="string">
      The currency code for the sale (3 letters)
    </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. Can be `null` when the transaction exists without an affiliate earning.
    </ResponseField>

    <ResponseField name="status" type="string">
      Commission status: `pending`, `pending_manual_approval`, `ready_for_payment`, `paid`, `declined`
    </ResponseField>

    <ResponseField name="sales_status" type="string">
      Sales status: `open`, `complete`, `trialing`, `failed`, `refunded`, `partial_refunded`
    </ResponseField>

    <ResponseField name="hold_period_days" type="integer | null">
      Number of days commission is on hold
    </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
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.affonso.io/v1/commissions/com_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "ready_for_payment",
      "sale_amount": 149.00,
      "sale_amount_currency": "USD",
      "commission_amount": 14.90,
      "commission_currency": "USD"
    }'
  ```
</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": 149.00,
      "sale_amount_currency": "USD",
      "commission_amount": 14.90,
      "commission_currency": "USD",
      "status": "ready_for_payment",
      "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-20T16:45:00Z"
    }
  }
  ```
</ResponseExample>