Read-only access to recurring donation plans/subscriptions - donor, campaign, plan type (monthly, weekly, etc.), amount, payment method, start date, last/next donation date, and status. Filterable by donor email/id/name, campaign, and start date range.
openapi: 3.0.3
info:
title: Donorbox API
description: >-
The Donorbox API provides read-only access to a nonprofit organization's
fundraising data - Campaigns, Donations, Plans (recurring donation
subscriptions), Donors, Events, Tickets, and Event Ticket Purchases. The
API is a paid add-on available on the Pro and Premium Donorbox plans. All
requests use HTTP Basic Auth, with your Donorbox organization login email
as the username and your API key as the password. Every list endpoint
supports `page`/`per_page` pagination and `order` sorting, and most
support endpoint-specific filters. There are no documented write
(POST/PUT/PATCH/DELETE) operations - donations, donors, and plans are
created through the hosted Donorbox checkout flow, not this API. This
document was authored by API Evangelist from the official
donorbox/donorbox-api GitHub README and wiki, since Donorbox does not
publish its own OpenAPI/Swagger file.
version: '1.0'
contact:
name: Donorbox
url: https://donorbox.org
license:
name: Proprietary (API access is a paid add-on)
url: https://github.com/donorbox/donorbox-api
servers:
- url: https://donorbox.org/api/v1
description: Donorbox production API
security:
- basicAuth: []
tags:
- name: Campaigns
description: Fundraising campaigns.
- name: Donations
description: One-time and recurring donation transactions.
- name: Plans
description: Recurring donation subscriptions.
- name: Donors
description: Donor/supporter profiles.
- name: Events
description: Ticketed fundraising events.
- name: Tickets
description: Individual event tickets.
- name: Purchases
description: Event ticket purchase transactions.
paths:
/campaigns:
get:
operationId: listCampaigns
tags:
- Campaigns
summary: List campaigns
description: >-
Returns all fundraising campaigns for the authenticated organization.
Endpoint confirmed in the official README; response fields confirmed
from the documented sample payload.
parameters:
- name: id
in: query
description: Filter to a single campaign by its Donorbox campaign id (documented as the `campaign_id` filter).
schema:
type: integer
- name: name
in: query
description: Filter campaigns by campaign name.
schema:
type: string
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of campaigns.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Campaign'
'401':
$ref: '#/components/responses/Unauthorized'
/donations:
get:
operationId: listDonations
tags:
- Donations
summary: List donations
description: >-
Returns all donations for the authenticated organization, including
Stripe and PayPal transactions, donor detail, and any custom
question/answer fields collected on the donation form. Endpoint and
response shape confirmed in the official README sample payloads.
parameters:
- name: email
in: query
description: Filter donations by the donor's email address.
schema:
type: string
format: email
- name: date_from
in: query
description: 'Filter donations on or after this date. Accepted formats: YYYY-mm-dd, YYYY/mm/dd, YYYYmmdd, dd-mm-YYYY.'
schema:
type: string
- name: date_to
in: query
description: 'Filter donations on or before this date. Accepted formats: YYYY-mm-dd, YYYY/mm/dd, YYYYmmdd, dd-mm-YYYY.'
schema:
type: string
- name: campaign_name
in: query
description: Filter donations by campaign title.
schema:
type: string
- name: campaign_id
in: query
description: Filter donations by Donorbox campaign id.
schema:
type: integer
- name: id
in: query
description: Filter to a single donation by its Donorbox donation id.
schema:
type: integer
- name: first_name
in: query
description: Filter donations by donor first name.
schema:
type: string
- name: last_name
in: query
description: Filter donations by donor last name.
schema:
type: string
- name: donor_id
in: query
description: Filter donations by Donorbox donor id.
schema:
type: integer
- name: amount[usd][min]
in: query
description: Minimum donation amount (USD), usable alone or with amount[usd][max].
schema:
type: number
- name: amount[usd][max]
in: query
description: Maximum donation amount (USD), usable alone or with amount[usd][min].
schema:
type: number
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of donations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Donation'
'401':
$ref: '#/components/responses/Unauthorized'
/plans:
get:
operationId: listPlans
tags:
- Plans
summary: List recurring donation plans
description: >-
Returns all recurring donation plans (subscriptions) for the
authenticated organization. Endpoint and response shape confirmed in
the official README sample payload.
parameters:
- name: email
in: query
description: Filter plans by the donor's email address.
schema:
type: string
format: email
- name: date_from
in: query
description: 'Filter plans started on or after this date. Accepted formats: YYYY-mm-dd, YYYY/mm/dd, YYYYmmdd, dd-mm-YYYY.'
schema:
type: string
- name: date_to
in: query
description: 'Filter plans started on or before this date. Accepted formats: YYYY-mm-dd, YYYY/mm/dd, YYYYmmdd, dd-mm-YYYY.'
schema:
type: string
- name: campaign_id
in: query
description: Filter plans by Donorbox campaign id.
schema:
type: integer
- name: campaign_name
in: query
description: Filter plans by campaign title.
schema:
type: string
- name: donor_id
in: query
description: Filter plans by Donorbox donor id.
schema:
type: integer
- name: first_name
in: query
description: Filter plans by donor first name.
schema:
type: string
- name: last_name
in: query
description: Filter plans by donor last name.
schema:
type: string
- name: donor_name
in: query
description: Filter plans by donor full name (equivalent to combining first_name and last_name).
schema:
type: string
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of recurring donation plans.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Plan'
'401':
$ref: '#/components/responses/Unauthorized'
/donors:
get:
operationId: listDonors
tags:
- Donors
summary: List donors
description: >-
Returns all donor profiles for the authenticated organization.
Endpoint and response shape confirmed in the official README sample
payload.
parameters:
- name: id
in: query
description: Filter to a single donor by Donorbox donor id.
schema:
type: integer
- name: first_name
in: query
description: Filter donors by first name.
schema:
type: string
- name: last_name
in: query
description: Filter donors by last name.
schema:
type: string
- name: donor_name
in: query
description: Filter donors by full name (equivalent to combining first_name and last_name).
schema:
type: string
- name: email
in: query
description: Filter donors by email address.
schema:
type: string
format: email
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of donors.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Donor'
'401':
$ref: '#/components/responses/Unauthorized'
/events:
get:
operationId: listEvents
tags:
- Events
summary: List ticketed events
description: >-
Returns all ticketed fundraising events for the authenticated
organization. Endpoint and response shape confirmed in the official
README sample payload; documented filter parameters were not
published beyond common pagination/ordering, so only those are
modeled here.
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of events.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Event'
'401':
$ref: '#/components/responses/Unauthorized'
/tickets:
get:
operationId: listTickets
tags:
- Tickets
summary: List event tickets
description: >-
Returns all individual event tickets for the authenticated
organization. Endpoint and response shape confirmed in the official
README sample payload.
parameters:
- name: payment_status
in: query
description: Filter tickets by payment status. Documented example is `refunded`.
schema:
type: string
enum:
- refunded
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of tickets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Ticket'
'401':
$ref: '#/components/responses/Unauthorized'
/purchases:
get:
operationId: listPurchases
tags:
- Purchases
summary: List event ticket purchases
description: >-
Returns all event ticket purchase transactions for the authenticated
organization. Endpoint and response shape confirmed in the official
README sample payload.
parameters:
- name: payment_status
in: query
description: Filter purchases by payment status. Defaults to `succeeded` if an invalid value is passed.
schema:
type: string
enum:
- succeeded
- pending
- failed
- refunded
default: succeeded
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Order'
responses:
'200':
description: A list of event ticket purchases.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Purchase'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Username is the Donorbox organization login email; password is the API key generated under Account > API & Zapier Integration.
parameters:
Page:
name: page
in: query
description: Page number to return.
schema:
type: integer
default: 1
PerPage:
name: per_page
in: query
description: Number of records per page. Default 50, maximum 100 (values above 100 fall back to the default).
schema:
type: integer
default: 50
maximum: 100
Order:
name: order
in: query
description: Sort order.
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
Unauthorized:
description: Missing or invalid Basic Auth credentials (organization email / API key). Response shape not published; modeled generically.
content:
application/json:
schema:
type: object
properties:
error:
type: string
schemas:
Campaign:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
currency:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
goal_amt:
type: string
formatted_goal_amount:
type: string
total_raised:
type: string
formatted_total_raised:
type: string
donations_count:
type: integer
DonationQuestion:
type: object
properties:
question_type:
type: string
enum:
- radiobutton
- text
- check
- dropdown
question:
type: string
answer:
description: Free-text, selected option, or boolean depending on question_type.
oneOf:
- type: string
- type: boolean
Donation:
type: object
properties:
id:
type: integer
action:
type: string
description: Present on Stripe donations in the documented sample (e.g. "new").
campaign:
type: object
properties:
id:
type: integer
name:
type: string
donor:
type: object
properties:
id:
type: integer
name:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
address:
type: string
address_line_2:
type: string
city:
type: string
state:
type: string
zip_code:
type: string
country:
type: string
employer:
type: string
nullable: true
occupation:
type: string
nullable: true
amount:
type: string
formatted_amount:
type: string
converted_amount:
type: string
formatted_converted_amount:
type: string
recurring:
type: boolean
first_recurring_donation:
type: boolean
amount_refunded:
type: string
formatted_amount_refunded:
type: string
stripe_charge_id:
type: string
description: Present when donation_type is "stripe".
paypal_transaction_id:
type: string
description: Present when donation_type is "paypal".
status:
type: string
donation_type:
type: string
enum:
- stripe
- paypal
donation_date:
type: string
format: date-time
anonymous_donation:
type: boolean
gift_aid:
type: boolean
designation:
type: string
join_mailing_list:
type: boolean
comment:
type: string
donating_company:
type: string
nullable: true
currency:
type: string
converted_currency:
type: string
utm_campaign:
type: string
utm_source:
type: string
utm_medium:
type: string
utm_term:
type: string
utm_content:
type: string
processing_fee:
type: number
formatted_processing_fee:
type: string
address:
type: string
address_line_2:
type: string
city:
type: string
state:
type: string
zip_code:
type: string
country:
type: string
employer:
type: string
nullable: true
occupation:
type: string
nullable: true
questions:
type: array
items:
$ref: '#/components/schemas/DonationQuestion'
Plan:
type: object
properties:
id:
type: integer
campaign:
type: object
properties:
id:
type: integer
name:
type: string
donor:
type: object
properties:
id:
type: integer
name:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
address:
type: string
city:
type: string
state:
type: string
zip_code:
type: string
country:
type: string
employer:
type: string
nullable: true
occupation:
type: string
nullable: true
type:
type: string
description: 'Recurrence frequency, e.g. "monthly".'
amount:
type: string
formatted_amount:
type: string
payment_method:
type: string
started_at:
type: string
format: date
last_donation_date:
type: string
format: date-time
next_donation_date:
type: string
format: date
status:
type: string
description: 'Documented example value: "active".'
Donor:
type: object
properties:
id:
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
address:
type: string
city:
type: string
state:
type: string
zip_code:
type: string
country:
type: string
employer:
type: string
nullable: true
occupation:
type: string
nullable: true
comment:
type: string
nullable: true
donations_count:
type: integer
last_donation_at:
type: string
format: date-time
total:
type: array
items:
type: object
properties:
currency:
type: string
value:
type: number
Event:
type: object
properties:
id:
type: integer
name:
type: string
slug:
type: string
currency:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
total_raised:
type: number
formatted_total_raised:
type: string
donations_count:
type: integer
tickets_count:
type: integer
TicketType:
type: object
properties:
id:
type: integer
name:
type: string
fair_market_value:
type: number
fair_market_value_formatted:
type: string
tax_deductible_amount:
type: number
tax_deductible_amount_formatted:
type: string
tax_amount:
type: number
tax_amount_formatted:
type: string
Ticket:
type: object
properties:
id:
type: integer
currency:
type: string
free_ticket:
type: boolean
price:
type: number
price_formatted:
type: string
ticket_type:
$ref: '#/components/schemas/TicketType'
event:
type: object
properties:
id:
type: integer
name:
type: string
transaction:
type: object
description: The purchase transaction this ticket belongs to.
properties:
id:
type: integer
city:
type: string
state:
type: string
country:
type: string
zip:
type: string
currency:
type: string
first_name:
type: string
last_name:
type: string
donation_id:
type: integer
nullable: true
stripe_charge_id:
type: string
full_name:
type: string
address:
type: string
phone:
type: string
email:
type: string
format: email
supporter_id:
type: integer
status:
type: string
purchase_date:
type: string
format: date-time
free_purchase:
type: boolean
price:
type: number
price_formatted:
type: string
donation_amount:
type: number
nullable: true
donation_amount_formatted:
type: string
nullable: true
app_fee:
type: number
app_fee_formatted:
type: string
stripe_fee:
type: number
stripe_fee_formatted:
type: string
slug:
type: string
preferences_answer:
nullable: true
Purchase:
type: object
properties:
id:
type: integer
currency:
type: string
status:
type: string
enum:
- succeeded
- pending
- failed
- refunded
- paid
supporter_id:
type: integer
amount:
type: number
amount_formatted:
type: string
amount_refunded:
type: number
date:
type: string
format: date-time
tickets_count:
type: integer
preferences_answer:
nullable: true
event:
type: object
properties:
id:
type: integer
name:
type: string
tickets:
type: array
items:
type: object
properties:
id:
type: integer
currency:
type: string
free_ticket:
type: boolean
price:
type: number
price_formatted:
type: string
ticket_type:
$ref: '#/components/schemas/TicketType'