Admin solidarity fund

Back-office view of the solidarity fund: a live summary, the contributions ledger, and assignment of fund money to communities. Paths are relative to the /api/v1 prefix; these are back-office endpoints that require an admin token.

Requires an admin bearer token (see Admin auth). Admin only. A scoped admin only sees their own city's totals, communities, and remnant.

See Common errors and the commission & solidarity rules.

Endpoints

Method URI Access Description
GET /admin/solidarity-fund Admin Fund summary plus active communities
GET /admin/solidarity-fund/contributions Admin Paginated contributions ledger (page-based)
POST /admin/solidarity-fund/assign Admin Assign fund money to a community

GET /admin/solidarity-fund

Live summary of the fund plus the list of ACTIVE communities and their assignment progress.

Response 200

{
  "summary": {
    "total_fund_usd": 1240.5,
    "client_contributions_usd": 620.25,
    "driver_contributions_usd": 620.25,
    "assigned_usd": 800.0,
    "remanent_usd": 440.5,
    "contributions_count": 3120,
    "total_liters_donated": 15600000
  },
  "communities": [
    {
      "id": 7,
      "name": "Barrio La Esperanza",
      "description": "Pozo comunitario",
      "status": "ACTIVE",
      "target_amount_usd": 500.0,
      "assigned_amount_usd": 320.0,
      "remaining_amount_usd": 180.0,
      "progress_percent": 64.0
    }
  ]
}

GET /admin/solidarity-fund/contributions

Paginated ledger of solidary contributions, newest first. Page-based; see Pagination → page-based.

Query

Field Type Required Rules
from date no filter created_at >=
to date no filter created_at <=; >= from
community_id integer no must exist in communities
q string no ≤ 100 chars
limit integer no 1–100, default 25
page integer no ≥ 1, default 1

Response 200

{
  "items": [
    {
      "id": 991,
      "order_id": 42,
      "client_amount_usd": 0.2,
      "driver_amount_usd": 0.16,
      "aguita_amount_usd": 0.0,
      "total_amount_usd": 0.36,
      "is_allocated": true,
      "allocated_to": 7,
      "created_at": "2026-06-26T12:40:00+00:00",
      "order_delivered_at": "2026-06-26T12:40:00+00:00"
    }
  ],
  "meta": { "total": 3120, "per_page": 25, "current_page": 1, "last_page": 125 }
}

POST /admin/solidarity-fund/assign

Assigns money from the fund to a community. The amount must not exceed the city's remnant, and the community must be ACTIVE.

Request body

Field Type Required Rules
community_id integer yes must exist in communities
amount_usd number yes ≥ 0.01

Response 200

{
  "community": {
    "id": 7,
    "name": "Barrio La Esperanza",
    "assigned_amount_usd": 420.0,
    "target_amount_usd": 500.0,
    "remaining_amount_usd": 80.0,
    "progress_percent": 84.0
  },
  "fund": {
    "total_fund_usd": 1240.5,
    "assigned_usd": 900.0,
    "remanent_usd": 340.5
  }
}

Errors

Status Body When
404 { "error": "NotFound" } Community not found or outside the admin's cities
422 { "error": "InsufficientFunds", "message": "…", "remanent_usd": 340.5, "requested_usd": 500 } Amount exceeds the city's remnant
422 { "error": "CommunityInactive", "message": "…" } The community is not ACTIVE