PPanel Edgereferral
由 openapi.json 自动生成的 28 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/growth/invite-codes
GET /api/v1/admin/growth/invite-codes
List universal invite codes
{
"parameters": [
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "channel",
"required": false,
"schema": {
"maxLength": 64,
"type": "string"
}
},
{
"in": "query",
"name": "promoter_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"additionalProperties": false,
"properties": {
"channel": {
"default": null,
"maxLength": 64,
"type": [
"string",
"null"
]
},
"code": {
"pattern": "^[A-Z0-9_-]{3,64}$",
"type": "string"
},
"effect": {
"additionalProperties": false,
"default": {
"invitee_rewards": [],
"landing": "/"
},
"properties": {
"invitee_rewards": {
"default": [],
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"kind": {
"enum": [
"gift_credit"
],
"type": "string"
}
},
"required": [
"kind",
"amount_minor"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"coupon"
],
"type": "string"
}
},
"required": [
"kind",
"code_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"kind",
"period_unit",
"period_count"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"trial"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id",
"period_unit",
"period_count"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
},
"landing": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"max_redemptions": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"promoter_user_id": {
"default": null,
"format": "uuid",
"type": [
"string",
"null"
]
},
"redeemed_count": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"code",
"starts_at",
"ends_at",
"id",
"redeemed_count",
"version"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "List universal invite codes",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "growth.invite_code.manage",
"effectiveSecurity": []
}POST /api/v1/admin/growth/invite-codes
POST /api/v1/admin/growth/invite-codes
Create a universal invite code
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channel": {
"default": null,
"maxLength": 64,
"type": [
"string",
"null"
]
},
"code": {
"pattern": "^[A-Z0-9_-]{3,64}$",
"type": "string"
},
"effect": {
"additionalProperties": false,
"default": {
"invitee_rewards": [],
"landing": "/"
},
"properties": {
"invitee_rewards": {
"default": [],
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"kind": {
"enum": [
"gift_credit"
],
"type": "string"
}
},
"required": [
"kind",
"amount_minor"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"coupon"
],
"type": "string"
}
},
"required": [
"kind",
"code_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"kind",
"period_unit",
"period_count"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"trial"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id",
"period_unit",
"period_count"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
},
"landing": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
},
"ends_at": {
"default": null,
"format": "date-time",
"type": [
"string",
"null"
]
},
"max_redemptions": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"promoter_user_id": {
"default": null,
"format": "uuid",
"type": [
"string",
"null"
]
},
"starts_at": {
"default": null,
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
}
},
"required": [
"name",
"code"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channel": {
"default": null,
"maxLength": 64,
"type": [
"string",
"null"
]
},
"code": {
"pattern": "^[A-Z0-9_-]{3,64}$",
"type": "string"
},
"effect": {
"additionalProperties": false,
"default": {
"invitee_rewards": [],
"landing": "/"
},
"properties": {
"invitee_rewards": {
"default": [],
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"kind": {
"enum": [
"gift_credit"
],
"type": "string"
}
},
"required": [
"kind",
"amount_minor"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"coupon"
],
"type": "string"
}
},
"required": [
"kind",
"code_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"kind",
"period_unit",
"period_count"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"trial"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id",
"period_unit",
"period_count"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
},
"landing": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"max_redemptions": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"promoter_user_id": {
"default": null,
"format": "uuid",
"type": [
"string",
"null"
]
},
"redeemed_count": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"code",
"starts_at",
"ends_at",
"id",
"redeemed_count",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Create a universal invite code",
"tags": [
"referral"
],
"x-audit": "growth.invite_code.create",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true
},
"x-idempotency": "required",
"x-permission": "growth.invite_code.manage",
"x-reauth": false,
"effectiveSecurity": []
}DELETE /api/v1/admin/growth/invite-codes/{id}
DELETE /api/v1/admin/growth/invite-codes/{id}
Delete an unused invite code
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Delete an unused invite code",
"tags": [
"referral"
],
"x-audit": "growth.invite_code.delete",
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "growth.invite_code.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/growth/invite-codes/{id}
GET /api/v1/admin/growth/invite-codes/{id}
Read an invite code
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channel": {
"default": null,
"maxLength": 64,
"type": [
"string",
"null"
]
},
"code": {
"pattern": "^[A-Z0-9_-]{3,64}$",
"type": "string"
},
"effect": {
"additionalProperties": false,
"default": {
"invitee_rewards": [],
"landing": "/"
},
"properties": {
"invitee_rewards": {
"default": [],
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"kind": {
"enum": [
"gift_credit"
],
"type": "string"
}
},
"required": [
"kind",
"amount_minor"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"coupon"
],
"type": "string"
}
},
"required": [
"kind",
"code_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"kind",
"period_unit",
"period_count"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"trial"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id",
"period_unit",
"period_count"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
},
"landing": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"max_redemptions": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"promoter_user_id": {
"default": null,
"format": "uuid",
"type": [
"string",
"null"
]
},
"redeemed_count": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"code",
"starts_at",
"ends_at",
"id",
"redeemed_count",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Read an invite code",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "growth.invite_code.manage",
"effectiveSecurity": []
}PATCH /api/v1/admin/growth/invite-codes/{id}
PATCH /api/v1/admin/growth/invite-codes/{id}
Update or disable an invite code
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channel": {
"default": null,
"maxLength": 64,
"type": [
"string",
"null"
]
},
"effect": {
"additionalProperties": false,
"default": {
"invitee_rewards": [],
"landing": "/"
},
"properties": {
"invitee_rewards": {
"default": [],
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"kind": {
"enum": [
"gift_credit"
],
"type": "string"
}
},
"required": [
"kind",
"amount_minor"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"coupon"
],
"type": "string"
}
},
"required": [
"kind",
"code_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"kind",
"period_unit",
"period_count"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"trial"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id",
"period_unit",
"period_count"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
},
"landing": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
},
"ends_at": {
"default": null,
"format": "date-time",
"type": [
"string",
"null"
]
},
"max_redemptions": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"promoter_user_id": {
"default": null,
"format": "uuid",
"type": [
"string",
"null"
]
},
"starts_at": {
"default": null,
"format": "date-time",
"type": [
"string",
"null"
]
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channel": {
"default": null,
"maxLength": 64,
"type": [
"string",
"null"
]
},
"code": {
"pattern": "^[A-Z0-9_-]{3,64}$",
"type": "string"
},
"effect": {
"additionalProperties": false,
"default": {
"invitee_rewards": [],
"landing": "/"
},
"properties": {
"invitee_rewards": {
"default": [],
"items": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"kind": {
"enum": [
"gift_credit"
],
"type": "string"
}
},
"required": [
"kind",
"amount_minor"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"enum": [
"coupon"
],
"type": "string"
}
},
"required": [
"kind",
"code_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"kind",
"period_unit",
"period_count"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"trial"
],
"type": "string"
},
"period_count": {
"exclusiveMinimum": 0,
"maximum": 3650,
"type": "integer"
},
"period_unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id",
"period_unit",
"period_count"
],
"type": "object"
}
]
},
"maxItems": 20,
"type": "array"
},
"landing": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"max_redemptions": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"promoter_user_id": {
"default": null,
"format": "uuid",
"type": [
"string",
"null"
]
},
"redeemed_count": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"code",
"starts_at",
"ends_at",
"id",
"redeemed_count",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Update or disable an invite code",
"tags": [
"referral"
],
"x-audit": "growth.invite_code.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "growth.invite_code.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/growth/referral-levels
GET /api/v1/admin/growth/referral-levels
List referral levels
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "List referral levels",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "growth.referral.manage",
"effectiveSecurity": []
}POST /api/v1/admin/growth/referral-levels
POST /api/v1/admin/growth/referral-levels
Create a referral level
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Create a referral level",
"tags": [
"referral"
],
"x-audit": "growth.level.create",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true
},
"x-idempotency": "required",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}PUT /api/v1/admin/growth/referral-levels/order
PUT /api/v1/admin/growth/referral-levels/order
Reorder every referral level
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"ids": {
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
}
},
"required": [
"ids"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
}
},
"description": "Result"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Reorder every referral level",
"tags": [
"referral"
],
"x-audit": "growth.level.reorder",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}DELETE /api/v1/admin/growth/referral-levels/{id}
DELETE /api/v1/admin/growth/referral-levels/{id}
Delete an unused non-base level
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Deleted"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Delete an unused non-base level",
"tags": [
"referral"
],
"x-audit": "growth.level.delete",
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/growth/referral-levels/{id}
GET /api/v1/admin/growth/referral-levels/{id}
Read a referral level
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Read a referral level",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "growth.referral.manage",
"effectiveSecurity": []
}PATCH /api/v1/admin/growth/referral-levels/{id}
PATCH /api/v1/admin/growth/referral-levels/{id}
Update a referral level without changing past commissions
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Update a referral level without changing past commissions",
"tags": [
"referral"
],
"x-audit": "growth.level.update",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/growth/referral-stats
GET /api/v1/admin/growth/referral-stats
Referral statistics
{
"parameters": [
{
"in": "query",
"name": "referrer_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "code_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "channel",
"required": false,
"schema": {
"maxLength": 64,
"type": "string"
}
},
{
"in": "query",
"name": "from",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
},
{
"in": "query",
"name": "to",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"clicks": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"commission_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"daily": {
"items": {
"properties": {
"clicks": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"code": {
"type": [
"string",
"null"
]
},
"commission_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"date": {
"format": "date",
"type": "string"
},
"first_paid": {
"type": "integer"
},
"paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"registrations": {
"type": "integer"
},
"rewards": {
"type": "integer"
}
},
"required": [
"date",
"code",
"clicks",
"registrations",
"first_paid",
"paid_minor",
"commission_minor",
"rewards"
],
"type": "object"
},
"type": "array"
},
"first_paid": {
"type": "integer"
},
"paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"registrations": {
"type": "integer"
},
"rewards": {
"type": "integer"
}
},
"required": [
"daily",
"currency",
"clicks",
"registrations",
"first_paid",
"paid_minor",
"commission_minor",
"rewards"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "Referral statistics",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "growth.referral.read",
"effectiveSecurity": []
}GET /api/v1/admin/growth/referrals
GET /api/v1/admin/growth/referrals
List referral relationships
{
"parameters": [
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "referrer_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "code_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "channel",
"required": false,
"schema": {
"maxLength": 64,
"type": "string"
}
},
{
"in": "query",
"name": "from",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
},
{
"in": "query",
"name": "to",
"required": false,
"schema": {
"format": "date",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"created_at": {
"type": "string"
},
"email_masked": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"invite_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"invited_via": {
"type": [
"string",
"null"
]
},
"public_id": {
"type": "string"
}
},
"required": [
"id",
"public_id",
"email_masked",
"invited_via",
"invite_code_id",
"created_at"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "List referral relationships",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "growth.referral.read",
"effectiveSecurity": []
}GET /api/v1/admin/growth/rewards
GET /api/v1/admin/growth/rewards
List referral rewards and held review queue
{
"parameters": [
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "beneficiary_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"enum": [
"held",
"pending",
"available",
"granted",
"reversed",
"rejected"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"available_at": {
"type": [
"string",
"null"
]
},
"base_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"beneficiary_user_id": {
"format": "uuid",
"type": "string"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"invite_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"invitee_user_id": {
"format": "uuid",
"type": "string"
},
"inviter_user_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"commission",
"gift_credit",
"coupon",
"traffic_bonus",
"term_extend",
"trial"
],
"type": "string"
},
"order_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"rate_bps": {
"type": [
"integer",
"null"
]
},
"reversed_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"review_reason": {
"type": [
"string",
"null"
]
},
"role": {
"enum": [
"inviter",
"invitee"
],
"type": "string"
},
"rule_key": {
"type": "string"
},
"rule_snapshot": {
"additionalProperties": {},
"type": "object"
},
"status": {
"enum": [
"pending",
"held",
"available",
"granted",
"reversed",
"rejected"
],
"type": "string"
},
"trigger": {
"enum": [
"registered",
"first_paid",
"paid"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"currency",
"id",
"beneficiary_user_id",
"invitee_user_id",
"inviter_user_id",
"invite_code_id",
"role",
"trigger",
"order_id",
"kind",
"rule_key",
"rule_snapshot",
"base_minor",
"rate_bps",
"amount_minor",
"reversed_minor",
"status",
"available_at",
"idempotency_key",
"review_reason",
"version"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "List referral rewards and held review queue",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "growth.commission.read",
"effectiveSecurity": []
}POST /api/v1/admin/growth/rewards/{id}/approve
POST /api/v1/admin/growth/rewards/{id}/approve
Approve a held referral reward
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"available_at": {
"type": [
"string",
"null"
]
},
"base_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"beneficiary_user_id": {
"format": "uuid",
"type": "string"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"invite_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"invitee_user_id": {
"format": "uuid",
"type": "string"
},
"inviter_user_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"commission",
"gift_credit",
"coupon",
"traffic_bonus",
"term_extend",
"trial"
],
"type": "string"
},
"order_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"rate_bps": {
"type": [
"integer",
"null"
]
},
"reversed_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"review_reason": {
"type": [
"string",
"null"
]
},
"role": {
"enum": [
"inviter",
"invitee"
],
"type": "string"
},
"rule_key": {
"type": "string"
},
"rule_snapshot": {
"additionalProperties": {},
"type": "object"
},
"status": {
"enum": [
"pending",
"held",
"available",
"granted",
"reversed",
"rejected"
],
"type": "string"
},
"trigger": {
"enum": [
"registered",
"first_paid",
"paid"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"currency",
"id",
"beneficiary_user_id",
"invitee_user_id",
"inviter_user_id",
"invite_code_id",
"role",
"trigger",
"order_id",
"kind",
"rule_key",
"rule_snapshot",
"base_minor",
"rate_bps",
"amount_minor",
"reversed_minor",
"status",
"available_at",
"idempotency_key",
"review_reason",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Approve a held referral reward",
"tags": [
"referral"
],
"x-audit": "growth.reward.approve",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/growth/rewards/{id}/reject
POST /api/v1/admin/growth/rewards/{id}/reject
Reject a held referral reward
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"available_at": {
"type": [
"string",
"null"
]
},
"base_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"beneficiary_user_id": {
"format": "uuid",
"type": "string"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"invite_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"invitee_user_id": {
"format": "uuid",
"type": "string"
},
"inviter_user_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"commission",
"gift_credit",
"coupon",
"traffic_bonus",
"term_extend",
"trial"
],
"type": "string"
},
"order_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"rate_bps": {
"type": [
"integer",
"null"
]
},
"reversed_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"review_reason": {
"type": [
"string",
"null"
]
},
"role": {
"enum": [
"inviter",
"invitee"
],
"type": "string"
},
"rule_key": {
"type": "string"
},
"rule_snapshot": {
"additionalProperties": {},
"type": "object"
},
"status": {
"enum": [
"pending",
"held",
"available",
"granted",
"reversed",
"rejected"
],
"type": "string"
},
"trigger": {
"enum": [
"registered",
"first_paid",
"paid"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"currency",
"id",
"beneficiary_user_id",
"invitee_user_id",
"inviter_user_id",
"invite_code_id",
"role",
"trigger",
"order_id",
"kind",
"rule_key",
"rule_snapshot",
"base_minor",
"rate_bps",
"amount_minor",
"reversed_minor",
"status",
"available_at",
"idempotency_key",
"review_reason",
"version"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Reject a held referral reward",
"tags": [
"referral"
],
"x-audit": "growth.reward.reject",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/users/{id}/referral-level
GET /api/v1/admin/users/{id}/referral-level
User referral level and assessment progress
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"level": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
},
"locked": {
"type": "boolean"
},
"next_level": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": [
"object",
"null"
]
},
"performance": {
"properties": {
"net_paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"paid_invitees": {
"type": "integer"
}
},
"required": [
"paid_invitees",
"net_paid_minor"
],
"type": "object"
},
"referral_level_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"until": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"referral_level_id",
"until",
"locked",
"version",
"level",
"performance",
"next_level"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "User referral level and assessment progress",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "growth.referral.read",
"effectiveSecurity": []
}PUT /api/v1/admin/users/{id}/referral-level
PUT /api/v1/admin/users/{id}/referral-level
Assign or lock a referral level
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"level_id": {
"format": "uuid",
"type": "string"
},
"locked": {
"type": "boolean"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"level": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
},
"locked": {
"type": "boolean"
},
"next_level": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": [
"object",
"null"
]
},
"performance": {
"properties": {
"net_paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"paid_invitees": {
"type": "integer"
}
},
"required": [
"paid_invitees",
"net_paid_minor"
],
"type": "object"
},
"referral_level_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"until": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"referral_level_id",
"until",
"locked",
"version",
"level",
"performance",
"next_level"
],
"type": "object"
}
}
},
"description": "Result",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Assign or lock a referral level",
"tags": [
"referral"
],
"x-audit": "growth.level.assign",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}PUT /api/v1/admin/users/{id}/referrer
PUT /api/v1/admin/users/{id}/referrer
Correct referrer for future orders
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Resource ETag; missing 428, malformed 412, stale 409.",
"in": "header",
"name": "If-Match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
},
"referrer_user_id": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"referrer_user_id",
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"referrer_user_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"user_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"user_id",
"referrer_user_id"
],
"type": "object"
}
}
},
"description": "Result"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Resource not found"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "State or version conflict"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid input"
}
},
"summary": "Correct referrer for future orders",
"tags": [
"referral"
],
"x-audit": "growth.referrer.correct",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"ifMatch": true
},
"x-idempotency": "optional",
"x-permission": "growth.referral.manage",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/me/referral
GET /api/v1/me/referral
My referral centre
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "string"
},
"level": {
"properties": {
"level": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": "object"
},
"locked": {
"type": "boolean"
},
"next_level": {
"additionalProperties": false,
"properties": {
"first_order_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"i18n": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"_meta": {
"additionalProperties": false,
"properties": {
"origin": {
"enum": [
"manual",
"machine",
"builtin"
],
"type": "string"
},
"provider": {
"maxLength": 64,
"type": "string"
}
},
"required": [
"origin"
],
"type": "object"
},
"description": {
"maxLength": 1000,
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"default": {},
"type": "object"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_base": {
"type": "boolean"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"rank": {
"type": "integer"
},
"recurring_rate_bps": {
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"retain_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"retain_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"source_locale": {
"default": "zh-CN",
"maxLength": 20,
"minLength": 2,
"type": "string"
},
"status": {
"default": "active",
"enum": [
"active",
"disabled"
],
"type": "string"
},
"upgrade_min_net_paid_minor": {
"default": null,
"pattern": "^[1-9]\\d{0,17}$",
"type": [
"string",
"null"
]
},
"upgrade_min_paid_invitees": {
"default": null,
"exclusiveMinimum": 0,
"type": [
"integer",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"name",
"rank",
"first_order_rate_bps",
"recurring_rate_bps",
"id",
"is_base",
"version"
],
"type": [
"object",
"null"
]
},
"performance": {
"properties": {
"net_paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"paid_invitees": {
"type": "integer"
}
},
"required": [
"paid_invitees",
"net_paid_minor"
],
"type": "object"
},
"referral_level_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"until": {
"type": [
"string",
"null"
]
},
"version": {
"type": "integer"
}
},
"required": [
"referral_level_id",
"until",
"locked",
"version",
"level",
"performance",
"next_level"
],
"type": "object"
},
"stats": {
"properties": {
"clicks": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"commission_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"daily": {
"items": {
"properties": {
"clicks": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"code": {
"type": [
"string",
"null"
]
},
"commission_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"date": {
"format": "date",
"type": "string"
},
"first_paid": {
"type": "integer"
},
"paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"registrations": {
"type": "integer"
},
"rewards": {
"type": "integer"
}
},
"required": [
"date",
"code",
"clicks",
"registrations",
"first_paid",
"paid_minor",
"commission_minor",
"rewards"
],
"type": "object"
},
"type": "array"
},
"first_paid": {
"type": "integer"
},
"paid_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"registrations": {
"type": "integer"
},
"rewards": {
"type": "integer"
}
},
"required": [
"daily",
"currency",
"clicks",
"registrations",
"first_paid",
"paid_minor",
"commission_minor",
"rewards"
],
"type": "object"
}
},
"required": [
"code",
"stats",
"level"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "My referral centre",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}GET /api/v1/me/referral/invitations
GET /api/v1/me/referral/invitations
My sent invitations
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"created_at": {
"type": "string"
},
"email": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"email",
"role",
"status",
"expires_at",
"created_at"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"items"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "My sent invitations",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}POST /api/v1/me/referral/invitations
POST /api/v1/me/referral/invitations
Invite a friend
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"email": {
"format": "email",
"maxLength": 254,
"type": "string"
}
},
"required": [
"email"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"created_at": {
"type": "string"
},
"email": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"role": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"email",
"role",
"status",
"expires_at",
"created_at"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "Invite a friend",
"tags": [
"referral"
],
"x-audit": "growth.invitation.create",
"x-body": "json",
"x-body-limit": 65536,
"x-capability": "me.referral.invite",
"x-idempotency": "required",
"x-rate-limit": "growth.invitation.user",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/me/referral/invitees
GET /api/v1/me/referral/invitees
My invited users
{
"parameters": [
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"created_at": {
"type": "string"
},
"email_masked": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"invite_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"invited_via": {
"type": [
"string",
"null"
]
},
"public_id": {
"type": "string"
}
},
"required": [
"id",
"public_id",
"email_masked",
"invited_via",
"invite_code_id",
"created_at"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "My invited users",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}POST /api/v1/me/referral/links
POST /api/v1/me/referral/links
Generate a referral link
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"channel": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
},
"to": {
"default": "/",
"pattern": "^(?:\\/|\\/pricing|\\/docs(?:\\/[a-zA-Z0-9_-]+)*|\\/app\\/(?:en-US\\/)?checkout\\?kind=purchase&plan=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}&price=[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$",
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"code",
"url"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "Generate a referral link",
"tags": [
"referral"
],
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "optional",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/me/referral/rewards
GET /api/v1/me/referral/rewards
My referral rewards
{
"parameters": [
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"available_at": {
"type": [
"string",
"null"
]
},
"base_minor": {
"pattern": "^\\d{1,18}$",
"type": [
"string",
"null"
]
},
"beneficiary_user_id": {
"format": "uuid",
"type": "string"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"invite_code_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"invitee_user_id": {
"format": "uuid",
"type": "string"
},
"inviter_user_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"kind": {
"enum": [
"commission",
"gift_credit",
"coupon",
"traffic_bonus",
"term_extend",
"trial"
],
"type": "string"
},
"order_id": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"rate_bps": {
"type": [
"integer",
"null"
]
},
"reversed_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
},
"review_reason": {
"type": [
"string",
"null"
]
},
"role": {
"enum": [
"inviter",
"invitee"
],
"type": "string"
},
"rule_key": {
"type": "string"
},
"rule_snapshot": {
"additionalProperties": {},
"type": "object"
},
"status": {
"enum": [
"pending",
"held",
"available",
"granted",
"reversed",
"rejected"
],
"type": "string"
},
"trigger": {
"enum": [
"registered",
"first_paid",
"paid"
],
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"currency",
"id",
"beneficiary_user_id",
"invitee_user_id",
"inviter_user_id",
"invite_code_id",
"role",
"trigger",
"order_id",
"kind",
"rule_key",
"rule_snapshot",
"base_minor",
"rate_bps",
"amount_minor",
"reversed_minor",
"status",
"available_at",
"idempotency_key",
"review_reason",
"version"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "My referral rewards",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}POST /api/v1/me/wallet/commission-to-cash
POST /api/v1/me/wallet/commission-to-cash
Transfer available commission to balance
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"amount_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"amount_minor"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"transferred_minor": {
"pattern": "^\\d{1,18}$",
"type": "string"
}
},
"required": [
"transferred_minor"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "Transfer available commission to balance",
"tags": [
"referral"
],
"x-audit": "growth.commission.transfer",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-mfa": true,
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/public/referral/{code}
GET /api/v1/public/referral/{code}
Referral landing information
{
"parameters": [
{
"in": "path",
"name": "code",
"required": true,
"schema": {
"maxLength": 64,
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"invitee_rewards": {},
"promoter_name": {
"type": [
"string",
"null"
]
},
"valid": {
"type": "boolean"
}
},
"required": [
"valid",
"promoter_name"
],
"type": "object"
}
}
},
"description": "Result"
}
},
"summary": "Referral landing information",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}GET /r/{code}
GET /r/{code}
Record last-click attribution and redirect
{
"parameters": [
{
"in": "path",
"name": "code",
"required": true,
"schema": {
"maxLength": 64,
"type": "string"
}
},
{
"in": "query",
"name": "to",
"required": false,
"schema": {
"maxLength": 500,
"type": "string"
}
},
{
"in": "query",
"name": "ch",
"required": false,
"schema": {
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"type": "string"
}
}
],
"responses": {
"302": {
"description": "Whitelisted landing page"
}
},
"summary": "Record last-click attribution and redirect",
"tags": [
"referral"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-rate-limit": "growth.referral.ip",
"x-reauth": false,
"effectiveSecurity": []
}