Solidarity

Public stats for the solidarity fund and the caller's personal contribution summary. See Commission & solidarity for how the fund is filled. Paths are relative to the /api/v1 prefix; the stats endpoints are public, while /solidarity/me requires Authorization: Bearer {token}.

See Common errors and Commission & solidarity for how the fund is filled.

Endpoints

Method URI Role Description
GET /solidarity/stats Public Aggregate fund stats (optionally per city)
GET /solidarity/recent-deliveries Public Recent fund-backed deliveries (PII-free)
GET /solidarity/me any The caller's own contribution summary

Money fields end in _usd (decimal).

GET /solidarity/stats

Aggregate fund stats. Pass city_id to scope the totals to a single city; omit it to aggregate across all cities.

Query

Field Type Required Rules
city_id integer no scope totals to one city

Response 200

{
  "totalFundUSD": 124.5,
  "clientContributionsUSD": 62.25,
  "driverContributionsUSD": 62.25,
  "contributionsCount": 312,
  "totalLitersDonated": 18000,
  "communitiesBenefited": 4,
  "familiesBenefited": 0
}

familiesBenefited is reserved and currently always 0.

GET /solidarity/recent-deliveries

A short, PII-free feed of recent fund-backed deliveries (truncated neighborhood, liters, and the driver's first name only).

Query

Field Type Required Rules
limit integer no 1–50; defaults to 10 (out-of-range values are clamped)

Response 200

{
  "deliveries": [
    {
      "liters": 5000,
      "driverFirstName": "Carlos",
      "neighborhood": "Av. Principal, Las Mercedes",
      "date": "2026-06-26T12:40:00+00:00"
    }
  ]
}

GET /solidarity/me

The authenticated user's contribution summary, plus their driver-side contributions when they have a driver profile.

Response 200

{
  "user": {
    "name": "Ana MartĂ­nez",
    "totalSolidaryUSD": 4.2,
    "totalOrders": 12,
    "totalLitersOrdered": 36000,
    "byMonth": [ { "month": "2026-06", "totalUSD": 1.4 } ]
  },
  "driver": {
    "totalSolidaryUSD": 6.1,
    "completedOrders": 48,
    "totalLitersDelivered": 240000
  }
}

driver is null when the user has no driver profile.

Examples

# Public fund stats for a city
curl "/api/v1/solidarity/stats?city_id=1"

# My contribution summary
curl /api/v1/solidarity/me -H "Authorization: Bearer {token}"