MLM API

Common Information

Base URL

/api/v1/mlm

Authentication Header

Authorization: Bearer <access_token>

Response Envelope

All responses follow the standard format:

typescript

// Success response
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    pagination?: PaginationMeta;
    [key: string]: unknown;
  };
}

// Error response
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, string[]>;
  };
}

Pagination Format

typescript

interface PaginationMeta {
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
  hasNext: boolean;
  hasPrevious: boolean;
}

Rate Limits

Endpoint	Limit
General MLM endpoints	100/min
POST /payouts/request	1/min per user
Network queries	50/min

Financial Endpoint Rate Limit Headers

X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705329600
X-RateLimit-Policy: financial

Partner Endpoints

POST /api/v1/mlm/partner/register

Authentication: Required

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

typescript

interface PartnerRegisterRequest {
  referralCode?: string; // Sponsor's referral code (optional)
  acceptPartnerTerms: boolean; // Must be true
}

Query Parameters

None

Response (201 Created)

typescript

interface PartnerRegisterResponse {
  partnerId: string;
  referralCode: string;
  status: "ACTIVE";
  rank: {
    code: string;
    name: string;
    level: number;
    personalSalesRate: number;
    passiveIncomeRate: number;
  };
  sponsor: {
    id: string;
    name: string;
  } | null;
  createdAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Terms not accepted
401	UNAUTHORIZED	Invalid or expired access token
404	INVALID_REFERRAL_CODE	Sponsor referral code not found
409	ALREADY_PARTNER	User is already registered as partner
403	KYC_REQUIRED	KYC verification required to become partner

Example

Request:

bash

curl -X POST https://api.iwm-platform.com/api/v1/mlm/partner/register \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "referralCode": "ABC123XY",
    "acceptPartnerTerms": true
  }'

Response:

json

{
  "success": true,
  "data": {
    "partnerId": "cc0e8400-e29b-41d4-a716-446655440000",
    "referralCode": "DEF456ZW",
    "status": "ACTIVE",
    "rank": {
      "code": "0",
      "name": "Consultant",
      "level": 0,
      "personalSalesRate": 3.0,
      "passiveIncomeRate": 0.0
    },
    "sponsor": {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith"
    },
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

GET /api/v1/mlm/partner/me

Get current partner profile.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface PartnerProfileResponse {
  id: string;
  userId: string;
  referralCode: string;
  status: "PENDING" | "ACTIVE" | "SUSPENDED" | "TERMINATED";
  currentRank: {
    id: string;
    name: string;
    code: string; // "0", "1", "2", ..., "4_PRO", "5", "5_PRO", ... "11", "11_PRO"
    level: number; // 0-21
    personalSalesRate: number; // 3% - 20%
    passiveIncomeRate: number; // 0% - 20%
    entranceFeeRate: number; // 10.5% - 20%
    badgeUrl: string | null;
  } | null;
  highestRank: {
    id: string;
    name: string;
    code: string;
    level: number;
  } | null;
  sponsor: {
    id: string;
    name: string;
    rank: string | null;
  } | null;
  stats: {
    directReferralsCount: number;
    totalNetworkSize: number;
    maxDepth: number; // Unlimited depth tracking
  };
  isActivated: boolean; // true if Rank 1+ (made $1,100 purchase)
  joinedAt: string;
  activatedAt: string | null;
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/partner/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "id": "cc0e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "referralCode": "DEF456ZW",
    "status": "ACTIVE",
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Consultant 5",
      "code": "5",
      "level": 9,
      "personalSalesRate": 14.0,
      "passiveIncomeRate": 14.0,
      "entranceFeeRate": 13.5,
      "badgeUrl": "https://cdn.iwm-platform.com/badges/rank-5.png"
    },
    "highestRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Consultant 5",
      "code": "5",
      "level": 9
    },
    "sponsor": {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith",
      "rank": "Consultant 6"
    },
    "stats": {
      "directReferralsCount": 15,
      "totalNetworkSize": 87,
      "maxDepth": 7
    },
    "isActivated": true,
    "joinedAt": "2024-01-15T10:00:00Z",
    "activatedAt": "2024-01-15T10:00:00Z"
  }
}

PATCH /api/v1/mlm/partner/me

Update partner profile.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

typescript

interface UpdatePartnerRequest {
  payoutDetails?: {
    method: "BANK_CARD" | "BANK_TRANSFER" | "CRYPTO";
    cardNumber?: string; // For BANK_CARD
    bankName?: string; // For BANK_TRANSFER
    bankSwift?: string; // For BANK_TRANSFER
    accountNumber?: string; // For BANK_TRANSFER
    cryptoNetwork?: string; // For CRYPTO (e.g., 'USDT_TRC20', 'USDT_ERC20')
    walletAddress?: string; // For CRYPTO
  };
}

Query Parameters

None

Response (200 OK)

typescript

interface UpdatePartnerResponse {
  id: string;
  payoutDetails: {
    method: string;
    maskedDetails: string; // e.g., "**** **** **** 1234" or "TRC20: T***...xyz"
    lastUpdated: string;
  } | null;
  updatedAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid payout details
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X PATCH https://api.iwm-platform.com/api/v1/mlm/partner/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "payoutDetails": {
      "method": "CRYPTO",
      "cryptoNetwork": "USDT_TRC20",
      "walletAddress": "TXyz1234567890abcdefghijklmnop"
    }
  }'

Response:

json

{
  "success": true,
  "data": {
    "id": "cc0e8400-e29b-41d4-a716-446655440000",
    "payoutDetails": {
      "method": "CRYPTO",
      "maskedDetails": "TRC20: TXyz...mnop",
      "lastUpdated": "2024-01-15T16:00:00Z"
    },
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}

GET /api/v1/mlm/partner/network

Get downline network structure (unlimited depth).

Authentication: Required (Partner)

Rate Limit: 50 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
page	number	Page number (optional)
pageSize	number	Items per page, max 100 (optional)
depth	number	Maximum depth level to fetch (optional, no limit)
level	number	Specific level to fetch (optional)
status	string	Filter by status: 'ACTIVE', 'SUSPENDED', 'ALL' (optional)
search	string	Search by name or referral code (optional)

Response (200 OK)

typescript

interface NetworkResponse {
  partners: NetworkPartner[];
  summary: {
    totalCount: number;
    byLevel: {
      level: number;
      count: number;
    }[];
  };
}

interface NetworkPartner {
  id: string;
  name: string;
  referralCode: string;
  depth: number; // Depth from current partner (unlimited)
  status: string;
  rank: {
    name: string;
    code: string;
    level: number;
  } | null;
  directReferralsCount: number;
  joinedAt: string;
  lastActiveAt: string | null;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid query parameters
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/partner/network?depth=5&page=1&pageSize=20" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "partners": [
      {
        "id": "ff0e8400-e29b-41d4-a716-446655440001",
        "name": "Alice Johnson",
        "referralCode": "ALI789AB",
        "depth": 1,
        "status": "ACTIVE",
        "rank": {
          "name": "Consultant 3",
          "code": "3",
          "level": 4
        },
        "directReferralsCount": 5,
        "joinedAt": "2024-01-20T14:00:00Z",
        "lastActiveAt": "2024-01-25T10:30:00Z"
      },
      {
        "id": "ff0e8400-e29b-41d4-a716-446655440002",
        "name": "Bob Williams",
        "referralCode": "BOB456CD",
        "depth": 2,
        "status": "ACTIVE",
        "rank": {
          "name": "Consultant 1",
          "code": "1",
          "level": 2
        },
        "directReferralsCount": 2,
        "joinedAt": "2024-01-22T09:00:00Z",
        "lastActiveAt": "2024-01-24T16:45:00Z"
      }
    ],
    "summary": {
      "totalCount": 87,
      "byLevel": [
        { "level": 1, "count": 15 },
        { "level": 2, "count": 32 },
        { "level": 3, "count": 25 },
        { "level": 4, "count": 10 },
        { "level": 5, "count": 5 }
      ]
    }
  },
  "meta": {
    "pagination": {
      "total": 87,
      "page": 1,
      "pageSize": 20,
      "totalPages": 5,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

GET /api/v1/mlm/partner/network/stats

Get network statistics.

Authentication: Required (Partner)

Rate Limit: 50 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
period	string	Time period: 'DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR', 'ALL' (optional)

Response (200 OK)

typescript

interface NetworkStatsResponse {
  period: string;
  periodStart: string;
  periodEnd: string;
  overview: {
    totalPartners: number;
    activePartners: number;
    newPartnersInPeriod: number;
    totalVolumeUsd: number;
    personalVolumeUsd: number;
    groupVolumeUsd: number;
  };
  growth: {
    date: string;
    newPartners: number;
    volumeUsd: number;
  }[];
  topPerformers: {
    id: string;
    name: string;
    volumeUsd: number;
    referrals: number;
  }[];
  rankDistribution: {
    rankCode: string;
    rankName: string;
    count: number;
    percentage: number;
  }[];
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid period
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/partner/network/stats?period=MONTH" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "period": "MONTH",
    "periodStart": "2024-01-01T00:00:00Z",
    "periodEnd": "2024-01-31T23:59:59Z",
    "overview": {
      "totalPartners": 87,
      "activePartners": 65,
      "newPartnersInPeriod": 12,
      "totalVolumeUsd": 125000.0,
      "personalVolumeUsd": 15000.0,
      "groupVolumeUsd": 110000.0
    },
    "growth": [
      { "date": "2024-01-01", "newPartners": 2, "volumeUsd": 4500.0 },
      { "date": "2024-01-08", "newPartners": 3, "volumeUsd": 6200.0 },
      { "date": "2024-01-15", "newPartners": 4, "volumeUsd": 7800.0 },
      { "date": "2024-01-22", "newPartners": 3, "volumeUsd": 5500.0 }
    ],
    "topPerformers": [
      {
        "id": "ff0e8400-e29b-41d4-a716-446655440001",
        "name": "Alice Johnson",
        "volumeUsd": 25000.0,
        "referrals": 8
      },
      {
        "id": "ff0e8400-e29b-41d4-a716-446655440002",
        "name": "Bob Williams",
        "volumeUsd": 18000.0,
        "referrals": 5
      }
    ],
    "rankDistribution": [
      {
        "rankCode": "0",
        "rankName": "Consultant 0",
        "count": 25,
        "percentage": 28.74
      },
      {
        "rankCode": "1",
        "rankName": "Consultant 1",
        "count": 20,
        "percentage": 22.99
      },
      {
        "rankCode": "2",
        "rankName": "Consultant 2",
        "count": 15,
        "percentage": 17.24
      },
      {
        "rankCode": "3",
        "rankName": "Consultant 3",
        "count": 12,
        "percentage": 13.79
      },
      {
        "rankCode": "4",
        "rankName": "Consultant 4",
        "count": 8,
        "percentage": 9.2
      },
      {
        "rankCode": "5",
        "rankName": "Consultant 5",
        "count": 5,
        "percentage": 5.75
      },
      {
        "rankCode": "6",
        "rankName": "Consultant 6",
        "count": 2,
        "percentage": 2.3
      }
    ]
  }
}

Referral Links Endpoints

GET /api/v1/mlm/referrals/links

List all referral links.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
page	number	Page number (optional)
pageSize	number	Items per page, max 50 (optional)
status	string	Filter: 'ACTIVE', 'EXPIRED', 'ALL' (optional)

Response (200 OK)

typescript

interface ReferralLinksResponse {
  links: ReferralLink[];
  defaultLink: string;
}

interface ReferralLink {
  id: string;
  code: string;
  name: string | null;
  fullUrl: string;
  targetUrl: string | null;
  utmParams: {
    source: string | null;
    medium: string | null;
    campaign: string | null;
  };
  stats: {
    clicks: number;
    registrations: number;
    conversions: number;
  };
  isActive: boolean;
  expiresAt: string | null;
  createdAt: string;
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/referrals/links?status=ACTIVE" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "gg0e8400-e29b-41d4-a716-446655440001",
        "code": "DEF456ZW-IG",
        "name": "Instagram Bio",
        "fullUrl": "https://iwm-platform.com/ref/DEF456ZW-IG",
        "targetUrl": null,
        "utmParams": {
          "source": "instagram",
          "medium": "social",
          "campaign": "bio_link"
        },
        "stats": {
          "clicks": 1250,
          "registrations": 45,
          "conversions": 12
        },
        "isActive": true,
        "expiresAt": null,
        "createdAt": "2024-01-10T14:00:00Z"
      }
    ],
    "defaultLink": "https://iwm-platform.com/ref/DEF456ZW"
  },
  "meta": {
    "pagination": {
      "total": 5,
      "page": 1,
      "pageSize": 20,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

POST /api/v1/mlm/referrals/links

Create a new referral link.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

typescript

interface CreateReferralLinkRequest {
  name: string; // Descriptive name (e.g., "YouTube Channel")
  targetUrl?: string; // Specific landing page URL
  utmSource?: string; // UTM source parameter
  utmMedium?: string; // UTM medium parameter
  utmCampaign?: string; // UTM campaign parameter
  expiresAt?: string; // Optional expiration date (ISO 8601)
}

Query Parameters

None

Response (201 Created)

typescript

interface CreateReferralLinkResponse {
  id: string;
  code: string;
  name: string;
  fullUrl: string;
  targetUrl: string | null;
  utmParams: {
    source: string | null;
    medium: string | null;
    campaign: string | null;
  };
  isActive: boolean;
  expiresAt: string | null;
  createdAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid input data
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner
400	MAX_LINKS_REACHED	Maximum 20 referral links allowed

Example

Request:

bash

curl -X POST https://api.iwm-platform.com/api/v1/mlm/referrals/links \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "YouTube Channel",
    "utmSource": "youtube",
    "utmMedium": "video",
    "utmCampaign": "tutorial_series"
  }'

Response:

json

{
  "success": true,
  "data": {
    "id": "hh0e8400-e29b-41d4-a716-446655440001",
    "code": "DEF456ZW-YT",
    "name": "YouTube Channel",
    "fullUrl": "https://iwm-platform.com/ref/DEF456ZW-YT",
    "targetUrl": null,
    "utmParams": {
      "source": "youtube",
      "medium": "video",
      "campaign": "tutorial_series"
    },
    "isActive": true,
    "expiresAt": null,
    "createdAt": "2024-01-15T17:00:00Z"
  }
}

GET /api/v1/mlm/referrals/links/:id/stats

Get detailed statistics for a referral link.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Path Parameters

Parameter	Type	Description
id	string (UUID)	Referral link ID

Request Body

None

Query Parameters

Parameter	Type	Description
period	string	Time period: 'DAY', 'WEEK', 'MONTH', 'ALL' (optional)

Response (200 OK)

typescript

interface LinkStatsResponse {
  linkId: string;
  linkCode: string;
  period: string;
  periodStart: string;
  periodEnd: string;
  totals: {
    clicks: number;
    uniqueVisitors: number;
    registrations: number;
    conversions: number;
    conversionRate: number;
    totalRevenueUsd: number;
    totalCommissionsUsd: number;
  };
  timeline: {
    date: string;
    clicks: number;
    registrations: number;
    conversions: number;
  }[];
  topReferrals: {
    userId: string;
    name: string;
    status: string;
    registeredAt: string;
    totalPurchasesUsd: number;
  }[];
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid period
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner
404	LINK_NOT_FOUND	Referral link not found

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/referrals/links/gg0e8400-e29b-41d4-a716-446655440001/stats?period=MONTH" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "linkId": "gg0e8400-e29b-41d4-a716-446655440001",
    "linkCode": "DEF456ZW-IG",
    "period": "MONTH",
    "periodStart": "2024-01-01T00:00:00Z",
    "periodEnd": "2024-01-31T23:59:59Z",
    "totals": {
      "clicks": 1250,
      "uniqueVisitors": 980,
      "registrations": 45,
      "conversions": 12,
      "conversionRate": 26.67,
      "totalRevenueUsd": 45000.0,
      "totalCommissionsUsd": 4500.0
    },
    "timeline": [
      {
        "date": "2024-01-01",
        "clicks": 45,
        "registrations": 2,
        "conversions": 0
      },
      {
        "date": "2024-01-02",
        "clicks": 62,
        "registrations": 3,
        "conversions": 1
      }
    ],
    "topReferrals": [
      {
        "userId": "ii0e8400-e29b-41d4-a716-446655440001",
        "name": "Carol Davis",
        "status": "ACTIVE",
        "registeredAt": "2024-01-05T10:00:00Z",
        "totalPurchasesUsd": 15000.0
      }
    ]
  }
}

DELETE /api/v1/mlm/referrals/links/:id

Delete a referral link.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Path Parameters

Parameter	Type	Description
id	string (UUID)	Referral link ID

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface DeleteLinkResponse {
  message: string;
  linkId: string;
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner
404	LINK_NOT_FOUND	Referral link not found
400	CANNOT_DELETE_DEFAULT	Cannot delete the default referral link

Example

Request:

bash

curl -X DELETE https://api.iwm-platform.com/api/v1/mlm/referrals/links/hh0e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "message": "Referral link deleted successfully",
    "linkId": "hh0e8400-e29b-41d4-a716-446655440001"
  }
}

Commission Endpoints

GET /api/v1/mlm/commissions

List commission transactions with 7 income types.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
page	number	Page number (optional)
pageSize	number	Items per page, max 100 (optional)
status	string	Filter: 'PENDING', 'APPROVED', 'PAID', 'REVERSED', 'ALL' (optional)
incomeType	string	Filter: 'PERSONAL_SALES', 'TEAM_SALES', 'REPEAT_SALES', 'PORTFOLIO_RETURNS', 'CLIENT_PROFITS', 'NETWORK_PROFITS', 'LEADERSHIP_POOL' (optional)
sourceType	string	Filter: 'ORDER', 'INVESTMENT', 'INVESTMENT_PROFIT', 'POOL_DISTRIBUTION' (optional)
dateFrom	string	Start date (ISO 8601) (optional)
dateTo	string	End date (ISO 8601) (optional)

Response (200 OK)

typescript

interface CommissionsResponse {
  commissions: Commission[];
}

interface Commission {
  id: string;
  incomeType:
    | "PERSONAL_SALES"
    | "TEAM_SALES"
    | "REPEAT_SALES"
    | "PORTFOLIO_RETURNS"
    | "CLIENT_PROFITS"
    | "NETWORK_PROFITS"
    | "LEADERSHIP_POOL";
  sourceType:
    | "ORDER"
    | "INVESTMENT"
    | "INVESTMENT_PROFIT"
    | "POOL_DISTRIBUTION"
    | "CLAWBACK";
  sourceId: string;
  sourcePartner: {
    id: string;
    name: string;
    rank: string;
  } | null;
  // Differential commission details
  ownRate: number; // Your rate (e.g., 14%)
  sourceRate: number; // Source partner's rate (e.g., 8%)
  differentialRate: number; // Difference (e.g., 6%)
  baseAmountUsd: number; // Amount the commission is calculated on
  grossAmountUsd: number;
  netAmountUsd: number;
  currency: string; // Always 'USD'
  status:
    | "PENDING"
    | "APPROVED"
    | "PAID"
    | "HELD"
    | "REVERSED"
    | "CLAWBACK"
    | "CANCELLED";
  periodId: string | null;
  processedAt: string | null;
  createdAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid query parameters
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/commissions?status=APPROVED&incomeType=TEAM_SALES&page=1&pageSize=20" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "commissions": [
      {
        "id": "jj0e8400-e29b-41d4-a716-446655440001",
        "incomeType": "TEAM_SALES",
        "sourceType": "ORDER",
        "sourceId": "kk0e8400-e29b-41d4-a716-446655440001",
        "sourcePartner": {
          "id": "ff0e8400-e29b-41d4-a716-446655440001",
          "name": "Alice Johnson",
          "rank": "Consultant 3"
        },
        "ownRate": 14.0,
        "sourceRate": 10.0,
        "differentialRate": 4.0,
        "baseAmountUsd": 5000.0,
        "grossAmountUsd": 200.0,
        "netAmountUsd": 200.0,
        "currency": "USD",
        "status": "APPROVED",
        "periodId": "2024-01",
        "processedAt": "2024-01-16T09:00:00Z",
        "createdAt": "2024-01-15T18:00:00Z"
      },
      {
        "id": "jj0e8400-e29b-41d4-a716-446655440002",
        "incomeType": "PERSONAL_SALES",
        "sourceType": "ORDER",
        "sourceId": "kk0e8400-e29b-41d4-a716-446655440002",
        "sourcePartner": null,
        "ownRate": 14.0,
        "sourceRate": 0,
        "differentialRate": 14.0,
        "baseAmountUsd": 3000.0,
        "grossAmountUsd": 420.0,
        "netAmountUsd": 420.0,
        "currency": "USD",
        "status": "APPROVED",
        "periodId": "2024-01",
        "processedAt": "2024-01-16T09:00:00Z",
        "createdAt": "2024-01-15T14:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 156,
      "page": 1,
      "pageSize": 20,
      "totalPages": 8,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

GET /api/v1/mlm/commissions/summary

Get commission summary by period with breakdown by 7 income types.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
period	string	Time period: 'DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR', 'ALL' (optional)

Response (200 OK)

typescript

interface CommissionSummaryResponse {
  period: string;
  periodStart: string;
  periodEnd: string;
  totals: {
    grossEarnedUsd: number;
    netEarnedUsd: number;
    pendingUsd: number;
    approvedUsd: number;
    paidUsd: number;
    reversedUsd: number;
  };
  byIncomeType: {
    incomeType: string;
    incomeTypeName: string;
    count: number;
    totalUsd: number;
  }[];
  bySource: {
    sourceType: string;
    count: number;
    totalUsd: number;
  }[];
  trend: {
    date: string;
    earnedUsd: number;
  }[];
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid period
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/commissions/summary?period=MONTH" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "period": "MONTH",
    "periodStart": "2024-01-01T00:00:00Z",
    "periodEnd": "2024-01-31T23:59:59Z",
    "totals": {
      "grossEarnedUsd": 12500.0,
      "netEarnedUsd": 12500.0,
      "pendingUsd": 1500.0,
      "approvedUsd": 5000.0,
      "paidUsd": 6000.0,
      "reversedUsd": 0.0
    },
    "byIncomeType": [
      {
        "incomeType": "PERSONAL_SALES",
        "incomeTypeName": "Personal Sales",
        "count": 15,
        "totalUsd": 4200.0
      },
      {
        "incomeType": "TEAM_SALES",
        "incomeTypeName": "Team Sales",
        "count": 45,
        "totalUsd": 3600.0
      },
      {
        "incomeType": "REPEAT_SALES",
        "incomeTypeName": "Repeat Sales",
        "count": 8,
        "totalUsd": 800.0
      },
      {
        "incomeType": "CLIENT_PROFITS",
        "incomeTypeName": "Client Profits",
        "count": 12,
        "totalUsd": 1400.0
      },
      {
        "incomeType": "NETWORK_PROFITS",
        "incomeTypeName": "Network Profits",
        "count": 30,
        "totalUsd": 1800.0
      },
      {
        "incomeType": "LEADERSHIP_POOL",
        "incomeTypeName": "Leadership Pool",
        "count": 4,
        "totalUsd": 700.0
      }
    ],
    "bySource": [
      { "sourceType": "ORDER", "count": 68, "totalUsd": 8600.0 },
      { "sourceType": "INVESTMENT", "count": 12, "totalUsd": 2000.0 },
      { "sourceType": "INVESTMENT_PROFIT", "count": 42, "totalUsd": 1200.0 },
      { "sourceType": "POOL_DISTRIBUTION", "count": 4, "totalUsd": 700.0 }
    ],
    "trend": [
      { "date": "2024-01-01", "earnedUsd": 450.0 },
      { "date": "2024-01-02", "earnedUsd": 320.0 }
    ]
  }
}

Rank Endpoints

GET /api/v1/mlm/ranks

Get all available ranks.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface RanksListResponse {
  ranks: Rank[];
}

interface Rank {
  id: string;
  code: string; // "0", "1", ..., "4_PRO", "5", "5_PRO", ..., "11", "11_PRO"
  name: string; // "Consultant 0", "Consultant 1", ..., "Consultant 11 PRO"
  level: number; // 0-21
  personalSalesRate: number; // 3% - 20%
  entranceFeeRate: number; // 10.5% - 20%
  passiveIncomeRate: number; // 0% - 20%
  requirements: {
    personalVolumeUsd: number;
    groupVolumeUsd: number | null;
    directReferrals: number | null;
    rankedPartnersRequired: number | null;
    rankedPartnerRank: string | null;
  };
  eligibleForPools: string[]; // ["POOL_5", "POOL_6"] etc.
  badgeUrl: string | null;
  colorCode: string | null;
}

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/ranks \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "ranks": [
      {
        "id": "ee0e8400-e29b-41d4-a716-446655440000",
        "code": "0",
        "name": "Consultant 0",
        "level": 0,
        "personalSalesRate": 3.0,
        "entranceFeeRate": 10.5,
        "passiveIncomeRate": 0.0,
        "requirements": {
          "personalVolumeUsd": 0,
          "groupVolumeUsd": null,
          "directReferrals": null,
          "rankedPartnersRequired": null,
          "rankedPartnerRank": null
        },
        "eligibleForPools": [],
        "badgeUrl": "https://cdn.iwm-platform.com/badges/rank-0.png",
        "colorCode": "#808080"
      },
      {
        "id": "ee0e8400-e29b-41d4-a716-446655440001",
        "code": "1",
        "name": "Consultant 1",
        "level": 1,
        "personalSalesRate": 5.0,
        "entranceFeeRate": 11.0,
        "passiveIncomeRate": 5.0,
        "requirements": {
          "personalVolumeUsd": 1100,
          "groupVolumeUsd": null,
          "directReferrals": null,
          "rankedPartnersRequired": null,
          "rankedPartnerRank": null
        },
        "eligibleForPools": [],
        "badgeUrl": "https://cdn.iwm-platform.com/badges/rank-1.png",
        "colorCode": "#4A90D9"
      },
      {
        "id": "ee0e8400-e29b-41d4-a716-446655440005",
        "code": "5",
        "name": "Consultant 5",
        "level": 9,
        "personalSalesRate": 14.0,
        "entranceFeeRate": 13.5,
        "passiveIncomeRate": 14.0,
        "requirements": {
          "personalVolumeUsd": 5500,
          "groupVolumeUsd": 165000,
          "directReferrals": 5,
          "rankedPartnersRequired": 2,
          "rankedPartnerRank": "4"
        },
        "eligibleForPools": ["POOL_5"],
        "badgeUrl": "https://cdn.iwm-platform.com/badges/rank-5.png",
        "colorCode": "#FFD700"
      }
    ]
  }
}

GET /api/v1/mlm/ranks/current

Get current rank details.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface CurrentRankResponse {
  currentRank: {
    id: string;
    name: string;
    code: string;
    level: number;
    description: string | null;
    badgeUrl: string | null;
    colorCode: string | null;
  } | null;
  achievedAt: string | null;
  rates: {
    personalSalesRate: number;
    entranceFeeRate: number;
    passiveIncomeRate: number;
  };
  eligibleForPools: string[];
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/ranks/current \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440005",
      "name": "Consultant 5",
      "code": "5",
      "level": 9,
      "description": "Qualified for weekly leadership pool with 50% branch rule",
      "badgeUrl": "https://cdn.iwm-platform.com/badges/rank-5.png",
      "colorCode": "#FFD700"
    },
    "achievedAt": "2024-01-10T14:30:00Z",
    "rates": {
      "personalSalesRate": 14.0,
      "entranceFeeRate": 13.5,
      "passiveIncomeRate": 14.0
    },
    "eligibleForPools": ["POOL_5"]
  }
}

GET /api/v1/mlm/ranks/progress

Get progression toward next rank.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface RankProgressResponse {
  currentRank: {
    id: string;
    name: string;
    code: string;
    level: number;
  } | null;
  nextRank: {
    id: string;
    name: string;
    code: string;
    level: number;
    badgeUrl: string | null;
    newRates: {
      personalSalesRate: number;
      entranceFeeRate: number;
      passiveIncomeRate: number;
    };
  } | null;
  requirements: {
    type: string;
    description: string;
    currentUsd: number;
    requiredUsd: number;
    percentage: number;
    isMet: boolean;
  }[];
  overallProgress: number;
  isMaxRank: boolean;
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/ranks/progress \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440005",
      "name": "Consultant 5",
      "code": "5",
      "level": 9
    },
    "nextRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440006",
      "name": "Consultant 5 PRO",
      "code": "5_PRO",
      "level": 10,
      "badgeUrl": "https://cdn.iwm-platform.com/badges/rank-5-pro.png",
      "newRates": {
        "personalSalesRate": 15.0,
        "entranceFeeRate": 14.0,
        "passiveIncomeRate": 15.0
      }
    },
    "requirements": [
      {
        "type": "PERSONAL_VOLUME",
        "description": "Personal volume required",
        "currentUsd": 8000.0,
        "requiredUsd": 11000.0,
        "percentage": 72.73,
        "isMet": false
      },
      {
        "type": "GROUP_VOLUME",
        "description": "Group volume required",
        "currentUsd": 280000.0,
        "requiredUsd": 330000.0,
        "percentage": 84.85,
        "isMet": false
      },
      {
        "type": "DIRECT_REFERRALS",
        "description": "Direct referrals required",
        "currentUsd": 5,
        "requiredUsd": 5,
        "percentage": 100.0,
        "isMet": true
      },
      {
        "type": "RANKED_PARTNERS",
        "description": "Partners at Rank 4 or higher",
        "currentUsd": 2,
        "requiredUsd": 3,
        "percentage": 66.67,
        "isMet": false
      }
    ],
    "overallProgress": 80.81,
    "isMaxRank": false
  }
}

GET /api/v1/mlm/ranks/history

Get rank advancement history. Ranks in IWM Platform are non-expiring (no demotion).

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
page	number	Page number (optional)
pageSize	number	Items per page, max 50 (optional)

Response (200 OK)

typescript

interface RankHistoryResponse {
  history: RankChange[];
}

interface RankChange {
  id: string;
  fromRank: {
    name: string;
    code: string;
    level: number;
  } | null;
  toRank: {
    name: string;
    code: string;
    level: number;
  };
  changeType: "PROMOTION" | "INITIAL"; // No DEMOTION - ranks don't expire
  qualificationSnapshot: {
    personalVolumeUsd: number;
    groupVolumeUsd: number;
    directReferrals: number;
    rankedPartners: number;
  };
  createdAt: string;
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/ranks/history?page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440002",
        "fromRank": {
          "name": "Consultant 4",
          "code": "4",
          "level": 6
        },
        "toRank": {
          "name": "Consultant 5",
          "code": "5",
          "level": 9
        },
        "changeType": "PROMOTION",
        "qualificationSnapshot": {
          "personalVolumeUsd": 5500.0,
          "groupVolumeUsd": 165000.0,
          "directReferrals": 5,
          "rankedPartners": 2
        },
        "createdAt": "2024-01-10T14:30:00Z"
      },
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440001",
        "fromRank": {
          "name": "Consultant 3",
          "code": "3",
          "level": 4
        },
        "toRank": {
          "name": "Consultant 4",
          "code": "4",
          "level": 6
        },
        "changeType": "PROMOTION",
        "qualificationSnapshot": {
          "personalVolumeUsd": 3300.0,
          "groupVolumeUsd": 55000.0,
          "directReferrals": 3,
          "rankedPartners": 0
        },
        "createdAt": "2023-11-15T10:00:00Z"
      },
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440000",
        "fromRank": null,
        "toRank": {
          "name": "Consultant 0",
          "code": "0",
          "level": 0
        },
        "changeType": "INITIAL",
        "qualificationSnapshot": {
          "personalVolumeUsd": 0,
          "groupVolumeUsd": 0,
          "directReferrals": 0,
          "rankedPartners": 0
        },
        "createdAt": "2023-06-01T09:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 3,
      "page": 1,
      "pageSize": 10,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

Balance and Payout Endpoints

GET /api/v1/mlm/balance

Get balance details with breakdown by 7 income types.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface BalanceResponse {
  availableBalanceUsd: number;
  pendingBalanceUsd: number;
  totalEarnedUsd: number;
  totalWithdrawnUsd: number;
  incomeBreakdown: {
    personalSalesUsd: number;
    teamSalesUsd: number;
    repeatSalesUsd: number;
    portfolioReturnsUsd: number;
    clientProfitsUsd: number;
    networkProfitsUsd: number;
    leadershipPoolUsd: number;
  };
  currency: string; // Always 'USD'
  lastCalculatedAt: string | null;
  minimumPayoutUsd: number; // $100
  canRequestPayout: boolean;
  payoutRestrictions: string[];
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/balance \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "availableBalanceUsd": 4500.0,
    "pendingBalanceUsd": 1500.0,
    "totalEarnedUsd": 18000.0,
    "totalWithdrawnUsd": 12000.0,
    "incomeBreakdown": {
      "personalSalesUsd": 5200.0,
      "teamSalesUsd": 6800.0,
      "repeatSalesUsd": 1200.0,
      "portfolioReturnsUsd": 800.0,
      "clientProfitsUsd": 1800.0,
      "networkProfitsUsd": 1500.0,
      "leadershipPoolUsd": 700.0
    },
    "currency": "USD",
    "lastCalculatedAt": "2024-01-15T23:59:59Z",
    "minimumPayoutUsd": 100.0,
    "canRequestPayout": true,
    "payoutRestrictions": []
  }
}

GET /api/v1/mlm/payouts

List payout requests.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
page	number	Page number (optional)
pageSize	number	Items per page, max 50 (optional)
status	string	Filter: 'PENDING', 'APPROVED', 'PROCESSING', 'COMPLETED', 'REJECTED', 'CANCELLED', 'ALL' (optional)

Response (200 OK)

typescript

interface PayoutsResponse {
  payouts: Payout[];
}

interface Payout {
  id: string;
  amountUsd: number;
  currency: string; // Always 'USD'
  method: {
    type: "BANK_CARD" | "BANK_TRANSFER" | "CRYPTO";
    maskedDetails: string;
  };
  status:
    | "PENDING"
    | "APPROVED"
    | "PROCESSING"
    | "COMPLETED"
    | "REJECTED"
    | "CANCELLED";
  rejectionReason: string | null;
  externalReference: string | null;
  processedAt: string | null;
  completedAt: string | null;
  createdAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid query parameters
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/payouts?status=ALL&page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "payouts": [
      {
        "id": "mm0e8400-e29b-41d4-a716-446655440001",
        "amountUsd": 3000.0,
        "currency": "USD",
        "method": {
          "type": "CRYPTO",
          "maskedDetails": "TRC20: TXyz...mnop"
        },
        "status": "COMPLETED",
        "rejectionReason": null,
        "externalReference": "PAY-2024011501234",
        "processedAt": "2024-01-15T10:00:00Z",
        "completedAt": "2024-01-15T10:05:00Z",
        "createdAt": "2024-01-14T18:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 12,
      "page": 1,
      "pageSize": 10,
      "totalPages": 2,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}

POST /api/v1/mlm/payouts/request

Request a payout (minimum $100 USD).

Authentication: Required (Partner)

Rate Limit: 1 request per minute (financial endpoint)

Request Headers

Authorization: Bearer <access_token>

Request Body

typescript

interface PayoutRequestBody {
  amountUsd: number; // Must be >= $100
  methodType: "BANK_CARD" | "BANK_TRANSFER" | "CRYPTO";
  // Use saved payout details or provide new ones
  useSavedDetails?: boolean; // Use saved payout details
  // Or provide details explicitly:
  details?: {
    cardNumber?: string; // For BANK_CARD
    bankName?: string; // For BANK_TRANSFER
    bankSwift?: string; // For BANK_TRANSFER
    accountNumber?: string; // For BANK_TRANSFER
    cryptoNetwork?: string; // For CRYPTO (e.g., 'USDT_TRC20')
    walletAddress?: string; // For CRYPTO
  };
}

Query Parameters

None

Response (201 Created)

typescript

interface PayoutRequestResponse {
  payoutId: string;
  amountUsd: number;
  currency: string;
  method: {
    type: string;
    maskedDetails: string;
  };
  status: "PENDING";
  estimatedProcessingTime: string;
  newAvailableBalanceUsd: number;
  createdAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid input data
400	AMOUNT_BELOW_MINIMUM	Amount below $100 minimum payout
400	INSUFFICIENT_BALANCE	Not enough available balance
400	PAYOUT_DETAILS_REQUIRED	Payout details not provided and none saved
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner
403	KYC_REQUIRED	KYC verification required for payouts
409	PAYOUT_ALREADY_PENDING	A payout request is already pending
429	RATE_LIMIT_EXCEEDED	Too many payout requests

Example

Request:

bash

curl -X POST https://api.iwm-platform.com/api/v1/mlm/payouts/request \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsd": 2500.00,
    "methodType": "CRYPTO",
    "useSavedDetails": true
  }'

Response:

json

{
  "success": true,
  "data": {
    "payoutId": "nn0e8400-e29b-41d4-a716-446655440001",
    "amountUsd": 2500.0,
    "currency": "USD",
    "method": {
      "type": "CRYPTO",
      "maskedDetails": "TRC20: TXyz...mnop"
    },
    "status": "PENDING",
    "estimatedProcessingTime": "1-3 business days",
    "newAvailableBalanceUsd": 2000.0,
    "createdAt": "2024-01-15T19:00:00Z"
  }
}

GET /api/v1/mlm/payouts/:id

Get payout details.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Path Parameters

Parameter	Type	Description
id	string (UUID)	Payout request ID

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface PayoutDetailsResponse {
  id: string;
  amountUsd: number;
  currency: string;
  method: {
    type: "BANK_CARD" | "BANK_TRANSFER" | "CRYPTO";
    maskedDetails: string;
  };
  status:
    | "PENDING"
    | "APPROVED"
    | "PROCESSING"
    | "COMPLETED"
    | "REJECTED"
    | "CANCELLED";
  statusHistory: {
    status: string;
    changedAt: string;
    changedBy: string | null;
    note: string | null;
  }[];
  rejectionReason: string | null;
  externalReference: string | null;
  processedBy: string | null;
  processedAt: string | null;
  completedAt: string | null;
  createdAt: string;
}

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or expired access token
403	NOT_A_PARTNER	User is not registered as partner
404	PAYOUT_NOT_FOUND	Payout request not found

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/payouts/mm0e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "id": "mm0e8400-e29b-41d4-a716-446655440001",
    "amountUsd": 3000.0,
    "currency": "USD",
    "method": {
      "type": "CRYPTO",
      "maskedDetails": "TRC20: TXyz...mnop"
    },
    "status": "COMPLETED",
    "statusHistory": [
      {
        "status": "PENDING",
        "changedAt": "2024-01-14T18:00:00Z",
        "changedBy": null,
        "note": "Payout request created"
      },
      {
        "status": "APPROVED",
        "changedAt": "2024-01-15T09:00:00Z",
        "changedBy": "Admin User",
        "note": "Approved for processing"
      },
      {
        "status": "PROCESSING",
        "changedAt": "2024-01-15T10:00:00Z",
        "changedBy": "System",
        "note": "Sent to payment processor"
      },
      {
        "status": "COMPLETED",
        "changedAt": "2024-01-15T10:05:00Z",
        "changedBy": "System",
        "note": "Payment confirmed"
      }
    ],
    "rejectionReason": null,
    "externalReference": "PAY-2024011501234",
    "processedBy": "Admin User",
    "processedAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:05:00Z",
    "createdAt": "2024-01-14T18:00:00Z"
  }
}

Leadership Pool Endpoints

GET /api/v1/mlm/pools

Get all leadership pools configuration.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

None

Response (200 OK)

typescript

interface PoolsListResponse {
  pools: LeadershipPool[];
}

interface LeadershipPool {
  id: string;
  code: string; // "POOL_5", "POOL_6", etc.
  name: string;
  eligibleRanks: string[]; // ["5", "5_PRO"]
  percentageOfTurnover: number; // 0.5% - 1%
  frequency: "WEEKLY" | "MONTHLY";
  qualificationVolumes: {
    rankCode: string;
    requiredVolumeUsd: number;
  }[];
  branchCapPercentage: number; // 50% branch rule
  isActive: boolean;
}

Example

Request:

bash

curl -X GET https://api.iwm-platform.com/api/v1/mlm/pools \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "pools": [
      {
        "id": "pp0e8400-e29b-41d4-a716-446655440001",
        "code": "POOL_5",
        "name": "Pool 5 (Weekly)",
        "eligibleRanks": ["5", "5_PRO"],
        "percentageOfTurnover": 1.0,
        "frequency": "WEEKLY",
        "qualificationVolumes": [
          { "rankCode": "5", "requiredVolumeUsd": 5000.0 },
          { "rankCode": "5_PRO", "requiredVolumeUsd": 10000.0 }
        ],
        "branchCapPercentage": 50,
        "isActive": true
      },
      {
        "id": "pp0e8400-e29b-41d4-a716-446655440002",
        "code": "POOL_6",
        "name": "Pool 6 (Weekly)",
        "eligibleRanks": ["6", "6_PRO"],
        "percentageOfTurnover": 0.5,
        "frequency": "WEEKLY",
        "qualificationVolumes": [
          { "rankCode": "6", "requiredVolumeUsd": 20000.0 },
          { "rankCode": "6_PRO", "requiredVolumeUsd": 30000.0 }
        ],
        "branchCapPercentage": 50,
        "isActive": true
      },
      {
        "id": "pp0e8400-e29b-41d4-a716-446655440007",
        "code": "POOL_9",
        "name": "Pool 9 (Monthly)",
        "eligibleRanks": ["9", "9_PRO"],
        "percentageOfTurnover": 1.0,
        "frequency": "MONTHLY",
        "qualificationVolumes": [
          { "rankCode": "9", "requiredVolumeUsd": 0 },
          { "rankCode": "9_PRO", "requiredVolumeUsd": 0 }
        ],
        "branchCapPercentage": 50,
        "isActive": true
      }
    ]
  }
}

GET /api/v1/mlm/pools/qualification

Get current qualification status for leadership pools.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
period	string	Period to check: 'CURRENT_WEEK', 'LAST_WEEK', 'CURRENT_MONTH', 'LAST_MONTH' (optional)

Response (200 OK)

typescript

interface PoolQualificationResponse {
  currentRank: {
    code: string;
    name: string;
  };
  eligiblePools: string[];
  qualificationStatus: {
    poolCode: string;
    poolName: string;
    isQualified: boolean;
    requiredVolumeUsd: number;
    currentVolumeUsd: number;
    cappedVolumeUsd: number; // After 50% branch cap applied
    percentage: number;
    branchVolumes: {
      branchPartnerId: string;
      branchPartnerName: string;
      rawVolumeUsd: number;
      cappedVolumeUsd: number;
      capApplied: boolean;
    }[];
  }[];
}

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/pools/qualification?period=CURRENT_WEEK" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "currentRank": {
      "code": "5",
      "name": "Consultant 5"
    },
    "eligiblePools": ["POOL_5"],
    "qualificationStatus": [
      {
        "poolCode": "POOL_5",
        "poolName": "Pool 5 (Weekly)",
        "isQualified": true,
        "requiredVolumeUsd": 5000.0,
        "currentVolumeUsd": 12000.0,
        "cappedVolumeUsd": 6500.0,
        "percentage": 130.0,
        "branchVolumes": [
          {
            "branchPartnerId": "ff0e8400-e29b-41d4-a716-446655440001",
            "branchPartnerName": "Alice Johnson",
            "rawVolumeUsd": 8000.0,
            "cappedVolumeUsd": 2500.0,
            "capApplied": true
          },
          {
            "branchPartnerId": "ff0e8400-e29b-41d4-a716-446655440002",
            "branchPartnerName": "Bob Williams",
            "rawVolumeUsd": 4000.0,
            "cappedVolumeUsd": 4000.0,
            "capApplied": false
          }
        ]
      }
    ]
  }
}

GET /api/v1/mlm/pools/distributions

Get leadership pool distribution history.

Authentication: Required (Partner)

Rate Limit: 100 requests per minute

Request Headers

Authorization: Bearer <access_token>

Request Body

None

Query Parameters

Parameter	Type	Description
page	number	Page number (optional)
pageSize	number	Items per page, max 50 (optional)
poolCode	string	Filter by pool: 'POOL_5', 'POOL_6', etc. (optional)

Response (200 OK)

typescript

interface PoolDistributionsResponse {
  distributions: PoolDistribution[];
}

interface PoolDistribution {
  id: string;
  poolCode: string;
  poolName: string;
  periodStart: string;
  periodEnd: string;
  totalTurnoverUsd: number;
  poolAmountUsd: number;
  qualifiedParticipants: number;
  perPersonAmountUsd: number;
  yourParticipation: {
    qualified: boolean;
    qualificationVolumeUsd: number;
    amountReceivedUsd: number;
  } | null;
  distributedAt: string;
}

Example

Request:

bash

curl -X GET "https://api.iwm-platform.com/api/v1/mlm/pools/distributions?poolCode=POOL_5&page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "distributions": [
      {
        "id": "qq0e8400-e29b-41d4-a716-446655440001",
        "poolCode": "POOL_5",
        "poolName": "Pool 5 (Weekly)",
        "periodStart": "2024-01-08T00:00:00Z",
        "periodEnd": "2024-01-14T23:59:59Z",
        "totalTurnoverUsd": 500000.0,
        "poolAmountUsd": 5000.0,
        "qualifiedParticipants": 25,
        "perPersonAmountUsd": 200.0,
        "yourParticipation": {
          "qualified": true,
          "qualificationVolumeUsd": 6500.0,
          "amountReceivedUsd": 200.0
        },
        "distributedAt": "2024-01-14T23:00:00Z"
      },
      {
        "id": "qq0e8400-e29b-41d4-a716-446655440000",
        "poolCode": "POOL_5",
        "poolName": "Pool 5 (Weekly)",
        "periodStart": "2024-01-01T00:00:00Z",
        "periodEnd": "2024-01-07T23:59:59Z",
        "totalTurnoverUsd": 450000.0,
        "poolAmountUsd": 4500.0,
        "qualifiedParticipants": 22,
        "perPersonAmountUsd": 204.55,
        "yourParticipation": {
          "qualified": false,
          "qualificationVolumeUsd": 4200.0,
          "amountReceivedUsd": 0
        },
        "distributedAt": "2024-01-07T23:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 8,
      "page": 1,
      "pageSize": 10,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

MLM API ​

Common Information ​

Base URL ​

Authentication Header ​

Response Envelope ​

Pagination Format ​

Rate Limits ​

Financial Endpoint Rate Limit Headers ​

Partner Endpoints ​

POST /api/v1/mlm/partner/register ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (201 Created) ​

Error Responses ​

Example ​

GET /api/v1/mlm/partner/me ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

PATCH /api/v1/mlm/partner/me ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

GET /api/v1/mlm/partner/network ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

GET /api/v1/mlm/partner/network/stats ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

Referral Links Endpoints ​

GET /api/v1/mlm/referrals/links ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

POST /api/v1/mlm/referrals/links ​

Request Headers ​

Request Body ​

Query Parameters ​

Response (201 Created) ​

Error Responses ​

Example ​

GET /api/v1/mlm/referrals/links/:id/stats ​

Request Headers ​

Path Parameters ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

DELETE /api/v1/mlm/referrals/links/:id ​

Request Headers ​

Path Parameters ​

Request Body ​

Query Parameters ​

Response (200 OK) ​

Error Responses ​

Example ​

Commission Endpoints ​

GET /api/v1/mlm/commissions ​

Request Headers ​

Request Body ​

Query Parameters ​

MLM API

Common Information

Base URL

Authentication Header

Response Envelope

Pagination Format

Rate Limits

Financial Endpoint Rate Limit Headers

Partner Endpoints

POST /api/v1/mlm/partner/register

Request Headers

Request Body

Query Parameters

Response (201 Created)

Error Responses

Example

GET /api/v1/mlm/partner/me

Request Headers

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

PATCH /api/v1/mlm/partner/me

Request Headers

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

GET /api/v1/mlm/partner/network

Request Headers

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

GET /api/v1/mlm/partner/network/stats

Request Headers

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

Referral Links Endpoints

GET /api/v1/mlm/referrals/links

Request Headers

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

POST /api/v1/mlm/referrals/links

Request Headers

Request Body

Query Parameters

Response (201 Created)

Error Responses

Example

GET /api/v1/mlm/referrals/links/:id/stats

Request Headers

Path Parameters

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

DELETE /api/v1/mlm/referrals/links/:id

Request Headers

Path Parameters

Request Body

Query Parameters

Response (200 OK)

Error Responses

Example

Commission Endpoints

GET /api/v1/mlm/commissions

Request Headers

Request Body

Query Parameters