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 agentreject: reject the request and mark the pending relation asdisabled
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.