Distribution System

The Ace Data Cloud platform provides a complete distribution (referral/affiliate) system. Users can earn corresponding commission rewards by inviting new users to register and make purchases.

This document describes the API interfaces related to the distribution system. All interfaces require authentication; for details, please refer to Platform Token.

Query Distribution Status

Get the current user's distribution status, including current level, total invited amount, total commission, etc.

  • Request Method: GET
  • Request URL: https://platform.acedata.cloud/api/v1/distribution-statuses/
  • Request Headers:
    • accept: application/json
    • authorization: Bearer {token}

CURL Request Example

curl -X GET \
  -H "accept: application/json" \
  -H "authorization: Bearer {token}" \
  "https://platform.acedata.cloud/api/v1/distribution-statuses/"

Response Result Example

{
  "count": 1,
  "results": [
    {
      "id": "status-uuid",
      "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
      "level": {
        "id": "level-uuid",
        "level": 1,
        "threshold": 0,
        "percentage": 0.1
      },
      "price": 500.0,
      "reward": 50.0,
      "tags": null,
      "metadata": null,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-08-01T00:00:00.000000Z"
    }
  ]
}

Response Field Description

Field Type Description
level object Current distribution level
level.level integer Level number
level.threshold number Total invited amount required to upgrade to this level
level.percentage number Commission rate (e.g., 0.1 means 10%)
price number Total amount spent by invited users
reward number Total commission earned

Initialize Distribution Status

If the current user does not have a distribution status record, this interface can be called to initialize it.

  • Request Method: POST
  • Request URL: https://platform.acedata.cloud/api/v1/distribution-statuses/initialize/
curl -X POST \
  -H "accept: application/json" \
  -H "authorization: Bearer {token}" \
  "https://platform.acedata.cloud/api/v1/distribution-statuses/initialize/"

Query Distribution Levels

Get detailed information about all distribution levels.

  • Request Method: GET
  • Request URL: https://platform.acedata.cloud/api/v1/distribution-levels/
curl -X GET \
  -H "accept: application/json" \
  -H "authorization: Bearer {token}" \
  "https://platform.acedata.cloud/api/v1/distribution-levels/"

Response Result Example

{
  "count": 3,
  "results": [
    {
      "id": "level-1-uuid",
      "level": 1,
      "threshold": 0,
      "percentage": 0.1,
      "tags": null,
      "metadata": null
    },
    {
      "id": "level-2-uuid",
      "level": 2,
      "threshold": 1000,
      "percentage": 0.15,
      "tags": null,
      "metadata": null
    },
    {
      "id": "level-3-uuid",
      "level": 3,
      "threshold": 5000,
      "percentage": 0.2,
      "tags": null,
      "metadata": null
    }
  ]
}

Query Distribution History

Get a list of commission records, including the source order of each commission, the invitee, commission amount, etc.

  • Request Method: GET
  • Request URL: https://platform.acedata.cloud/api/v1/distribution-histories/

Query Parameters

Parameter Type Required Description
limit integer No Number of items returned per page
offset integer No Offset 
curl -X GET \
  -H "accept: application/json" \
  -H "authorization: Bearer {token}" \
  "https://platform.acedata.cloud/api/v1/distribution-histories/"

Response Result Example

{
  "count": 20,
  "results": [
    {
      "id": "history-uuid",
      "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
      "inviter_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6",
      "invitee_id": "new-user-uuid",
      "order_id": "order-uuid",
      "percentage": 0.1,
      "reward": 5.0,
      "invalid": false,
      "order": {
        "id": "order-uuid",
        "price": 50.0,
        "state": "Finished"
      },
      "invitee": {
        "id": "new-user-uuid",
        "nickname": "New User"
      },
      "tags": null,
      "metadata": null,
      "created_at": "2024-08-01T10:00:00.000000Z"
    }
  ]
}

Response Field Description

Field Type Description
inviter_id string User ID of the inviter (yourself)
invitee_id string User ID of the invitee
order_id string Associated order ID
percentage number Commission rate
reward number Amount of commission earned
invalid boolean Whether it is invalid (e.g., order refunded)
order object Order details
invitee object Invitee information

Code Example

Python:

import requests

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}"
}

# Query distribution status
response = requests.get("https://platform.acedata.cloud/api/v1/distribution-statuses/", headers=headers)
status = response.json()["results"][0]
print(f"Current Level: {status['level']['level']}")
print(f"Commission Rate: {status['level']['percentage'] * 100}%")
print(f"Total Commission: ${status['reward']}")

# Query distribution history
response = requests.get("https://platform.acedata.cloud/api/v1/distribution-histories/", headers=headers)
data = response.json()
for h in data["results"]:
    print(f"Commission: ${h['reward']} | Order Amount: ${h['order']['price']} | Invitee: {h['invitee']['nickname']}")