Skip to main content

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.

​
Overview

The payout tools allow you to manage and track affiliate payouts. All tools support both Markdown and JSON response formats.

​
Available Tools

ToolDescriptionPermission
affonso_list_payoutsList payouts with filteringread:payouts
affonso_get_payoutGet a single payout with detailsread:payouts
affonso_update_payoutUpdate payout statuswrite:payouts
Payouts are typically created automatically when processing affiliate payments through the dashboard. Use these tools to track and update payout status.

​
Payout Statuses

StatusDescription
PENDINGPayout created, awaiting processing
PROCESSINGPayout is being processed
COMPLETEDPayout successfully sent
FAILEDPayout failed to process
CANCELLEDPayout was cancelled

​
affonso_list_payouts

List and filter payouts.

​
Parameters

​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"50"
Results per page (max 100)
​
affiliateId
string
Filter by affiliate ID
​
status
string
Filter by status: PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED
​
startDate
string
Filter from date (ISO 8601)
​
endDate
string
Filter to date (ISO 8601)
​
responseFormat
string
default:"markdown"
Response format: markdown or json

​
Example Prompts

List all payouts
Show pending payouts
Get payouts for affiliate aff_abc123
Show completed payouts from last month
What payouts are processing right now?

​
Response

## Payouts (Page 1 of 2)

### pay_abc123
- **Affiliate:** John Smith (aff_123)
- **Amount:** $500.00
- **Transactions:** 15
- **Status:** COMPLETED
- **Processed:** Jan 15, 2024

### pay_def456
- **Affiliate:** Jane Doe (aff_456)
- **Amount:** $250.00
- **Transactions:** 8
- **Status:** PENDING
- **Created:** Jan 14, 2024

---
**Total:** $750.00 across 2 payouts

​
affonso_get_payout

Get detailed information about a specific payout, including all associated transactions.

​
Parameters

​
id
string
required
The payout ID (starts with pay_)
​
responseFormat
string
default:"markdown"
Response format: markdown or json

​
Example Prompts

Get payout pay_abc123
Show details for payout pay_xyz789
What transactions are in payout pay_pending123

​
Response

## Payout: pay_abc123

| Field | Value |
|-------|-------|
| Affiliate | John Smith (aff_123) |
| Amount | $500.00 |
| Status | COMPLETED |
| Method | Bank Transfer |
| Created | Jan 10, 2024 |
| Processed | Jan 15, 2024 |

### Included Transactions (15)

| ID | Amount | Sale | Date |
|----|--------|------|------|
| txn_001 | $35.00 | $350.00 | Jan 5 |
| txn_002 | $42.00 | $420.00 | Jan 6 |
| txn_003 | $28.00 | $280.00 | Jan 7 |
| ... and 12 more |

### Payment Details
- **Bank:** Chase Bank ****1234
- **Reference:** PAY-2024-001234

​
affonso_update_payout

Update an existing payout’s status.

​
Parameters

​
id
string
required
The payout ID to update
​
status
string
required
New status: PROCESSING, COMPLETED, FAILED, CANCELLED
​
notes
string
Notes about the status change
​
responseFormat
string
default:"markdown"
Response format: markdown or json

​
Example Prompts

Mark payout pay_abc123 as completed
Set payout pay_xyz to processing
Cancel payout pay_pending456
Mark payout pay_123 as failed with note "Bank rejected transfer"

​
Response

## Payout Updated

**pay_abc123** has been updated:
- Status: PENDING → COMPLETED

All included transactions have been marked as paid.

​
Common Workflows

​
Process Pending Payouts

1. "List all pending payouts"
2. "Get details for payout pay_abc123"
3. "Mark payout pay_abc123 as processing"
4. (Process payment externally)
5. "Mark payout pay_abc123 as completed"

​
Review Affiliate Earnings

"Show all completed payouts for affiliate aff_abc123"
"What's the total paid to John Smith this year?"
"List failed payouts from last month"

​
Monthly Payout Report

"Show all payouts from January 2024"
"What's the total amount paid out last month?"
"List affiliates with pending payouts over $100"

​
Status Transitions

Once a payout is COMPLETED, its status cannot be changed. Refunds should be handled as new commission adjustments.

​
Error Handling

ErrorCauseSolution
NOT_FOUNDPayout ID doesn’t existVerify the ID is correct
ALREADY_COMPLETEDCannot modify completed payoutCreate a refund/adjustment instead
INVALID_TRANSITIONInvalid status changeCheck allowed status transitions
PERMISSION_DENIEDMissing required scopeCheck your API key permissions