Wallet

Creator wallet balances, transaction history, affiliate earnings view, payout requests, and dashboard KPI summaries used for creator analytics.

---

Wallet resource

Current wallet responses include:

Field	Type	Notes
available	integer	Funds ready for payout.
hold	integer	Funds currently on hold.
pending	integer	Funds currently in payout processing.
total	integer	Aggregate wallet total.
referral_revenue	integer	Affiliate revenue amount.
cashout_available	boolean	Whether available is positive.
transactions	paginated collection	Wallet transaction list excluding RELEASE_PENDING.

---

GET /api/dashboard/summary

Pre-aggregated dashboard KPIs for the authenticated creator (content counts, link clicks, unlocks, product revenue totals, top-performing products, wallet buckets).

• Auth required: Yes
• Roles: Authenticated creator with a wallet
• Content type: none

Response shape notes

The payload extends the historical single-account shape with:

Field	Type	Notes
currency_unified	boolean	For one account, always true.
accounts	array	One object per creator in the summary (single-account: one element) with user_id, email, display_name, currency_id, currency_code, and wallet_balance.
wallet_balance	object or null	Top-level aggregate wallet buckets when every account shares the same currency_id; otherwise null (use per-account accounts[].wallet_balance).
total_content_items	integer	Count of qualifying products with complete media.
total_link_clicks	integer	Sum of short-link views.
total_unlocks	integer	Sum of product unlocks.
total_product_revenue	integer	Sum of total_earnings (minor units).
overall_conversion_rate	number	Derived from totals.
top_performing	array	Up to five products ranked by conversion with revenue and thumbnail metadata.

Clients that need full wallet transaction history for charts should still call GET /api/wallet with the relevant bearer token per account.

---

POST /api/dashboard/summary/aggregate

Same KPI aggregation as GET /api/dashboard/summary, but merged across multiple creator accounts.

• Auth required: Yes (primary account’s api token in Authorization)
• Roles: Authenticated creator with a wallet on every resolved account
• Content type: application/json

Request body

Field	Type	Required	Notes
additional_tokens	string[]	No	Deprecated for masters. Ignored when the bearer is a master account; aggregation uses persisted links from account_group_members instead. For standalone accounts, ignored (only the bearer is aggregated). Child accounts must not send this field → 403.

The primary user is always included from the bearer token. Master accounts automatically include every persisted linked child from GET /api/user/linked-accounts / login account_group.linked_accounts.

Important semantics

• Trust model: Combined metrics for multiple creators are allowed only when the backend recognizes a master → child link (or the caller is aggregating only themselves). Holding another user’s token in additional_tokens does not grant access.
• Currency: If combined accounts use different currency_id values, currency_unified is false and root wallet_balance is null; use each accounts[].wallet_balance and interpret total_product_revenue with care across currencies.

Error examples

Child sent additional_tokens:

{
  "success": false,
  "errors_message": "Child accounts cannot aggregate other accounts.",
  "data": null
}

---

GET /api/wallet

Return wallet balances and creator wallet transactions.

• Auth required: Yes
• Roles: Authenticated creator with wallet

Query parameters

Parameter	Type	Required
page	integer	No
limit	integer	No

Success response example

{
  "success": true,
  "errors_message": null,
  "data": {
    "available": 15000,
    "hold": 3000,
    "pending": 5000,
    "total": 23000,
    "referral_revenue": 2500,
    "cashout_available": true,
    "transactions": {
      "data": [
        {
          "id": 1,
          "amount": 550,
          "type": "affiliate_earning",
          "created_at": "2026-04-20 10:15:00",
          "title": "Money for a photo"
        }
      ]
    }
  }
}

---

GET /api/wallet/affiliate

Return affiliate-only revenue and affiliate wallet transactions.

• Auth required: Yes
• Roles: Authenticated creator with wallet

Query parameters

Parameter	Type	Required
page	integer	No
limit	integer	No

Success response example

{
  "success": true,
  "errors_message": null,
  "data": {
    "referral_revenue": 2500,
    "transactions": {
      "data": [
        {
          "id": 33,
          "amount": 220,
          "type": "affiliate_earning",
          "created_at": "2026-04-20 10:15:00",
          "title": "Referral revenue"
        }
      ]
    }
  }
}

---

POST /api/wallet/cashout

Create a payout request for the creator's full currently available balance.

• Auth required: Yes
• Roles: Authenticated creator with wallet
• Content type: no body required

Request body

No request body is currently required.

Success response example

{
  "success": true,
  "errors_message": null,
  "data": "Cashout created successfully"
}

Error example

{
  "success": false,
  "errors_message": "No available funds",
  "data": null
}

Side effects

• backend creates payout state from current wallet
• current implementation uses the wallet service and does not ask the API client for a payout amount

---

Transaction behavior

Current public wallet responses expose transaction items with:

Field	Type
id	integer
amount	integer
type	string
created_at	string
title	string or null

Do not assume every internal payout/admin transaction type is exposed publicly.

---

Related

• Auth (batch login and app sessions)
• Affiliate
• Wallet & Payouts