Commission Tools

Overview

The commission tools allow you to track and manage commission transactions for your affiliates. All tools support both Markdown and JSON response formats.

Available Tools

Tool	Description	Permission
`affonso_list_commissions`	List commission transactions	`read:commissions`
`affonso_get_commission`	Get a single commission	`read:commissions`
`affonso_create_commission`	Create a new commission	`write:commissions`
`affonso_create_bonus`	Create a Bonus earning (no sale or referral)	`write:commissions`
`affonso_update_commission`	Update commission status	`write:commissions`
`affonso_delete_commission`	Delete a commission	`delete:commissions`

Commission Statuses

Status	Description
`PENDING`	Commission created, awaiting approval
`APPROVED`	Commission approved, ready for payout
`PAID`	Commission has been paid out
`REJECTED`	Commission was rejected
`REFUNDED`	Commission was refunded due to return/chargeback

affonso_list_commissions

List and filter commission transactions.

Parameters

number

default:"1"

Page number for pagination

number

default:"50"

Results per page (max 100)

string

Filter by affiliate ID

string

Filter by status: PENDING, APPROVED, PAID, REJECTED, REFUNDED

string

Filter from date (ISO 8601)

string

Filter to date (ISO 8601)

string

default:"markdown"

Response format: markdown or json. Also accepted as responseFormat.

Example Prompts

List all commissions
Show pending commissions
Get commissions for affiliate aff_abc123
Show approved commissions from last month
What commissions are ready for payout?

Response

## Commissions (Page 1 of 3)

### txn_abc123
- **Affiliate:** John Smith (aff_123)
- **Amount:** $9.90
- **Sale Amount:** $99.00
- **Status:** APPROVED
- **Created:** Jan 15, 2024

### txn_def456
- **Affiliate:** Jane Doe (aff_456)
- **Amount:** $15.00
- **Sale Amount:** $150.00
- **Status:** PENDING
- **Created:** Jan 14, 2024

---
**Total:** $24.90 across 2 commissions

{
  "commissions": [
    {
      "id": "txn_abc123",
      "affiliateId": "aff_123",
      "affiliateName": "John Smith",
      "amount": 990,
      "saleAmount": 9900,
      "status": "APPROVED",
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 25,
    "totalPages": 1
  },
  "summary": {
    "totalAmount": 2490
  }
}

affonso_get_commission

Get detailed information about a specific commission.

Parameters

string

required

The commission ID (starts with txn_)

string

default:"markdown"

Response format: markdown or json. Also accepted as responseFormat.

Example Prompts

Get commission txn_abc123
Show details for commission txn_xyz789
What's the status of transaction txn_pending123

Response

## Commission: txn_abc123

| Field | Value |
|-------|-------|
| Affiliate | John Smith (aff_123) |
| Commission | $9.90 |
| Sale Amount | $99.00 |
| Rate | 10% |
| Status | APPROVED |
| Referral | ref_xyz789 |
| Created | Jan 15, 2024 |
| Approved | Jan 16, 2024 |

### Notes
Commission approved after 30-day refund window.

{
  "id": "txn_abc123",
  "affiliateId": "aff_123",
  "affiliateName": "John Smith",
  "amount": 990,
  "saleAmount": 9900,
  "rate": 10,
  "status": "APPROVED",
  "referralId": "ref_xyz789",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "approvedAt": "2024-01-16T10:00:00.000Z"
}

affonso_create_commission

Create a new commission record for a referral. Same required fields as POST /v1/commissions: a referral, a positive sale amount, and a commission amount. For a non-sale cash bonus with no referral, use affonso_create_bonus.

Parameters

string

required

ID of the referral this commission belongs to

number

required

Total sale/transaction amount (not the commission amount). Must be a positive number

number

required

Commission amount earned. Must be a non-negative number (can be 0)

string

default:"USD"

Currency code for the sale (3 letters, e.g. USD, EUR). Defaults to USD

string

default:"USD"

Currency code for the commission (3 letters). Defaults to USD

boolean

default:"false"

Whether this is a recurring subscription commission

string

default:"pending"

Initial status: pending, pending_manual_approval, ready_for_payment, paid, declined

string

default:"complete"

Purchase status: open, complete, trialing, failed, refunded, partial_refunded

string

Payment provider intent ID. If set, must be unique across commissions

integer

Days to hold the commission before payout. Non-negative integer. Uses program default if omitted

string

default:"markdown"

Response format: markdown or json. Also accepted as responseFormat.

Example Prompts

Create a commission for referral ref_abc123 with sale amount 99 and commission amount 9.90
Record commission_amount 25.50 on referral ref_xyz from sale_amount 255
Create a pending commission for ref_123 with sale_amount 100 and commission_amount 10 in USD
Create a commission for referral ref_top with sale_amount 500 and commission_amount 50

Response

## Commission Created

| Field | Value |
|-------|-------|
| ID | txn_new123 |
| Referral | ref_abc123 |
| Sale Amount | $99.00 |
| Commission | $9.90 |
| Status | pending |
| Created | Jan 15, 2024 |

The commission is pending.

affonso_create_bonus

Create a first-class Bonus earning for an affiliate. This is not a sale commission: do not send a referral or sale amount. The result is bonus and ready_for_payment, and it is payout-eligible like other ready earnings.

Parameters

string

required

Affiliate to credit. Must belong to the authenticated team. Example: cm3abc123def456

number

required

Bonus amount in the team’s currency. Must be between 0.0001 and 999999.9999 with at most 4 decimal places. Zero, negative, overflow, and extra-precision values are rejected. Example: 50

string

Optional note shown to the brand and affiliate (stored as the earning description). Maximum 2000 characters. Example: Q3 partner bonus

string

default:"markdown"

Response format: markdown or json. Also accepted as responseFormat.

Example Prompts

Create a $50 bonus for affiliate aff_abc123
Add a Q3 partner bonus of $100 for aff_top with note "Q3 partner bonus"
Credit affiliate cm3abc123def456 a 25.50 bonus
Give aff_xyz a 0.5 bonus with note "referral contest"

Response

The created earning is a Bonus with status ready_for_payment. There is no sale and no referral.

### $50.00 👍
**Earning Type:** bonus
**Status:** ready_for_payment
**Affiliate:** `aff_abc123`
**Note:** Q3 partner bonus

affonso_update_commission

Update an existing commission’s status or information.

Parameters

string

required

The commission ID to update

string

New status: PENDING, APPROVED, REJECTED, REFUNDED

number

Updated commission amount in cents

string

Updated description

string

default:"markdown"

Response format: markdown or json. Also accepted as responseFormat.

Example Prompts

Approve commission txn_abc123
Reject commission txn_xyz due to fraud
Mark commission txn_123 as refunded
Update commission txn_456 amount to $75

Response

## Commission Updated

**txn_abc123** has been updated:
- Status: PENDING → APPROVED

This commission is now ready for payout.

affonso_delete_commission

This is a destructive operation. Commissions that have been paid cannot be deleted.

Parameters

string

required

The commission ID to delete

string

default:"markdown"

Response format: markdown or json. Also accepted as responseFormat.

Example Prompts

Delete commission txn_abc123
Remove commission txn_test456

Response

## Commission Deleted

Commission **txn_abc123** has been permanently deleted.

Bulk Operations

Approve Multiple Commissions

"List all pending commissions from before January 1st"
"Approve commissions txn_abc, txn_def, and txn_ghi"

Monthly Commission Report

"Show me all approved commissions from last month grouped by affiliate"
"What's the total commission amount for January?"

Error Handling

Error	Cause	Solution
`NOT_FOUND`	Commission ID doesn’t exist	Verify the ID is correct
`ALREADY_PAID`	Cannot modify paid commission	Commission is locked after payout
`INVALID_TRANSITION`	Invalid status change	Check allowed status transitions
`PERMISSION_DENIED`	Missing required scope	Check your API key permissions

Getting Started

Setup

Tools

Overview

Available Tools

Commission Statuses

affonso_list_commissions

Parameters

Example Prompts

Response

affonso_get_commission

Parameters

Example Prompts

Response

affonso_create_commission

Parameters

Example Prompts

Response

affonso_create_bonus

Parameters

Example Prompts

Response

affonso_update_commission

Parameters

Example Prompts

Response

affonso_delete_commission

Parameters

Example Prompts

Response

Bulk Operations

Approve Multiple Commissions

Monthly Commission Report

Error Handling

​Overview

​Available Tools

​Commission Statuses

​affonso_list_commissions

​Parameters

​Example Prompts

​Response

​affonso_get_commission

​Parameters

​Example Prompts

​Response

​affonso_create_commission

​Parameters

​Example Prompts

​Response

​affonso_create_bonus

​Parameters

​Example Prompts

​Response

​affonso_update_commission

​Parameters

​Example Prompts

​Response

​affonso_delete_commission

​Parameters

​Example Prompts

​Response

​Bulk Operations

​Approve Multiple Commissions

​Monthly Commission Report

​Error Handling

Overview

Available Tools

Commission Statuses

affonso_list_commissions

Parameters

Example Prompts

Response

affonso_get_commission

Parameters

Example Prompts

Response

affonso_create_commission

Parameters

Example Prompts

Response

affonso_create_bonus

Parameters

Example Prompts

Response

affonso_update_commission

Parameters

Example Prompts

Response

affonso_delete_commission

Parameters

Example Prompts

Response

Bulk Operations

Approve Multiple Commissions

Monthly Commission Report

Error Handling