Campaign Analytics

Per-campaign donation analytics with trend data, top donors, and breakdowns.

GET /api/reporting/campaign/:id

Campaign Analytics

cURL

curl --request GET \
  --url https://api.example.com/api/reporting/campaign/:id

200

{
  "campaign": {
    "id": "<string>",
    "title": "<string>",
    "goalAmountCents": {},
    "raisedAmountCents": 123,
    "donationCount": 123,
    "status": "<string>",
    "startDate": {},
    "endDate": {}
  },
  "summary": {
    "totalRaisedCents": 123,
    "donationCount": 123,
    "avgGiftCents": 123,
    "uniqueDonors": 123,
    "recurringCount": 123,
    "oneTimeCount": 123
  },
  "trend": [
    {
      "date": "<string>",
      "amountCents": 123,
      "count": 123
    }
  ],
  "topDonors": [
    {
      "donorId": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "totalCents": 123,
      "count": 123
    }
  ],
  "paymentMethods": [
    {
      "method": "<string>",
      "count": 123,
      "amountCents": 123
    }
  ],
  "frequencyBreakdown": [
    {
      "frequency": "<string>",
      "count": 123,
      "amountCents": 123
    }
  ],
  "topSources": [
    {
      "source": "<string>",
      "count": 123,
      "amountCents": 123
    }
  ],
  "peakHour": {}
}

Campaign Analytics

Returns detailed analytics for a single campaign. Includes a daily donation trend, top donor list, payment method breakdown, frequency breakdown, UTM source breakdown, and peak donation hour.

Path Parameters

id · string · required

The campaign ID to retrieve analytics for.

Query Parameters

orgId · string · required

The organization ID. Used to verify the authenticated user’s access to this campaign.

startDate · string

ISO 8601 start date for the daily trend window (e.g., "2026-02-01"). Defaults to 30 days ago.

endDate · string

ISO 8601 end date for the daily trend window (e.g., "2026-03-04"). Defaults to today.

Authentication

Requires a valid Clerk session JWT in the Authorization: Bearer header. The authenticated user must be a member of the organization that owns this campaign.

Response

campaign · object

Core campaign metadata.

Show Campaign fields

id · string

Campaign ID.

title · string

Campaign title.

goalAmountCents · integer | null

Fundraising goal in cents.

raisedAmountCents · integer

Running total raised in cents (all-time, not filtered by date range).

donationCount · integer

Total succeeded donation count (all-time).

status · string

Campaign status: "DRAFT", "ACTIVE", "PAUSED", or "ENDED".

startDate · string | null

ISO 8601 campaign start date.

endDate · string | null

ISO 8601 campaign end date.

summary · object

Aggregated totals across all succeeded donations for this campaign (all-time, not filtered by date range).

Show Summary fields

totalRaisedCents · integer

Total amount raised in cents.

donationCount · integer

Total number of succeeded donations.

avgGiftCents · integer

Average donation amount in cents.

uniqueDonors · integer

Number of unique donors who have given to this campaign.

recurringCount · integer

Number of recurring donations (non-one-time frequency).

oneTimeCount · integer

Number of one-time donations.

trend · array

Daily donation data for the requested date range. One entry per calendar day, pre-filled with zeros for days with no donations.

Show Trend entry fields

date · string

Date in YYYY-MM-DD format.

amountCents · integer

Total donated on this day in cents.

count · integer

Number of donations on this day.

topDonors · array

Up to 10 top donors by total amount given to this campaign. Last names are truncated to an initial for privacy.

Show Top donor entry fields

donorId · string

Internal donor ID.

firstName · string

Donor first name, or "Anonymous" if not found.

lastName · string

Donor last initial followed by a period (e.g., "S."), for privacy.

totalCents · integer

Total amount given to this campaign in cents.

count · integer

Number of donations to this campaign.

paymentMethods · array

Breakdown of succeeded donations by payment method.

Show Payment method entry fields

method · string

Payment method: "CARD", "ACH", "APPLE_PAY", "GOOGLE_PAY", or "UNKNOWN".

count · integer

Number of donations via this method.

amountCents · integer

Total donated via this method in cents.

frequencyBreakdown · array

Breakdown of succeeded donations by giving frequency.

Show Frequency entry fields

frequency · string

Frequency: "ONE_TIME", "MONTHLY", "QUARTERLY", or "ANNUAL".

count · integer

Number of donations at this frequency.

amountCents · integer

Total donated at this frequency in cents.

topSources · array

Up to 5 top UTM sources by total amount raised, for donations that have a utmSource value.

Show Source entry fields

source · string

UTM source value (e.g., "email", "facebook").

count · integer

Number of donations from this source.

amountCents · integer

Total donated from this source in cents.

peakHour · integer | null

The UTC hour of day (0–23) that received the most donations across all time. null if the campaign has no donations.

Example

curl "https://givelink-api-production.up.railway.app/api/reporting/campaign/clx9876543210?orgId=clxabc123456&startDate=2026-02-01&endDate=2026-03-04" \
  -H "Authorization: Bearer <clerk-session-jwt>"

{
  "campaign": {
    "id": "clx9876543210",
    "title": "Spring 2026 Annual Fund",
    "goalAmountCents": 5000000,
    "raisedAmountCents": 1245000,
    "donationCount": 87,
    "status": "ACTIVE",
    "startDate": "2026-03-01T00:00:00.000Z",
    "endDate": "2026-06-30T23:59:59.000Z"
  },
  "summary": {
    "totalRaisedCents": 1245000,
    "donationCount": 87,
    "avgGiftCents": 14310,
    "uniqueDonors": 74,
    "recurringCount": 23,
    "oneTimeCount": 64
  },
  "trend": [
    { "date": "2026-02-01", "amountCents": 0, "count": 0 },
    { "date": "2026-02-02", "amountCents": 25000, "count": 2 },
    { "date": "2026-02-03", "amountCents": 100000, "count": 7 }
  ],
  "topDonors": [
    { "donorId": "clxdonor001", "firstName": "Margaret", "lastName": "T.", "totalCents": 250000, "count": 1 },
    { "donorId": "clxdonor002", "firstName": "Robert", "lastName": "K.", "totalCents": 100000, "count": 2 }
  ],
  "paymentMethods": [
    { "method": "CARD", "count": 70, "amountCents": 900000 },
    { "method": "ACH", "count": 17, "amountCents": 345000 }
  ],
  "frequencyBreakdown": [
    { "frequency": "ONE_TIME", "count": 64, "amountCents": 800000 },
    { "frequency": "MONTHLY", "count": 23, "amountCents": 445000 }
  ],
  "topSources": [
    { "source": "email", "count": 45, "amountCents": 650000 },
    { "source": "facebook", "count": 12, "amountCents": 180000 }
  ],
  "peakHour": 19
}

Error Responses

Status	Error	Description
400	Validation failed	orgId is missing or invalid.
401	Unauthorized	Missing or invalid Authorization header.
403	Forbidden	Authenticated user is not a member of the specified org.
404	Campaign not found	No campaign with this ID exists for the given org.