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

# List Commissions

> Get a paginated list of all commissions with optional filtering

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Must be a positive integer.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of results per page. Maximum value is 200. Default is 50.
</ParamField>

<ParamField query="affiliate_id" type="string">
  Filter commissions by affiliate ID. Only returns commissions for the specified affiliate.
</ParamField>

<ParamField query="referral_id" type="string">
  Filter commissions by referral ID. Only returns commissions for the specified referral.
</ParamField>

<ParamField query="status" type="string">
  Filter commissions by commission status. Valid values: `pending`, `pending_manual_approval`, `ready_for_payment`, `paid`, `declined`.
</ParamField>

<ParamField query="sales_status" type="string">
  Filter commissions by sales/transaction status. Valid values: `open`, `complete`, `trialing`, `failed`, `refunded`, `partial_refunded`.
</ParamField>

<ParamField query="expand" type="string">
  Comma-separated list of related data to include. Valid values: `affiliate`, `affiliate_program`, `referral`. You can combine multiple values: `affiliate,referral`.
</ParamField>

<ParamField query="created_gte" type="string">
  Filter commissions created on or after this date. ISO 8601 date-time format (e.g., `2024-01-01T00:00:00Z`).
</ParamField>

<ParamField query="created_lte" type="string">
  Filter commissions created on or before this date. ISO 8601 date-time format (e.g., `2024-12-31T23:59:59Z`).
</ParamField>

## Response

The response includes a paginated list of commissions and pagination metadata.

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

<ResponseField name="data" type="array">
  Array of commission objects. Each commission object has the same structure as the single commission response (see Get Commission endpoint).

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

<ResponseField name="pagination" type="object">
  Pagination metadata object containing:

  * `page` (integer): Current page number
  * `limit` (integer): Number of results per page
  * `total` (integer): Total number of commissions matching the filters
  * `total_pages` (integer): Total number of pages
  * `has_next_page` (boolean): Whether there is a next page
  * `has_prev_page` (boolean): Whether there is a previous page
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.affonso.io/v1/commissions?limit=10&status=ready_for_payment&sales_status=complete" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```bash cURL with Expand theme={null}
  curl -X GET "https://api.affonso.io/v1/commissions?limit=10&expand=affiliate,referral" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```
</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": "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-20T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 50,
      "total_pages": 5,
      "has_next_page": true,
      "has_prev_page": false
    }
  }
  ```

  ```json Response with Expand 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": "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-20T15:30:00Z",
        "affiliate": {
          "id": "aff_789ghi",
          "name": "John Doe",
          "email": "john@example.com",
          "tracking_id": "PARTNER123",
          "source": "api",
          "partnership_status": "APPROVED",
          "onboarding_completed": true,
          "program_id": "prog_123xyz",
          "group_id": null,
          "created_at": "2024-01-15T10:30:00Z"
        },
        "referral": {
          "id": "ref_456def",
          "affiliate_id": "aff_789ghi",
          "program_id": "prog_123xyz",
          "email": "customer@example.com",
          "customer_id": "cust_123",
          "subscription_id": null,
          "status": "customer",
          "created_at": "2024-01-18T12:00:00Z",
          "converted_at": "2024-01-18T12:00:00Z"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 50,
      "total_pages": 5,
      "has_next_page": true,
      "has_prev_page": false
    }
  }
  ```
</ResponseExample>