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

# Commissions

> Sync commission operations bidirectionally with your finance software.

Introw calculates partner commissions and groups them into **Payouts**. Your finance software — NetSuite, Xero, a custom AP stack, or anything in between — owns the rest: review, approve, schedule payment, and mark paid. The commission lines that make up each payout can be managed individually through the API.

Introw is the commission source of truth. Your finance stack is the payment source of truth. Status updates flow back so partner managers see a single view in Introw.

## Concepts

* **Payout** — a per-partner bundle of commission lines for a period. It has a `stage` (your finance workflow status) and an optional `poNumber`.
* **Commission line** — an individual commission amount for a partner. A line can sit in the pending pool (no payout) or be attached to a payout. Lines are managed through the top-level `/commission-lines` endpoints.

## Authentication

Create an API key with `commissions:read` and `commissions:write` scopes. See [Authentication](/general/authentication) for key creation, rotation, and request signing.

## End-to-end walkthrough

### 1. List payouts ready for review

Poll for payouts in `PENDING_REVIEW`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.introw.io/api/v1/payouts?stage=PENDING_REVIEW" \
  -H "x-api-key: $INTROW_API_KEY"
```

### 2. Inspect the commission lines on a payout

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.introw.io/api/v1/commission-lines?payoutId=pay_2x7n4q8z0w1a2b3c4d5e6f7g" \
  -H "x-api-key: $INTROW_API_KEY"
```

### 3. Approve a payout

After your approval workflow passes, update the payout stage and attach your purchase order number:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://api.introw.io/api/v1/payouts/pay_2x7n4q8z0w1a2b3c4d5e6f7g" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "APPROVED",
    "poNumber": "PO-ACME-2026-Q1"
  }'
```

### 4. Mark the payout as paid

After your ERP confirms payment, sync the final status back to Introw:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://api.introw.io/api/v1/payouts/pay_2x7n4q8z0w1a2b3c4d5e6f7g" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "PAID" }'
```

## Managing commission lines

### Create a line

Create a pending line (no payout) that a future payout batch can pick up:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.introw.io/api/v1/commission-lines" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerId": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
    "amount": "500.00",
    "currency": "USD",
    "description": "Q1 referral bonus"
  }'
```

Pass `payoutId` to attach the line to an existing payout on creation instead.

### Edit a line

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://api.introw.io/api/v1/commission-lines/cln_4d5e6f7g8h9i0j1k2l3m4n5o" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "750.00", "description": "Q1 referral bonus (adjusted)" }'
```

### Decline a line

Soft-delete (void) a line attached to a payout, with a categorised reason. If the payout becomes empty, it is automatically declined.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.introw.io/api/v1/commission-lines/cln_5o4n3m2l1k0j9i8h7g6f5e4d/decline" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reasonType": "DUPLICATE" }'
```

### Detach a line

Remove a line from its payout and return it to the pending pool for a future batch:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.introw.io/api/v1/commission-lines/cln_5o4n3m2l1k0j9i8h7g6f5e4d/detach" \
  -H "x-api-key: $INTROW_API_KEY"
```

## Payout stages

Set the stage that matches your finance workflow. The API accepts any valid stage value — use the recommended flow below as guidance.

| Stage             | When to use it                              |
| ----------------- | ------------------------------------------- |
| `DRAFT`           | Payout created but not yet ready for review |
| `PENDING_REVIEW`  | New payout ready for your approval workflow |
| `PENDING_INVOICE` | Approved — waiting for a partner invoice    |
| `APPROVED`        | Approved and ready to schedule              |
| `SCHEDULED`       | Payment scheduled in your ERP               |
| `PENDING_PAYMENT` | Payment initiated                           |
| `PAID`            | Payment confirmed — sync back to Introw     |
| `DECLINED`        | Payout rejected and will not be paid        |
| `POSTPONED`       | Deferred to a later payout                  |
| `BLOCKED`         | On hold pending resolution                  |
| `FAILED`          | Payment attempt failed                      |

Recommended flow: `PENDING_REVIEW` → `APPROVED` → `PENDING_PAYMENT` → `PAID`.

## API reference

<CardGroup cols={2}>
  <Card title="List payouts" icon="list" href="/api-reference/payouts/list-payouts">
    GET /api/v1/payouts
  </Card>

  <Card title="Update a payout" icon="pen" href="/api-reference/payouts/update-a-payout">
    PATCH /api/v1/payouts/{id}
  </Card>

  <Card title="Create a commission line" icon="plus" href="/api-reference/commission-lines/create-a-commission-line">
    POST /api/v1/commission-lines
  </Card>

  <Card title="Decline a commission line" icon="ban" href="/api-reference/commission-lines/decline-a-commission-line">
    POST /api/v1/commission-lines/{id}/decline
  </Card>
</CardGroup>