> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Query AceDataCloud Referral Reward Information

> Platform integration guide - Ace Data Cloud

AceDataCloud currently does not have an aggregated `/api/v1/distribution/` endpoint. Referral reward data consists of four groups of interfaces: status, history, level, and redemption; please call according to the required resource and avoid relying on a non-existent summary response.

## Preparation

1. Create and save an Account Token in the [Account Token Console](https://platform.acedata.cloud/console/platform-tokens).
2. Use `GET /api/v1/platform-tokens/me/` to obtain the current account UUID.

```shell theme={null}
export PLATFORM_TOKEN='your account token'
export USER_ID='your account UUID'
```

## Available Interfaces

| Method | URL | Purpose |
| - | - | - |
| `GET` | `/api/v1/distribution-statuses/?user_id=${USER_ID}` | Current account's cumulative referral amount, rewards, and level |
| `POST` | `/api/v1/distribution-statuses/initialize/` | Initialize or refresh the current account level for the first time; writes data |
| `GET` | `/api/v1/distribution-histories/?user_id=${USER_ID}` | Referral reward history |
| `GET` | `/api/v1/distribution-levels/` | Level and percentage rules |
| `GET` | `/api/v1/distribution-redemptions/preview/` | Preview currently redeemable rewards; optional `amount` |
| `GET` | `/api/v1/distribution-redemptions/` | Completed redemption records |
| `POST` | `/api/v1/distribution-redemptions/redeem/` | Confirm redemption; requires `idempotency_key` and creates an irreversible redemption |

## Read-Only Request Examples

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/distribution-statuses/' \
  --data-urlencode "user_id=${USER_ID}" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl --get 'https://platform.acedata.cloud/api/v1/distribution-histories/' \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl 'https://platform.acedata.cloud/api/v1/distribution-levels/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl 'https://platform.acedata.cloud/api/v1/distribution-redemptions/preview/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

The response format verified online is:

* status, history, level, redemption list: `{count, items}`;
* redemption preview: a single object containing fields such as `eligible`, `reason`, `reward_amount`, `credit_amount`, `credits_per_usd`, `currency`, `package`, and `global_application`.

Status items and history items may be expanded according to referral risk control, compensation, and reward rules; clients should read as needed and should not rely on aggregated fields such as `referral_url`, `recent_orders`, and `withdrawable_balance` that are not returned by the interfaces in older documentation.

> Initialization and redemption are both write operations. Production scripts should first call read-only interfaces to check the status, and persist a unique `idempotency_key` for redemption requests; do not automatically retry redemptions with unknown results.

## Related Pages

* [Get Order List](https://platform.acedata.cloud/documents/platform-order-list)
* [Manage Account Tokens](https://platform.acedata.cloud/documents/platform-token)

## Site Markup Orders

For site orders subject to the new rules, referral commissions are calculated based on the discounted base price, and the full difference from the discounted markup belongs to the site owner at the time the order is created. The two parts of the reward for the same beneficiary are merged into the original distribution record, and the distribution history displays the composition; orders without markup and historical orders retain the original rules.

For example, if the base price is 100 and the price after markup is 120, and the site owner is also the sole referrer with a percentage of 10%, the reward for this order is 10 + 20 = 30. When the site owner and referrer are not the same, they each receive their corresponding reward.

Cash settlement is still handled manually by the platform. The platform manually pays after deducting the currently available amount from the original reward account; portions already redeemed for credits cannot be paid in cash again. If a reward deficit occurs after a refund, it will first be offset by subsequent rewards.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.