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

# Commissions

# Commissions

> **Endpoint reference: ✅ Verified live against production on 10 May 2026.**
> Commissions are the holder's earnings from sold orders. Each delivered order generates a commission record tied to that holder's NFT. Dr Green pays commissions in either USD (fiat) or ETH (on-chain), so amounts are tracked in both currencies on every record.

***

## Endpoints

| Method | Path                                 | Auth          | Description                                           |
| ------ | ------------------------------------ | ------------- | ----------------------------------------------------- |
| `GET`  | `/dapp/commissions`                  | API-key + sig | List individual commission records, paginated         |
| `GET`  | `/dapp/commissions/summary`          | API-key + sig | Aggregate paid/pending in USD and ETH                 |
| `GET`  | `/dapp/commissions/managers`         | API-key + sig | Sub-managers' commissions (for holders running teams) |
| `GET`  | `/dapp/commissions/managers/summary` | API-key + sig | Manager-team aggregates                               |

***

## Status enum

| Status    | Meaning                                    |
| --------- | ------------------------------------------ |
| `PENDING` | Commission accrued but not yet paid out    |
| `PAID`    | Paid out (settlement on-chain or via fiat) |

(Other states may exist — `PROCESSING`, `FAILED` — but only `PENDING` and `PAID` were observed live.)

***

## `GET /dapp/commissions` — list records

Each record represents one order's commission. Paginated.

### Query parameters

| Name            | Type          | Default | Notes                              |
| --------------- | ------------- | ------- | ---------------------------------- |
| `page`          | integer       | `1`     |                                    |
| `limit`         | integer       | `10`    |                                    |
| `paymentStatus` | string        | —       | Filter by `PENDING` or `PAID`      |
| `userId`        | string (UUID) | —       | Filter to one user (the recipient) |

### Canonical payload

`urlencode(query)` if any present, else `"{}"`.

### Response shape (verified)

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "commissions": [
      {
        "id": "0871c46e-78f1-418c-bab5-75146820fe3d",
        "amountInDollar": 3.59,
        "amountInEth": null,
        "userId": "c317cade-63c8-4b59-ba67-1512297417f2",
        "paymentStatus": "PAID",
        "createdAt": "2025-05-13T15:36:29.276Z",
        "updatedAt": "2025-09-04T13:52:04.136Z",
        "order": {
          "id": "cb8a2384-3505-4693-8f27-a52aa840f59d",
          "agentProfit": 3.59,
          "totalAmount": 9.09,
          "orderStatus": "DELIVERED",
          "currency": null,
          "agentProfitInUSD": null,
          "orderLogs": [
            { "activity": "Delivered", "createdAt": "2025-05-13T15:43:16.964Z" }
          ],
          "client": {
            "id": "316682f6-6909-461d-b505-68fa6afd7917",
            "firstName": "Reza",
            "lastName": "Van Oudtshoorn",
            "email": "rezavanoudt@gmail.com"
          },
          "totalQuantity": 1
        },
        "isPayable": true
      }
    ],
    "pageMetaDto": { "page": "1", "take": 10, "itemCount": 4, "pageCount": 1, "hasPreviousPage": false, "hasNextPage": false }
  }
}
```

> 🪲 **`amountInEth` is null on PAID records** in observed data — even though the field exists. Either ETH wasn't the payout rail for those, or it's a backend gap. Defensively handle null. Display `amountInDollar` as the primary figure.

> 🪲 **`order.currency` and `order.agentProfitInUSD` are both null** in observed records. They're declared in the response but populated inconsistently. Don't rely on either for display — use `order.totalAmount` (USD) and `order.agentProfit`.

> 🪲 **`order.orderLogs[]`** is an audit trail with `activity` strings like `"Delivered"`, `"Approved"`, `"Created"`. Useful for showing a per-order timeline if you surface order history.

> 🪲 **`isPayable`** appears to gate whether the holder can claim — `true` after the order is delivered, `false` while in earlier states. Confirm with Dr Green for full state machine. 🔒

***

## `GET /dapp/commissions/summary` — aggregate by status

The headline numbers for a holder's earnings dashboard.

### Canonical payload

`{}`

### Response shape (verified)

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "commissionSummary": {
      "PENDING": {
        "amountInDollar": 0,
        "amountInEth": 0
      },
      "PAID": {
        "amountInDollar": 25.95,
        "amountInEth": 0.011156
      },
      "totalInDollar": 25.95
    }
  }
}
```

> ⚠️ **The wrapper field is `commissionSummary`, not `summary`.** Other endpoints use `summary`. Mind the inconsistency.

> 🪲 **`totalInDollar` is just `PENDING.amountInDollar + PAID.amountInDollar`.** No equivalent `totalInEth`. If you need it, sum yourself.

### Display patterns

```ts theme={null}
function formatCommissionSummary(s: CommissionSummary): string {
  const usd = (n: number) => `$${n.toFixed(2)}`;
  const eth = (n: number) => `${n.toFixed(6)} ETH`;
  return `Paid: ${usd(s.PAID.amountInDollar)} (${eth(s.PAID.amountInEth)}) · Pending: ${usd(s.PENDING.amountInDollar)}`;
}
```

***

## `GET /dapp/commissions/managers` — sub-manager commissions

For holders who run a team. Returns commissions earned by managers under this holder. Paginated.

### Canonical payload

`urlencode(query)` if pagination params, else `"{}"`.

### Response shape

```json theme={null}
{
  "data": {
    "managers": [ /* manager records */ ],
    "pageMetaDto": { ... }
  }
}
```

🔒 The shape of an individual manager record is **not yet captured live** — the test holder for verification has no managers (`itemCount: 0`). Backend code suggests fields include `userId`, `firstName`, `lastName`, `email`, plus per-manager commission stats.

***

## `GET /dapp/commissions/managers/summary` — manager-team aggregate

### Canonical payload

`{}`

### Response shape (verified)

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "summary": {
      "totalAgents": 0,
      "activeAgents": 0,
      "inActiveAgents": 0,
      "totalSales": 70,
      "totalCommission": 0,
      "totalPaidCommission": 0,
      "totalPendingCommission": 0
    }
  }
}
```

> 🪲 **`inActiveAgents`** (camelCase split inconsistently — usual would be `inactiveAgents`). Document the field name as-is.

> 🪲 **All `totalCommission` figures are USD only here** — no ETH equivalent at the manager-summary level.

***

## Common patterns

### Render a "what am I owed" widget

```ts theme={null}
const { commissionSummary } = await getCommissionsSummary();
const totalUnpaid = commissionSummary.PENDING.amountInDollar;
const totalEarned = commissionSummary.totalInDollar;
const paidPercent = totalEarned > 0
  ? (commissionSummary.PAID.amountInDollar / totalEarned) * 100
  : 0;
```

### Reconcile against orders

```python theme={null}
# Sum delivered orders' agentProfit; should equal commissionSummary.totalInDollar
async def reconcile_commissions():
    orders = await get_all_delivered_orders()  # paginate through
    expected = sum(o["agentProfit"] for o in orders)
    actual = (await get_commissions_summary())["commissionSummary"]["totalInDollar"]
    return expected, actual, abs(expected - actual) < 0.01  # tolerance for rounding
```

### Polling for commission accrual

Commissions appear after Dr Green marks an order `DELIVERED`. Poll `/dapp/commissions/summary` every 15 minutes when an order has been recently approved; switch to longer intervals once delivery confirmed.

***

## Caching guidance

| Endpoint                    | TTL |
| --------------------------- | --- |
| Commission list (paginated) | 5m  |
| Commission summary          | 5m  |
| Manager list / summary      | 5m  |

***

## See also

* [Orders](./orders.md) — every commission references an `order`
* [Sales](./sales.md) — commissions accrue from won sales
* [Dashboard](./dashboard.md) — top-line numbers including commissions