Commissions

Introw calculates partner commissions and groups them into Payouts. From there, one of two things owns the payment. With Introw Pay, one consolidated invoice per batch settles every partner and the payout stages advance on their own; the API is your read model for booking and reconciliation. With manual invoicing, your finance software - NetSuite, Xero, a custom AP stack, or anything in between - owns the rest: review, approve, schedule payment, and mark paid through the API. The commission lines that make up each payout can be managed individually through the API in both cases, including creating lines for rewards decided outside a commission plan. Where the period and the lines are decided in your own system, the API builds the whole thing: the batch, each partner’s payout, the lines on it, and the commission statement PDF. Introw is the commission source of truth. Introw Pay or your finance stack is the payment source of truth. Status updates flow back so partner managers and partners 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.
Payout batch - the run around the payouts: one period holding one payout per partner, which is what the Payouts page lists. A payout created on its own opens a batch of its own.
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.
Commission statement - the PDF the partner invoices against, rendered from the payout’s lines and its statement note.

Authentication

Create an API key with commissions:read and commissions:write scopes. See Authentication for key creation, rotation, and request signing.

End-to-end walkthrough

1. List payouts ready for review

Poll for payouts in PENDING_REVIEW:

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

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:

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:

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:

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

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 categorized reason. If the payout becomes empty, it is automatically declined.

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:

curl -X POST "https://api.introw.io/api/v1/commission-lines/cln_5o4n3m2l1k0j9i8h7g6f5e4d/detach" \
  -H "x-api-key: $INTROW_API_KEY"

Building payouts yourself

The walkthrough above reads payouts Introw built. You can also build them, when the period, the partners and the lines are all decided in your own system.

Open the run

POST /api/v1/payout-batches opens one period and, optionally, a draft payout for each partner you name. Use it whenever the run covers several partners, so they stay one batch rather than one batch each.

curl -X POST "https://api.introw.io/api/v1/payout-batches" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "periodStart": "2026-01-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.000Z",
    "partnerIds": ["ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8", "ptn_02JWL7Z9A9R8K9K9K9K9K9K9K9"]
  }'

Open one partner’s payout

POST /api/v1/payouts opens a single payout in DRAFT. Pass batchId to add a partner to a run that already exists, metadata to set the statement note in the same call, and attachPendingLines: true to pull in that partner’s pending lines for the period the way the app does.

curl -X POST "https://api.introw.io/api/v1/payouts" \
  -H "x-api-key: $INTROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerId": "ptn_01HVK6Y8Z8Q7J8J8J8J8J8J8J8",
    "periodStart": "2026-01-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.000Z",
    "metadata": "Remittance reference: ACME-Q1-2026"
  }'

Then attach each line with POST /api/v1/commission-lines and its payoutId. Send sourceAmount alongside amount when the commission came off a deal value, and the statement prints the calculation, EUR 4,200.00 x 10%, instead of the amount alone.

Render the statement

POST /api/v1/payouts/{id}/statement renders the commission statement and returns a signed link, with expiresAt telling you when it lapses. The PDF is rebuilt only when something on it changed, so calling it after every edit stays cheap.

curl -X POST "https://api.introw.io/api/v1/payouts/pay_2x7n4q8z0w1a2b3c4d5e6f7g/statement" \
  -H "x-api-key: $INTROW_API_KEY"

It needs complete commission billing information and at least one line on the payout, or it answers 422 with NO_BILLING_INFO or NO_COMMISSION_LINES. When someone uploaded their own statement in the app, that PDF is returned untouched and isUploaded is true.

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. On Introw Pay, PENDING_PAYMENT, SCHEDULED, PAID, BLOCKED and FAILED are set by the payment run itself. Read them, but do not write over them: once Introw Pay owns a payout’s payment, moving it back from PAID is rejected.

API reference

List payouts

GET /api/v1/payouts

Update a payout

PATCH /api/v1/payouts/

Create a commission line

POST /api/v1/commission-lines

Decline a commission line

POST /api/v1/commission-lines//decline

INTROW API

Use cases

Partner API

Forms API

CRM API

Commission payouts API

Commission lines API

Collaboration API

Embed API

Affiliate API

Concepts

Authentication

End-to-end walkthrough

1. List payouts ready for review

2. Inspect the commission lines on a payout

3. Approve a payout

4. Mark the payout as paid

Managing commission lines

Create a line

Edit a line

Decline a line

Detach a line

Building payouts yourself

Open the run

Open one partner’s payout

Render the statement

Payout stages

API reference

List payouts

Update a payout

Create a commission line

Decline a commission line

​Concepts

​Authentication

​End-to-end walkthrough

​1. List payouts ready for review

​2. Inspect the commission lines on a payout

​3. Approve a payout

​4. Mark the payout as paid

​Managing commission lines

​Create a line

​Edit a line

​Decline a line

​Detach a line

​Building payouts yourself

​Open the run

​Open one partner’s payout

​Render the statement

​Payout stages

​API reference

List payouts

Update a payout

Create a commission line

Decline a commission line

Concepts

Authentication

End-to-end walkthrough

1. List payouts ready for review

2. Inspect the commission lines on a payout

3. Approve a payout

4. Mark the payout as paid

Managing commission lines

Create a line

Edit a line

Decline a line

Detach a line

Building payouts yourself

Open the run

Open one partner’s payout

Render the statement

Payout stages

API reference