Community Fund

Base path: /api/admin/community-fund

All endpoints require a valid auth session with admin.access permission and a non-empty tenantId in the request context.

Note: Order-flow integration (checkout donation prompt), Discord celebration message dispatch, and payment charge capture are deferred. These endpoints operate on the standalone data layer only. See docs/specs/2026-04-26-community-fund.md for the full integration roadmap.

---

GET /api/admin/community-fund/balance

Returns the current community fund balance for the authenticated tenant.

Auth: Session cookie required; admin.access permission
Tenant: Scoped via request context

Response 200

{
  "totalContributedCents": 15000,
  "totalDisbursedCents": 5000,
  "currentBalanceCents": 10000
}

---

GET /api/admin/community-fund/contributions

Returns paginated contributions for the tenant, ordered by creation date descending.

Auth: Session cookie required; admin.access permission

Query Parameters

Parameter	Type	Default	Description
limit	number	20	Number of results (1–100)
offset	number	0	Pagination offset

Response 200

{
  "items": [
    {
      "id": "...",
      "tenantId": "...",
      "customerId": "...",
      "orderId": null,
      "amountCents": 500,
      "anonymous": false,
      "createdAt": "2026-04-26T00:00:00.000Z"
    }
  ],
  "total": 42
}

---

GET /api/admin/community-fund/disbursements

Returns paginated disbursements for the tenant, ordered by creation date descending.

Auth: Session cookie required; admin.access permission

Query Parameters

Parameter	Type	Default	Description
limit	number	20	Number of results (1–100)
offset	number	0	Pagination offset

Response 200

{
  "items": [
    {
      "id": "...",
      "tenantId": "...",
      "recipientCustomerId": "...",
      "amountCents": 2500,
      "reason": "Member needed help after a difficult month.",
      "approvedBy": "admin-user-id",
      "createdAt": "2026-04-26T00:00:00.000Z"
    }
  ],
  "total": 3
}

---

POST /api/admin/community-fund/disbursements

Records an approved fund disbursement. Validates that the current balance covers the requested amount.

Auth: Session cookie required; admin.access permission
Approver: approvedBy is automatically set from the authenticated user's ID.

Request Body

Field	Type	Required	Description
recipientCustomerId	string	Yes	Customer ID of the beneficiary
amountCents	number	Yes	Disbursement amount in cents
reason	string	Yes	Human-readable reason (max 1000 chars)

Response 201

Returns the created disbursement document.

Error Responses

Status	Code	Condition
400	INSUFFICIENT_BALANCE	Current balance < requested amount
400	COMMUNITY_FUND_DISABLED	Fund is disabled for this tenant
400	(validation error)	Missing required fields
403	—	Missing auth or admin.access permission

---

GET /api/admin/community-fund/config

Returns the current community fund configuration for the tenant. Creates with defaults if no config exists yet.

Auth: Session cookie required; admin.access permission

Response 200

Returns the full CommunityFundConfig object. See docs/reference/data-dictionary.md#communityfundconfig for the field list.

---

PUT /api/admin/community-fund/config

Updates the community fund configuration for the tenant. All fields are optional (partial update).

Auth: Session cookie required; admin.access permission

Request Body (all fields optional)

Field	Type	Description
enabled	boolean	Master toggle
allowedAmountsCents	number[]	Preset donation tiers in cents (min 1 item)
customAmountAllowed	boolean	Allow custom amount entry
customAmountMinCents	number	Minimum custom amount
customAmountMaxCents	number	Maximum custom amount (must be > min)
celebrationChannelId	string|null	Discord channel ID for celebration messages
celebrationMessageTemplate	string	Template with {donor}, {amount}, {balance} placeholders
anonymousMessageTemplate	string	Template with {amount}, {balance} placeholders
anonymityAllowed	boolean	Whether customers can donate anonymously
disbursementApprovalRoles	string[]	Role slugs that may approve disbursements (min 1 item)
disclaimerText	string	Legal/tax disclaimer surfaced in admin UI

Response 200

Returns the updated CommunityFundConfig.