---
title: "Promo API"
canonical_url: "https://ainode.run/docs/promo"
type: "doc"
locale: "en"
description: "Admin endpoints for managing promo settings, agent tiers, promo agents and commission overview."
---

# Promo API
> Admin endpoints for managing promo settings, agent tiers, promo agents and commission overview.

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:**

```json
{
  "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:**

```json
{
  "promo_invite_reward_amount": "10"
}
```

**Endpoint:** `POST /api/admin/promo/settings`

**Request Body Example:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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.
