openapi: 3.0.3
info:
  title: Donorbox Campaigns Donations 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: Donations
  description: One-time and recurring donation transactions.
paths:
  /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'
components:
  parameters:
    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
    Page:
      name: page
      in: query
      description: Page number to return.
      schema:
        type: integer
        default: 1
    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:
    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'
  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.