Skip to main content
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 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 categorised 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"

​
Payout stages

Set the stage that matches your finance workflow. The API accepts any valid stage value — use the recommended flow below as guidance.
StageWhen to use it
DRAFTPayout created but not yet ready for review
PENDING_REVIEWNew payout ready for your approval workflow
PENDING_INVOICEApproved — waiting for a partner invoice
APPROVEDApproved and ready to schedule
SCHEDULEDPayment scheduled in your ERP
PENDING_PAYMENTPayment initiated
PAIDPayment confirmed — sync back to Introw
DECLINEDPayout rejected and will not be paid
POSTPONEDDeferred to a later payout
BLOCKEDOn hold pending resolution
FAILEDPayment attempt failed
Recommended flow: PENDING_REVIEW → APPROVED → PENDING_PAYMENT → PAID.

​
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