Skip to main content
POST
/
v1
/
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": "[email protected]",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "company_name": "Jane LLC",
    "country_code": "US",
    "payout_method": "paypal",
    "payout_details": {
      "email": "[email protected]"
    },
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    }
  }'

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "[email protected]",
    "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"
  }
}

​
Body Parameters

​
name
string
required
The affiliate’s full display name. Must be between 1 and 100 characters.
​
email
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.
​
program_id
string
required
Program ID to associate affiliate with.
​
tracking_id
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.
​
group_id
string
Optional affiliate group ID.
​
company_name
string
Company name for invoice. Maximum 100 characters.
​
country_code
string
2-letter ISO country code.
​
payout_method
string
Payout method (lowercase with underscores). Valid values: paypal, wise, payoneer, paxum, webmoney, skrill, wire_transfer, bitcoin, ethereum, alipay, wechat, manual, none.
​
payout_details
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
​
external_user_id
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.
​
metadata
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:
​
success
boolean
Always true for successful responses
​
data
object
The created affiliate object.
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": "[email protected]",
    "program_id": "cm7xutqbb0001yfkcrnpextmp",
    "company_name": "Jane LLC",
    "country_code": "US",
    "payout_method": "paypal",
    "payout_details": {
      "email": "[email protected]"
    },
    "external_user_id": "user_123",
    "metadata": {
      "plan": "pro",
      "signup_source": "landing_page"
    }
  }'

{
  "success": true,
  "data": {
    "id": "cmj8q1wau0003sb01lpvka478",
    "name": "Jane Smith",
    "email": "[email protected]",
    "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"
  }
}

​
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.