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'