Affiliate Tools

Overview

The affiliate tools allow you to manage affiliates in your program through natural language commands. Create and update work on affiliate Accounts and durable program contacts, without creating merchant Users. All tools support both Markdown and JSON response formats.

Available Tools

Tool	Description	Permission
`affonso_list_affiliates`	List affiliates with filtering and pagination	`read:affiliates`
`affonso_get_affiliate`	Get a single affiliate by ID	`read:affiliates`
`affonso_create_affiliate`	Create a new affiliate	`write:affiliates`
`affonso_update_affiliate`	Update an existing affiliate	`write:affiliates`
`affonso_delete_affiliate`	Delete an affiliate	`delete:affiliates`

affonso_list_affiliates

List and search affiliates with powerful filtering options.

Parameters

number

default:"1"

Page number for pagination

number

default:"50"

Number of results per page (max 100)

string

Search by name, email, or tracking ID

string

Filter by partnership status: APPROVED, PENDING, REJECTED

string

default:"createdAt"

Sort field: createdAt, name, email

string

default:"desc"

Sort order: asc or desc

string

default:"markdown"

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

Example Prompts

List all my affiliates
Show me pending affiliates
Find affiliates with "john" in their name
List top 10 affiliates sorted by name

Response

## Affiliates (Page 1 of 3)

### John Smith
- **Email:** john@example.com
- **Tracking ID:** john-smith
- **Status:** APPROVED
- **Created:** Jan 15, 2024

### Jane Doe
- **Email:** jane@example.com
- **Tracking ID:** jane-doe
- **Status:** PENDING
- **Created:** Jan 14, 2024

---
Showing 2 of 25 affiliates

{
  "affiliates": [
    {
      "id": "aff_abc123",
      "name": "John Smith",
      "email": "john@example.com",
      "trackingId": "john-smith",
      "partnershipStatus": "APPROVED",
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 25,
    "totalPages": 1
  }
}

affonso_get_affiliate

Retrieve detailed information about a specific affiliate.

Parameters

string

required

The affiliate ID (starts with aff_)

array

Include related data: promoCodes, commissionOverrides, invoiceDetails, payoutMethod, onboardingResponses

string

default:"markdown"

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

Example Prompts

Get affiliate aff_abc123
Show me details for affiliate aff_xyz789 with their promo codes
Get affiliate info including commission overrides
Show affiliate aff_abc123 with their onboarding responses

Response

## Affiliate: John Smith

| Field | Value |
|-------|-------|
| ID | aff_abc123 |
| Email | john@example.com |
| Tracking ID | john-smith |
| Status | APPROVED |
| Created | Jan 15, 2024 |

### Promo Codes
- **JOHN20** - 20% off (Active)
- **JOHNVIP** - 30% off (Inactive)

{
  "id": "aff_abc123",
  "name": "John Smith",
  "email": "john@example.com",
  "trackingId": "john-smith",
  "partnershipStatus": "APPROVED",
  "promoCodes": [
    {
      "code": "JOHN20",
      "discountPercent": 20,
      "active": true
    }
  ],
  "onboardingResponses": {
    "form_name": "Affiliate Onboarding",
    "form_description": "Complete this form to get started",
    "completed_at": "2024-01-15T10:00:00.000Z",
    "questions": [
      {
        "id": "q1",
        "question": "What is your primary marketing channel?",
        "type": "single_choice",
        "is_required": true,
        "options": ["Social Media", "Email", "Blog", "Other"],
        "order": 1,
        "answer": "Social Media"
      },
      {
        "id": "q2",
        "question": "Tell us about your audience",
        "type": "textarea",
        "is_required": false,
        "options": [],
        "order": 2,
        "answer": "Tech-savvy professionals aged 25-45"
      }
    ]
  },
  "createdAt": "2024-01-15T10:00:00.000Z"
}

affonso_create_affiliate

Create a new affiliate in your program. Provisions an affiliate Account and durable program contact (no merchant User).

Parameters

string

required

Affiliate’s email address

string

Affiliate’s display name

string

Custom tracking ID (auto-generated if not provided)

string

default:"approved"

Initial partnership status: pending, approved, or rejected. Omit to auto-approve. No second update call is required.

string

default:"markdown"

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

Example Prompts

Create an affiliate for john@example.com
Add a new affiliate named "Jane Doe" with email jane@example.com
Create an approved affiliate for partner@company.com with tracking ID "partner-co"

Response

## Affiliate Created Successfully

| Field | Value |
|-------|-------|
| ID | aff_new123 |
| Email | john@example.com |
| Tracking ID | john-example |
| Status | PENDING |

The affiliate will receive an invitation email.

affonso_update_affiliate

Update an existing affiliate’s information.

Parameters

string

required

The affiliate ID to update

string

New display name

string

New email address

string

New partnership status: APPROVED, PENDING, REJECTED

object

Partial billing and invoice details. Omitted keys keep their current values. null clears optional fields. Creating a first invoice record requires first_name, last_name, address_line_1, city, and country.

string

Payout method (none to remove). Valid values match PUT /v1/affiliates/{id}.If you send payout_method without payout_details, or with empty / method-incomplete details, only the method type is updated. Existing PayPal, bank, and crypto credentials stay in place.

object

Payout details for the selected method. Sending this object replaces credentials and clears fields from other methods. Omit it to keep stored credentials when you only change payout_method.

string

default:"markdown"

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

Example Prompts

Approve affiliate aff_abc123
Update affiliate aff_xyz to have email new@example.com
Change the name of affiliate aff_123 to "John Smith Jr."
Reject affiliate aff_pending456
Set affiliate aff_abc123 payout method to PayPal without changing the saved email

Response

## Affiliate Updated

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

The affiliate is now active and can start promoting.

affonso_delete_affiliate

This is a destructive operation. The affiliate and all their data will be permanently deleted.

Parameters

string

required

The affiliate ID to delete

string

default:"markdown"

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

Example Prompts

Delete affiliate aff_abc123
Remove affiliate aff_old789

Response

## Affiliate Deleted

Affiliate **aff_abc123** (john@example.com) has been permanently deleted.

Error Handling

Common errors you may encounter:

Error	Cause	Solution
`NOT_FOUND`	Affiliate ID doesn’t exist	Verify the ID is correct
`DUPLICATE_ERROR`	Email already exists	Use a different email
`PERMISSION_DENIED`	Missing required scope	Check your API key permissions
`VALIDATION_ERROR`	Invalid parameter value	Check parameter format

Getting Started

Setup

Tools

Overview

Available Tools

affonso_list_affiliates

Parameters

Example Prompts

Response

affonso_get_affiliate

Parameters

Example Prompts

Response

affonso_create_affiliate

Parameters

Example Prompts

Response

affonso_update_affiliate

Parameters

Example Prompts

Response

affonso_delete_affiliate

Parameters

Example Prompts

Response

Error Handling

​Overview

​Available Tools

​affonso_list_affiliates

​Parameters

​Example Prompts

​Response

​affonso_get_affiliate

​Parameters

​Example Prompts

​Response

​affonso_create_affiliate

​Parameters

​Example Prompts

​Response

​affonso_update_affiliate

​Parameters

​Example Prompts

​Response

​affonso_delete_affiliate

​Parameters

​Example Prompts

​Response

​Error Handling

Overview

Available Tools

affonso_list_affiliates

Parameters

Example Prompts

Response

affonso_get_affiliate

Parameters

Example Prompts

Response

affonso_create_affiliate

Parameters

Example Prompts

Response

affonso_update_affiliate

Parameters

Example Prompts

Response

affonso_delete_affiliate

Parameters

Example Prompts

Response

Error Handling