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)

{
  "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)

{
  "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

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

{
  "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)

{
  "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

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

# 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

Commissions

Commissions

Endpoints

Status enum

`GET /dapp/commissions` — list records

Query parameters

Canonical payload

Response shape (verified)

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

Canonical payload

Response shape (verified)

Display patterns

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

Canonical payload

Response shape

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

Canonical payload

Response shape (verified)

Common patterns

Render a “what am I owed” widget

Reconcile against orders

Polling for commission accrual

Caching guidance

See also

​Commissions

​Endpoints

​Status enum

​GET /dapp/commissions — list records

​Query parameters

​Canonical payload

​Response shape (verified)

​GET /dapp/commissions/summary — aggregate by status

​Canonical payload

​Response shape (verified)

​Display patterns

​GET /dapp/commissions/managers — sub-manager commissions

​Canonical payload

​Response shape

​GET /dapp/commissions/managers/summary — manager-team aggregate

​Canonical payload

​Response shape (verified)

​Common patterns

​Render a “what am I owed” widget

​Reconcile against orders

​Polling for commission accrual

​Caching guidance

​See also

Commissions

Endpoints

Status enum

`GET /dapp/commissions` — list records

Query parameters

Canonical payload

Response shape (verified)

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

Canonical payload

Response shape (verified)

Display patterns

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

Canonical payload

Response shape

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

Canonical payload

Response shape (verified)

Common patterns

Render a “what am I owed” widget

Reconcile against orders

Polling for commission accrual

Caching guidance

See also