Create Affiliate

curl -X POST "https://api.affonso.io/v1/affiliates" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "company_name": "Jane LLC",
    "country_code": "US",
    "payout_method": "paypal",
    "payout_details": {
      "email": "jane@example.com"
    },
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    }
  }'

curl -X POST "https://api.affonso.io/v1/affiliates" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "tracking_id": "janesmith-2024",
    "payout_method": "paypal",
    "payout_details": {
      "email": "jane@example.com"
    }
  }'

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tracking_id": "jane-smith",
    "source": "api",
    "partnership_status": "APPROVED",
    "onboarding_completed": false,
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "group_id": null,
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    },
    "created_at": "2024-01-25T09:15:00Z"
  }
}

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tracking_id": "janesmith-2024",
    "source": "api",
    "partnership_status": "APPROVED",
    "onboarding_completed": false,
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "group_id": null,
    "external_user_id": null,
    "metadata": null,
    "created_at": "2024-01-25T09:15:00Z"
  }
}

POST

affiliates

curl -X POST "https://api.affonso.io/v1/affiliates" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "company_name": "Jane LLC",
    "country_code": "US",
    "payout_method": "paypal",
    "payout_details": {
      "email": "jane@example.com"
    },
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    }
  }'

curl -X POST "https://api.affonso.io/v1/affiliates" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "tracking_id": "janesmith-2024",
    "payout_method": "paypal",
    "payout_details": {
      "email": "jane@example.com"
    }
  }'

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tracking_id": "jane-smith",
    "source": "api",
    "partnership_status": "APPROVED",
    "onboarding_completed": false,
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "group_id": null,
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    },
    "created_at": "2024-01-25T09:15:00Z"
  }
}

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tracking_id": "janesmith-2024",
    "source": "api",
    "partnership_status": "APPROVED",
    "onboarding_completed": false,
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "group_id": null,
    "external_user_id": null,
    "metadata": null,
    "created_at": "2024-01-25T09:15:00Z"
  }
}

Body Parameters

string

required

The affiliate’s full display name. Must be between 1 and 100 characters.

string

required

The affiliate’s email address. Must be a valid email format. If a user with this email already exists, they will be linked to the affiliate account.

string

required

Program ID to associate affiliate with.

string

Custom tracking ID for the affiliate. Must contain only lowercase letters, numbers, and hyphens. Maximum 100 characters. If not provided, a tracking ID will be automatically generated from the affiliate’s name. Must be unique within your team.

string

Optional affiliate group ID.

string

Company name for invoice. Maximum 100 characters.

string

2-letter ISO country code.

string

Payout method (lowercase with underscores). Valid values: paypal, wise, payoneer, paxum, webmoney, skrill, wire_transfer, bitcoin, ethereum, alipay, wechat, manual, none.

object

Payout details (fields vary by method, all snake_case). The required fields depend on the payout_method:

Email-based methods (paypal, wise, payoneer, paxum, skrill): email (string, valid email)
ID-based methods (webmoney, alipay, wechat): account_id (string)
Crypto methods (bitcoin, ethereum): address (string, wallet address)
Wire transfer (wire_transfer): bank_name, account_number, swift_code, iban, routing_number, account_name (all strings)
Manual (manual): No details required

string

Your external user ID for linking referral users to your own user system. Useful for matching affiliates back to users in your application. Maximum 255 characters.

object

Custom key-value data for storing additional information about the affiliate. You can store any JSON-serializable data here (e.g., {"plan": "pro", "signup_source": "landing_page"}).

Response

The response includes the created affiliate object with the following fields:

boolean

Always true for successful responses

object

The created affiliate object.

Show Data Object Properties

string

Unique identifier for the affiliate

string

The affiliate’s display name

string

The affiliate’s email address

string

Unique tracking ID for the affiliate. If a custom tracking_id was provided in the request, it will be used. Otherwise, it’s automatically generated from the name (with a random suffix if needed for uniqueness).

string

Source of the affiliate creation, always "api" for API-created affiliates

string

Partnership status with the program. Will be "APPROVED" for newly created affiliates. Can be "PENDING", "APPROVED", "REJECTED", or null.

boolean

Whether the affiliate has completed their onboarding process. Always false for newly created affiliates.

string

The affiliate program ID the affiliate is assigned to

string | null

The affiliate group ID if assigned, otherwise null

string | null

Your external user ID if provided, otherwise null

object | null

Custom key-value data if provided, otherwise null

string

ISO 8601 timestamp of when the affiliate was created

curl -X POST "https://api.affonso.io/v1/affiliates" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "company_name": "Jane LLC",
    "country_code": "US",
    "payout_method": "paypal",
    "payout_details": {
      "email": "jane@example.com"
    },
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    }
  }'

curl -X POST "https://api.affonso.io/v1/affiliates" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "tracking_id": "janesmith-2024",
    "payout_method": "paypal",
    "payout_details": {
      "email": "jane@example.com"
    }
  }'

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tracking_id": "jane-smith",
    "source": "api",
    "partnership_status": "APPROVED",
    "onboarding_completed": false,
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "group_id": null,
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    },
    "created_at": "2024-01-25T09:15:00Z"
  }
}

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "tracking_id": "janesmith-2024",
    "source": "api",
    "partnership_status": "APPROVED",
    "onboarding_completed": false,
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "group_id": null,
    "external_user_id": null,
    "metadata": null,
    "created_at": "2024-01-25T09:15:00Z"
  }
}

Notes

To retrieve related data like promo codes, commission overrides, invoice details, and payout methods, use GET /v1/affiliates/{id}?expand=promoCodes,commissionOverrides,invoiceDetails,payoutMethod.
If you provide a custom tracking_id that is already in use by another affiliate in your team, the API will return a 409 Conflict error with the code DUPLICATE_ERROR.
The tracking_id must contain only lowercase letters (a-z), numbers (0-9), and hyphens (-). Any other characters will result in a 400 Bad Request validation error.

Getting Started

Guide

Core Resources

Program Management

Marketplace

Body Parameters

Response

Notes

​Body Parameters

​Response

​Notes

Body Parameters

Response

Notes