Promo API

This document describes the admin-facing API for the promo module. These endpoints require administrator authentication.

Admin Endpoints

Promo Overview

Endpoint: GET /api/admin/promo/overview

Returns overview metrics, recent agents, recent attributions and recent commissions.

Response Example:

{
  "overview": {
    "members": 12,
    "agents": 4,
    "masterAgents": 1,
    "commissionAmount": 128.5,
    "attributedOrders": 20
  },
  "agents": [],
  "attributions": [],
  "commissions": []
}

Promo Settings

Endpoint: GET /api/admin/promo/settings

Returns persisted promo settings.

Response Example:

{
  "promo_invite_reward_amount": "10"
}

Endpoint: POST /api/admin/promo/settings

Request Body Example:

{
  "promo_invite_reward_amount": "10"
}

Agent Tiers

Endpoint: GET /api/admin/promo/tiers

Returns all configured agent tiers.

Endpoint: POST /api/admin/promo/tiers

Creates or updates an agent tier.

Request Body Example:

{
  "code": "master-default",
  "name": "Master Agent",
  "roleScope": "master_agent",
  "level": 100,
  "discountRate": 0.8,
  "salesThreshold": 0,
  "isFixed": true,
  "isActive": true,
  "description": "Fixed discount for master agents"
}

Agents

Endpoint: GET /api/admin/promo/agents?page=1&pageSize=15

Returns a paginated list of promo agents and master agents.

Endpoint: POST /api/admin/promo/agents

Assigns a user as master_agent or agent by email.

Request Body Example:

{
  "email": "agent@example.com",
  "role": "agent",
  "parentAgentUserId": 12
}

Agent Relations

Endpoint: GET /api/admin/promo/relations

Returns current promo agent relation records, including parent and master agent bindings.

Endpoint: PUT /api/admin/promo/relations/:id

Updates the parent master agent for an existing child-agent relation.

Request Body Example:

{
  "parentAgentUserId": 12
}

Endpoint: DELETE /api/admin/promo/relations/:id

Disables the agent relation and demotes the member back to a normal member. Master agents with active child agents cannot be removed.

Commissions

Endpoint: GET /api/admin/promo/commissions?page=1&pageSize=15

Returns a paginated list of promo commission records.

User Endpoints

User Promo Overview

Endpoint: GET /api/users/promo/overview

Returns current user's referral summary, promo links, promo codes and agent-role flags such as isAgent / isMasterAgent. When the user visits this endpoint for the first time, the backend will lazily create a promo member record and generate invite-related codes automatically. If the user registers through a master-agent agent link, the system first creates a promo_agent_relations.status = pending relation. The user only joins the formal team after the master agent approves it.

User Invite Records

Endpoint: GET /api/users/promo/invites

Returns invite records created by the current user.

User Team Records

Endpoint: GET /api/users/promo/team

Returns formal child-agent team records visible to the current user and only includes status = active members.

Pending Agent Applicants

Endpoint: GET /api/users/promo/pending

Returns pending child-agent applications under the current master agent and only includes status = pending records.

Endpoint: POST /api/users/promo/pending/:id

Allows the current master agent to review a pending child-agent request.

Request Body Example:

{
  "action": "approve"
}

Supported action values:

  • approve: promote the applicant into a formal child agent
  • reject: reject the request and mark the pending relation as disabled

User Commission Records

Endpoint: GET /api/users/promo/commissions

Returns promo commission records owned by the current user.

Team Report

Endpoint: GET /api/admin/promo/team-report?masterAgentUserId=12

Returns team summary and child-agent sales report for a given master agent.

Endpoint: GET /api/users/promo/team-report

Returns the current master agent's team summary and child-agent sales report.

Team Orders

Endpoint: GET /api/admin/promo/team-orders?masterAgentUserId=12

Returns attributed team order details for a given master agent.

Endpoint: GET /api/users/promo/team-orders

Returns attributed team order details for the current master agent.