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';
  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",
    "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;
    level: number;
    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;
    treeDepth: number;
  };
  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": "Silver Partner",
      "code": "SILVER",
      "level": 2,
      "badgeUrl": "https://cdn.iwm-platform.com/badges/silver.png"
    },
    "highestRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2
    },
    "sponsor": {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "name": "Jane Smith",
      "rank": "Gold Partner"
    },
    "stats": {
      "directReferralsCount": 15,
      "totalNetworkSize": 87,
      "treeDepth": 4
    },
    "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' | 'EWALLET';
    cardNumber?: string;          // For BANK_CARD
    bankName?: string;            // For BANK_TRANSFER
    bankBik?: string;             // For BANK_TRANSFER
    accountNumber?: string;       // For BANK_TRANSFER
    walletType?: string;          // For EWALLET (e.g., 'YOOMONEY', 'QIWI')
    walletId?: string;            // For EWALLET
  };
}

Query Parameters

None

Response (200 OK)

typescript

interface UpdatePartnerResponse {
  id: string;
  payoutDetails: {
    method: string;
    maskedDetails: string;        // e.g., "**** **** **** 1234"
    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": "BANK_CARD",
      "cardNumber": "4111111111111234"
    }
  }'

Response:

json

{
  "success": true,
  "data": {
    "id": "cc0e8400-e29b-41d4-a716-446655440000",
    "payoutDetails": {
      "method": "BANK_CARD",
      "maskedDetails": "**** **** **** 1234",
      "lastUpdated": "2024-01-15T16:00:00Z"
    },
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}

GET /api/v1/mlm/partner/network

Get downline network structure.

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, 1-10 (optional)
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;
  level: number;                  // Depth from current partner
  status: string;
  rank: {
    name: string;
    code: string;
  } | 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=3&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",
        "level": 1,
        "status": "ACTIVE",
        "rank": {
          "name": "Bronze Partner",
          "code": "BRONZE"
        },
        "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",
        "level": 2,
        "status": "ACTIVE",
        "rank": null,
        "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": 40 }
      ]
    }
  },
  "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;
    totalVolume: number;
    personalVolume: number;
    groupVolume: number;
  };
  growth: {
    date: string;
    newPartners: number;
    volume: number;
  }[];
  topPerformers: {
    id: string;
    name: string;
    volume: 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,
      "totalVolume": 1250000,
      "personalVolume": 150000,
      "groupVolume": 1100000
    },
    "growth": [
      { "date": "2024-01-01", "newPartners": 2, "volume": 45000 },
      { "date": "2024-01-08", "newPartners": 3, "volume": 62000 },
      { "date": "2024-01-15", "newPartners": 4, "volume": 78000 },
      { "date": "2024-01-22", "newPartners": 3, "volume": 55000 }
    ],
    "topPerformers": [
      { "id": "ff0e8400-e29b-41d4-a716-446655440001", "name": "Alice Johnson", "volume": 250000, "referrals": 8 },
      { "id": "ff0e8400-e29b-41d4-a716-446655440002", "name": "Bob Williams", "volume": 180000, "referrals": 5 }
    ],
    "rankDistribution": [
      { "rankCode": "STARTER", "rankName": "Starter", "count": 45, "percentage": 51.72 },
      { "rankCode": "BRONZE", "rankName": "Bronze Partner", "count": 25, "percentage": 28.74 },
      { "rankCode": "SILVER", "rankName": "Silver Partner", "count": 12, "percentage": 13.79 },
      { "rankCode": "GOLD", "rankName": "Gold Partner", "count": 5, "percentage": 5.75 }
    ]
  }
}

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;
    totalRevenue: number;
    totalCommissions: number;
  };
  timeline: {
    date: string;
    clicks: number;
    registrations: number;
    conversions: number;
  }[];
  topReferrals: {
    userId: string;
    name: string;
    status: string;
    registeredAt: string;
    totalPurchases: 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,
      "totalRevenue": 450000,
      "totalCommissions": 45000
    },
    "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",
        "totalPurchases": 150000
      }
    ]
  }
}

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.

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)
sourceType	string	Filter: 'ORDER', 'INVESTMENT', 'BONUS', 'RANK_BONUS' (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;
  sourceType: 'ORDER' | 'INVESTMENT' | 'BONUS' | 'RANK_BONUS' | 'CLAWBACK';
  sourceId: string;
  sourcePartner: {
    id: string;
    name: string;
  } | null;
  levelDepth: number | null;
  grossAmount: number;
  netAmount: number;
  careerPoints: number;
  currency: string;
  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&page=1&pageSize=20" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "commissions": [
      {
        "id": "jj0e8400-e29b-41d4-a716-446655440001",
        "sourceType": "ORDER",
        "sourceId": "kk0e8400-e29b-41d4-a716-446655440001",
        "sourcePartner": {
          "id": "ff0e8400-e29b-41d4-a716-446655440001",
          "name": "Alice Johnson"
        },
        "levelDepth": 1,
        "grossAmount": 1000,
        "netAmount": 1000,
        "careerPoints": 100,
        "currency": "RUB",
        "status": "APPROVED",
        "periodId": "2024-01",
        "processedAt": "2024-01-16T09:00:00Z",
        "createdAt": "2024-01-15T18: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.

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: {
    grossEarned: number;
    netEarned: number;
    pending: number;
    approved: number;
    paid: number;
    reversed: number;
    careerPointsEarned: number;
  };
  bySource: {
    sourceType: string;
    count: number;
    total: number;
    careerPoints: number;
  }[];
  byLevel: {
    level: number;
    count: number;
    total: number;
  }[];
  trend: {
    date: string;
    earned: number;
    careerPoints: 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": {
      "grossEarned": 125000,
      "netEarned": 125000,
      "pending": 15000,
      "approved": 50000,
      "paid": 60000,
      "reversed": 0,
      "careerPointsEarned": 12500
    },
    "bySource": [
      { "sourceType": "ORDER", "count": 45, "total": 75000, "careerPoints": 7500 },
      { "sourceType": "INVESTMENT", "count": 12, "total": 45000, "careerPoints": 4500 },
      { "sourceType": "RANK_BONUS", "count": 1, "total": 5000, "careerPoints": 500 }
    ],
    "byLevel": [
      { "level": 1, "count": 30, "total": 60000 },
      { "level": 2, "count": 18, "total": 36000 },
      { "level": 3, "count": 10, "total": 29000 }
    ],
    "trend": [
      { "date": "2024-01-01", "earned": 4500, "careerPoints": 450 },
      { "date": "2024-01-02", "earned": 3200, "careerPoints": 320 }
    ]
  }
}

Rank Endpoints

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;
  benefits: {
    commissionMultiplier: number;
    maxCommissionLevels: number;
    bonusPercentage: number;
  };
}

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-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2,
      "description": "Achieve 50,000 career points and have 10 direct referrals",
      "badgeUrl": "https://cdn.iwm-platform.com/badges/silver.png",
      "colorCode": "#C0C0C0"
    },
    "achievedAt": "2024-01-10T14:30:00Z",
    "benefits": {
      "commissionMultiplier": 1.1,
      "maxCommissionLevels": 5,
      "bonusPercentage": 2.0
    }
  }
}

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;
  } | null;
  requirements: {
    type: string;
    description: string;
    current: number;
    required: number;
    percentage: number;
    isMet: boolean;
  }[];
  overallProgress: number;
  estimatedAchievement: 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/ranks/progress \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "currentRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440001",
      "name": "Silver Partner",
      "code": "SILVER",
      "level": 2
    },
    "nextRank": {
      "id": "ee0e8400-e29b-41d4-a716-446655440002",
      "name": "Gold Partner",
      "code": "GOLD",
      "level": 3,
      "badgeUrl": "https://cdn.iwm-platform.com/badges/gold.png"
    },
    "requirements": [
      {
        "type": "CAREER_POINTS_TOTAL",
        "description": "Total career points",
        "current": 75000,
        "required": 100000,
        "percentage": 75.0,
        "isMet": false
      },
      {
        "type": "DIRECT_REFERRALS",
        "description": "Direct referrals",
        "current": 15,
        "required": 20,
        "percentage": 75.0,
        "isMet": false
      },
      {
        "type": "GROUP_VOLUME",
        "description": "Monthly group volume",
        "current": 800000,
        "required": 500000,
        "percentage": 100.0,
        "isMet": true
      }
    ],
    "overallProgress": 75.0,
    "estimatedAchievement": "2024-03-15"
  }
}

GET /api/v1/mlm/ranks/history

Get rank advancement 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)

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' | 'DEMOTION' | 'INITIAL';
  qualificationSnapshot: {
    careerPoints: number;
    directReferrals: number;
    groupVolume: number;
  };
  periodId: 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/ranks/history?page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

json

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440001",
        "fromRank": {
          "name": "Bronze Partner",
          "code": "BRONZE",
          "level": 1
        },
        "toRank": {
          "name": "Silver Partner",
          "code": "SILVER",
          "level": 2
        },
        "changeType": "PROMOTION",
        "qualificationSnapshot": {
          "careerPoints": 50000,
          "directReferrals": 10,
          "groupVolume": 250000
        },
        "periodId": "2024-01",
        "createdAt": "2024-01-10T14:30:00Z"
      },
      {
        "id": "ll0e8400-e29b-41d4-a716-446655440000",
        "fromRank": null,
        "toRank": {
          "name": "Bronze Partner",
          "code": "BRONZE",
          "level": 1
        },
        "changeType": "INITIAL",
        "qualificationSnapshot": {
          "careerPoints": 0,
          "directReferrals": 0,
          "groupVolume": 0
        },
        "periodId": null,
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 2,
      "page": 1,
      "pageSize": 10,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

Balance and Payout Endpoints

GET /api/v1/mlm/balance

Get balance 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 BalanceResponse {
  availableBalance: number;
  pendingBalance: number;
  totalEarned: number;
  totalWithdrawn: number;
  careerPoints: {
    total: number;
    currentPeriod: number;
  };
  currency: string;
  lastCalculatedAt: string | null;
  minimumPayout: number;
  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": {
    "availableBalance": 45000,
    "pendingBalance": 15000,
    "totalEarned": 180000,
    "totalWithdrawn": 120000,
    "careerPoints": {
      "total": 75000,
      "currentPeriod": 12500
    },
    "currency": "RUB",
    "lastCalculatedAt": "2024-01-15T23:59:59Z",
    "minimumPayout": 100,
    "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;
  amount: number;
  currency: string;
  method: {
    type: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
    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",
        "amount": 30000,
        "currency": "RUB",
        "method": {
          "type": "BANK_CARD",
          "maskedDetails": "**** **** **** 1234"
        },
        "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.

Authentication: Required (Partner)

Rate Limit: 1 request per minute (financial endpoint)

Request Headers

Authorization: Bearer <access_token>

Request Body

typescript

interface PayoutRequestBody {
  amount: number;                 // Must be >= minimum payout amount
  currency?: string;              // Defaults to account currency (RUB)
  methodType: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
  // 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
    bankBik?: string;             // For BANK_TRANSFER
    accountNumber?: string;       // For BANK_TRANSFER
    walletType?: string;          // For EWALLET
    walletId?: string;            // For EWALLET
  };
}

Query Parameters

None

Response (201 Created)

typescript

interface PayoutRequestResponse {
  payoutId: string;
  amount: number;
  currency: string;
  method: {
    type: string;
    maskedDetails: string;
  };
  status: 'PENDING';
  estimatedProcessingTime: string;
  newAvailableBalance: number;
  createdAt: string;
}

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid input data
400	AMOUNT_BELOW_MINIMUM	Amount below minimum payout threshold
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 '{
    "amount": 25000,
    "methodType": "BANK_CARD",
    "useSavedDetails": true
  }'

Response:

json

{
  "success": true,
  "data": {
    "payoutId": "nn0e8400-e29b-41d4-a716-446655440001",
    "amount": 25000,
    "currency": "RUB",
    "method": {
      "type": "BANK_CARD",
      "maskedDetails": "**** **** **** 1234"
    },
    "status": "PENDING",
    "estimatedProcessingTime": "1-3 business days",
    "newAvailableBalance": 20000,
    "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;
  amount: number;
  currency: string;
  method: {
    type: 'BANK_CARD' | 'BANK_TRANSFER' | 'EWALLET';
    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",
    "amount": 30000,
    "currency": "RUB",
    "method": {
      "type": "BANK_CARD",
      "maskedDetails": "**** **** **** 1234"
    },
    "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"
  }
}

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