Donorbox

Aggregate donations for the current Donorbox organization via GET /api/v2/insights/donations/aggregations.json. PREFER THIS TOOL over paginating list_donations for any count, sum, trend, ranking, or breakdown question. It is far more token-efficient and returns complete results in a single request regardless of data volume. Required: date_from, date_to (YYYY-MM-DD). No maximum date range — a single request can cover any span (e.g. all-time, 5+ years). Very large ranges on high-volume orgs may hit the Postgres 10-second statement timeout and return a 400 with code "timeout"; narrow the range or remove a group_by dimension if that happens. Metrics: donations_count, donors_count, amount_cents_sum, usd_amount_cents_sum. group_by: date, form_id, donation_type, plan_interval, currency, status, donor_id, donor_state, donor_city, donor_zip_code, donor_country (max 3). granularity: day/week/month/quarter/year (required only when group_by includes date; default month). Filters: status (default [paid]), donation_type, currency, plan_interval, form_id (campaign), donor_id, donor_city, donor_state, donor_zip_code, donor_country. Sorting: use sort_by + order to rank results server-side before the limit is applied. sort_by must be one of the requested metrics or group_by dimensions. order is "desc" (default) or "asc". Always set sort_by when using limit for top-N queries — without it, limit slices an arbitrary subset, not the top rows. No filter required for any group_by dimension. When group_by includes donor_id with no other scoping, the API caps results at 500 rows automatically. DATA MODEL — Donations and event ticket purchases are separate datasets linked by donor_id (the same supporter record in both). Questions that combine giving rank with ticket-buying activity are cross-domain joins, not single-tool queries. CROSS-DOMAIN QUERIES — do not answer from this tool alone when the question spans both donations and ticket purchases. Complete the full chain: rank or filter in each domain, intersect on donor_id, then resolve names via list_donors. Do not substitute explanation for missing purchase or identity steps. QUERY PLANNING HEURISTIC — when a question spans two domains (e.g. "major donors who bought tickets"), treat it as a join on donor_id: rank donors here, then call donorbox_aggregate_purchases to confirm ticket purchases for those donor_ids. TOOL SELECTION (donations side): • Top donors by giving, campaign trends, geographic breakdowns → this tool • Top ticket buyers, event revenue, buyer averages → donorbox_aggregate_purchases • Major donors who also bought tickets → this tool THEN donorbox_aggregate_purchases • Individual donation or purchase line items → list_donations / list_purchases Recipe — "Which major donors purchased event tickets?": Step 1 (here) — rank major donors by giving: metrics=["amount_cents_sum","donations_count"], group_by=["donor_id"], sort_by="amount_cents_sum", order="desc", limit=50, date_from=..., date_to=... Step 2 — call donorbox_aggregate_purchases with those donor_ids (max 50 per request; batch if needed). Buyer = donor_id (who paid), not attendee_id on tickets: metrics=["purchases_count","tickets_count","amount_cents_sum"], group_by=["donor_id"], donor_id=[ids from step 1], date_from=..., date_to=... Step 3 — keep rows where purchases_count > 0 (intersection) Step 4 — list_donors(ids: [...], summary: true) for names (mandatory) Step 5 (optional) — list_purchases(donor_id: <id>) for per-purchase/event detail MANDATORY ID RESOLUTION — when aggregate rows contain donor_id or form_id values, you MUST resolve them to human-readable names before presenting results to the user: • donor_id → call list_donors(ids: [<id>, ...], summary: true) to get name and masked email. Pass up to 100 IDs in a single call. • form_id → call list_campaigns() and match on id to get campaign name. Never surface a raw numeric ID to the user without its corresponding name. Example — top 10 donors by lifetime giving: metrics=["donations_count","amount_cents_sum"], group_by=["donor_id"], sort_by="amount_cents_sum", order="desc", limit=10, date_from="2020-01-01", date_to="2026-12-31" → then call list_donors(ids: [<donor_id>, ...], summary: true) to resolve names Example — donations by campaign per month: metrics=["donations_count","amount_cents_sum"], group_by=["date","form_id"], granularity="month", date_from="2026-01-01", date_to="2026-12-31" → then call list_campaigns() to resolve form_id → campaign name Example — donations by state: metrics=["donations_count","amount_cents_sum"], group_by=["donor_state"], sort_by="amount_cents_sum", date_from="2026-01-01", date_to="2026-12-31" Example — per-donor breakdown for Texas donors: metrics=["donations_count","amount_cents_sum"], group_by=["donor_id"], donor_state="TX", sort_by="amount_cents_sum", date_from="2026-01-01", date_to="2026-12-31" → then call list_donors(ids: [<donor_id>, ...], summary: true) to resolve names

Aggregate event ticket purchase totals (counts, ticket counts, revenue) grouped by date, event, status, etc. Use for purchase/ticket revenue and volume analytics over a date range. Wraps GET /api/v2/insights/purchases/aggregations.json. PREFER THIS TOOL over paginating list_purchases for any count, sum, trend, ranking, or breakdown question about event ticket purchases. It is far more token-efficient and returns complete results in a single request regardless of data volume. Required: date_from, date_to (YYYY-MM-DD). The range must be <= 366 days; a wider span returns a 400 with code "range_too_large" — split the request into yearly windows. Very large/high-volume ranges may also hit the Postgres statement timeout and return a 400 with code "timeout"; narrow the range or remove a group_by dimension if that happens. Metrics: purchases_count, buyers_count, tickets_count, price_cents_sum, amount_cents_sum, usd_amount_cents_sum, donation_amount_cents_sum, cover_fee_amount_cents_sum, discount_amount_cents_sum, app_fee_cents_sum, stripe_fee_cents_sum, net_amount_cents_sum. Default metrics: [purchases_count, amount_cents_sum]. CURRENCY: amount_cents_sum is in the org's default currency (meta.currency); usd_amount_cents_sum is in USD. All other *_cents metrics are in each purchase's native currency, so only meaningful when scoped to a single currency (filter currency=USD) or grouped by currency. For cross-currency rollups use amount_cents_sum or usd_amount_cents_sum. price_cents (and price_cents_sum) already includes the optional checkout donation and is net of discount; subtract donation_amount_cents_sum to approximate ticket-only revenue. DISTINCT COUNTS (buyers_count): buyers_count is omitted from totals because distinct buyers are not additive across grouped rows — e.g. with group_by=["date"], each row's buyers_count is unique buyers in that month and summing rows double-counts people who bought in multiple months. That does NOT mean buyer totals are unavailable; change the grouping instead. QUERY PLANNING HEURISTIC — when a distinct-count metric is omitted from totals, group by the entity being counted. The resulting row_count often becomes the distinct count. Applies here (donor_id → unique buyers) and generally (event_id → events, promo_code_id → codes, etc.). BUYER-LEVEL ANALYTICS — for unique buyer count, averages per buyer, buyer rankings, or lifetime-style buyer metrics over a date range, use group_by=["donor_id"]. Each row is exactly one unique buyer. When not truncated: • unique_buyers = row_count • average_tickets_per_buyer = totals.tickets_count / row_count • average_revenue_per_buyer = totals.amount_cents_sum / row_count (or usd_amount_cents_sum) With group_by=["date"], buyers_count per row is still useful for per-period unique buyers, but never sum buyers_count across rows to infer a total. COMMON ANALYTICS RECIPES: Average revenue per buyer: metrics=["amount_cents_sum"], group_by=["donor_id"], date_from=..., date_to=... → average_revenue_per_buyer = totals.amount_cents_sum / row_count Average tickets per buyer: metrics=["tickets_count"], group_by=["donor_id"], date_from=..., date_to=... → average_tickets_per_buyer = totals.tickets_count / row_count Top buyers by spend: metrics=["amount_cents_sum","tickets_count"], group_by=["donor_id"], sort_by="amount_cents_sum", order="desc", limit=10, date_from=..., date_to=... → call list_donors(ids: [...]) to resolve donor_id → name Unique buyers in range (total, not per month): metrics=["purchases_count"], group_by=["donor_id"], date_from=..., date_to=... → unique_buyers = row_count (check meta.truncated; narrow range if capped) DATA MODEL — Donations and event ticket purchases are separate datasets linked by donor_id. On purchases, donor_id is the buyer (who paid). attendee_id on list_tickets is the ticket holder and may differ on multi-ticket orders. CROSS-DOMAIN QUERIES — do not answer from this tool alone when the question combines donation giving rank with ticket purchases. Complete the full chain: rank donors in donorbox_aggregate_donations, filter or intersect here on donor_id, then resolve names via list_donors. Do not substitute explanation for missing donation-ranking or identity steps. QUERY PLANNING HEURISTIC — when a question spans giving and tickets, it is a join on donor_id. "Top ticket buyers" is answered here alone; "major donors who bought tickets" requires donorbox_aggregate_donations first, then this tool to confirm purchases. TOOL SELECTION (purchases side): • Counts, rankings, buyer averages, event revenue trends → this tool • Top donors by donation giving → donorbox_aggregate_donations • Major donors who also bought tickets → donorbox_aggregate_donations THEN this tool • Individual purchase records (events, tickets, payment detail) → list_purchases Recipe — "Which major donors purchased event tickets?": Step 1 — call donorbox_aggregate_donations to rank major donors by giving: metrics=["amount_cents_sum","donations_count"], group_by=["donor_id"], sort_by="amount_cents_sum", order="desc", limit=50, date_from=..., date_to=... Step 2 (here) — confirm ticket purchases for those donor_ids (max 50 per request; split into batches if step 1 returned more): metrics=["purchases_count","tickets_count","amount_cents_sum"], group_by=["donor_id"], donor_id=[ids from step 1], date_from=..., date_to=... Step 3 — keep rows where purchases_count > 0 Step 4 — list_donors(ids: [...], summary: true) for names (mandatory) Step 5 (optional) — list_purchases(donor_id: <id>) for event/ticket line-item detail group_by: date, event_id, status, currency, payment_method_type, donor_id, offline, promo_code_id (max 3). granularity: day/week/month/quarter/year (only when group_by includes date; default month). Filters: status (default [paid]), currency, payment_method_type, event_id, donor_id, promo_code_id, offline (true = offline only, false = online only, omit = both). Sorting: use sort_by + order to rank results server-side before the limit is applied. sort_by must be one of the requested metrics or group_by dimensions. order is "desc" (default) or "asc". Always set sort_by when using limit for top-N queries — without it, limit slices an arbitrary subset, not the top rows. MANDATORY ID RESOLUTION — when aggregate rows contain donor_id or event_id values, you MUST resolve them to human-readable names before presenting results to the user: • donor_id → call list_donors(ids: [<id>, ...], summary: true) to get name and masked email. • event_id → call list_events() and match on id to get the event name. Never surface a raw numeric ID to the user without its corresponding name. Example — purchases and revenue by event per month: metrics=["purchases_count","amount_cents_sum"], group_by=["date","event_id"], granularity="month", date_from="2026-01-01", date_to="2026-12-31" → then call list_events() to resolve event_id → event name Example — top 10 events by ticket revenue: metrics=["purchases_count","tickets_count","amount_cents_sum"], group_by=["event_id"], sort_by="amount_cents_sum", order="desc", limit=10, date_from="2026-01-01", date_to="2026-12-31" → then call list_events() to resolve event_id → event name Example — online vs offline split: metrics=["purchases_count","amount_cents_sum"], group_by=["offline"], date_from="2026-01-01", date_to="2026-12-31" Example — average revenue per buyer and top 10 buyers: metrics=["amount_cents_sum","tickets_count"], group_by=["donor_id"], sort_by="amount_cents_sum", order="desc", limit=10, date_from="2026-01-01", date_to="2026-12-31" → average_revenue_per_buyer = totals.amount_cents_sum / row_count → call list_donors(ids: [<donor_id>, ...]) to resolve names

Fetch a single donation by id (still minimal projection). Returns not_found if it does not belong to the authenticated org. Implemented as a filtered list because the upstream API does not expose a show action; the org-scope filter on the index enforces tenancy.

List fundraising campaigns for the authenticated Donorbox org. Returns id, name, slug, type, currency, goal amounts, total raised, donation count, and additional questions. Use this tool to discover campaign IDs, names, and fundraising totals. Filter by id for a specific campaign, by ids for bulk lookup (up to 100), or by name for a partial match. Note: event-type campaigns also appear in results; use list_events to fetch only ticketed events.

List donations for the authenticated Donorbox org. By default (no status param) returns only paid and refunded donations — the safe set for financial reporting. Pass status=paid for paid-only, or status=pending / status=failed to investigate problem donations. Filter further by date range, campaign, donor, payment method, plan interval, or amount. Use recurring=true for subscription donations and recurring=false for one-time gifts. Sorted by donation_date. Returns a minimal projection per donation; call get_donation for full detail. ANALYTICS NOTE: For count, sum, trend, or ranking questions prefer donorbox_aggregate_donations — it returns complete data in one request without pagination and consumes far fewer tokens. PAGINATION: Each response includes returned_count, total_count (when available), and has_more. If has_more is true, call again with next_cursor to retrieve the next page. Repeat until has_more is false to ensure complete data coverage. Default page size is 25; increase with limit (max 100). DONOR ENRICHMENT: Each donation includes a donor sub-object with id and email_masked. Whenever the conversation focuses on one or more specific donors (e.g. showing a profile, following up on a donor, or any question about "who is this donor"), call list_donors with those donor id(s) to retrieve full contact details (name, masked email, location, donation count, last donation date, lifetime total).

List donors for the authenticated Donorbox org. Returns a normalized record per donor with PII-safe values. Filter by identity (id, email, name), donor type, date of last donation, or lifetime donation count. Use donor_type=entity for organizational or legal-entity supporters; donor_type=individual for personal donors. Use donations_count_min/max to find high-value or lapsed donors. Use last_donation_at_from/to to find donors active in a date window. PAGINATION: Each response includes returned_count, total_count (when available), and has_more. If has_more is true, increment page to retrieve the next batch. Repeat until has_more is false for complete data coverage. Default page size is 25; increase with per_page (max 100). ENRICHMENT USE CASE: This is the canonical endpoint for resolving donor identity. Other tools (list_donations, list_plans, list_purchases, list_tickets, donorbox_aggregate_donations, donorbox_aggregate_purchases) return donor sub-objects or raw donor_id values. Call this tool with those id(s) whenever the conversation requires full donor details — name, masked email, location, donation count, last donation date, lifetime total — and always present results with both donor name and email alongside the id. When you have a known list of donor IDs (e.g. from aggregate joins, list_donations, or list_purchases output), pass them as ids to resolve all names and details in one call instead of paging through index results. For aggregate enrichment where you only need name and email alongside each id, pass summary=true with ids to get compact records and lower token usage; omit summary (default) when the user needs full profiles. CROSS-DOMAIN IDENTITY — final step for questions spanning donations and ticket purchases (e.g. "major donors who bought tickets"): 1. donorbox_aggregate_donations — rank major donors by giving (group_by donor_id) 2. donorbox_aggregate_purchases — confirm purchases for those donor_ids 3. intersect on donor_id (keep purchases_count > 0) 4. list_donors(ids: [...], summary: true) — mandatory before presenting results 5. list_purchases(donor_id: ...) — optional, for line-item detail only Never answer cross-domain questions with raw donor_id values or donation rankings alone; always complete steps 2–4 minimum.

List ticketed events for the authenticated Donorbox org. Returns id, name, slug, currency, total raised, donation count, ticket count, deadline date, ticket types, and additional questions. Use this tool to discover event IDs, ticket types, and fundraising totals. For purchases and tickets sold at an event, use list_purchases (which embeds event data in each purchase). Note: no content filters are available — only pagination and sort order.

List recurring donation plans for the authenticated Donorbox org. Returns plan amount, currency, status, interval, payment method, start/stop dates, next donation date, and nested campaign and donor details. Use this tool to answer questions about recurring donors, subscriptions (active or inactive), and plan activity over time. By default (no status param) returns plans in every status — active, paused, cancelled, failed, and finished. Pass status=active for currently charging plans, or status=paused / cancelled / finished / failed for inactive or problem plans. Filter by donor (id, email, name), campaign, or date range. Use date_filter to choose whether dates apply to plan start or last donation. DONOR ENRICHMENT: Each plan includes a donor sub-object with id and email_masked. Whenever the conversation focuses on one or more specific donors (e.g. showing a profile, following up on a donor, or any question about "who is this donor"), call list_donors with those donor id(s) to retrieve full contact details (name, masked email, location, donation count, last donation date, lifetime total).

List event ticket purchases for the authenticated Donorbox org. Returns purchase details including attendee info, price breakdown, payment method, promo codes, question answers, nested tickets, and the associated event. WHEN TO USE — prefer donorbox_aggregate_purchases for counts, sums, rankings, buyer-level analytics, and any question that needs complete results without pagination. Use list_purchases when you already know donor_id(s) or event_id and need individual purchase records (nested tickets, payment method, promo codes, per-event detail). Do not paginate through all purchases to rank buyers or answer aggregate questions. CROSS-DOMAIN QUERIES — questions like "which major donors purchased event tickets" require donorbox_aggregate_donations (rank by giving) AND donorbox_aggregate_purchases (confirm ticket purchases), intersect on donor_id, then list_donors for names. Use this tool only after that intersection when the user needs purchase line-item detail for specific donors. Use event_id to scope to a single event. Use donor_id to filter by the person who bought the tickets (the supporter/buyer). Use attendee_id to find purchases containing a ticket assigned to a specific attendee — this differs from donor_id on multi-ticket purchases where the buyer and attendees may be different people. Date filters apply to purchase created_at, not the event date. DONOR ENRICHMENT: Each purchase includes a nested donor sub-object with id and email. Whenever the conversation focuses on one or more specific donors (e.g. showing a profile, following up on a donor, or any question about "who is this donor"), call list_donors with those donor id(s) to retrieve full contact details (name, masked email, location, donation count, last donation date, lifetime total). Pass ids in bulk (up to 100) with summary=true after aggregate joins.

List event tickets for the authenticated Donorbox org. Returns ticket price, ticket type, associated event (id, name, start/end times), attendee info (if recorded), custom question answers, and the parent purchase record. Use event_id to scope to a single event. Use ticket_type_id to filter by a specific tier. Use attendee_id to find tickets assigned to a specific donor as attendee. Use date_from/date_to to filter by ticket created_at. Omit payment_status for all non-refunded tickets; pass payment_status=refunded for refunded tickets only. DONOR ENRICHMENT: Attendee sub-objects include a donor id. Whenever the conversation focuses on one or more specific donors (e.g. showing a profile, following up on a donor, or any question about "who is this donor"), call list_donors with those donor id(s) to retrieve full contact details (name, masked email, location, donation count, last donation date, lifetime total).