[Early Access] Charity Donations

Please reach out to the admin team [email protected] to learn more about donations through our API

Base URL: https://app.thegoodapi.com

All endpoints require an API key via the Authorization header:

Authorization: <your_api_key>

---

Search Charities

Search for charities by name or EIN.

GET /charities/search

Parameters

Parameter	Type	Required	Description
name	string	No	Search by charity name
ein	string	No	Employer Identification Number
page_size	integer	No	Results per page (1-20, default 20)
page	integer	No	Page number (minimum 1, default 1)

Response

{
  "total_items": 42,
  "total_pages": 3,
  "charities": [
    {
      "nonprofit_id": "n_abc123",
      "name": "American Red Cross",
      "ein": "53-0196605",
      "description": "Prevents and alleviates human suffering",
      "website": "https://www.redcross.org",
      "icon_url": "https://example.com/redcross-icon.png"
    }
  ]
}

Charity Fields

Field	Type	Description
nonprofit_id	string	Provider-specific nonprofit ID
name	string	Charity name
ein	string	Employer Identification Number
description	string	Charity description or mission
website	string	Charity website URL
icon_url	string	Charity icon image URL

Errors

Status	Reason
403	Invalid or missing API key
500	Charity search failed

Example

curl -H "Authorization: your-api-key" \
  "https://api.thegoodapi.com/charities/search?name=red+cross"

---

Create Donation

Record a charity donation for your organization.

POST /charities/donate

Request Body

{
  "amount_cents": 5000,
  "ein": "53-0196605",
  "nonprofit_id": "n_abc123",
  "charity_name": "American Red Cross",
  "idempotency_key": "order-12345-donate",
  "attribution": "checkout-flow",
  "metadata": {
    "order_id": "12345",
    "customer_email": "[email protected]"
  }
}

Request Fields

Field	Type	Required	Description
amount_cents	integer	Yes	Donation amount in cents (must be > 0)
ein	string	*	Employer Identification Number of the charity
nonprofit_id	string	*	Provider-specific nonprofit identifier
charity_name	string	No	Human-readable charity name (auto-filled from search if omitted)
idempotency_key	string	No	Unique key to prevent duplicate donations
attribution	string	No	Attribution tag (e.g., "checkout", "campaign-xyz")
metadata	object	No	Arbitrary key-value pairs for your records

* At least one of ein or nonprofit_id is required. Currency is always USD.

Response

{
  "donation_id": "abc123def456",
  "amount_cents": 5000,
  "charity_name": "American Red Cross",
  "ein": "53-0196605",
  "nonprofit_id": "n_abc123",
  "total_donations": 15,
  "donation_details": [
    {
      "id": "abc123def456",
      "amount_cents": 5000,
      "currency": "USD",
      "ein": "53-0196605",
      "nonprofit_id": "n_abc123",
      "charity_name": "American Red Cross",
      "created_at": "2025-06-15T10:30:00Z",
      "idempotency_key": "order-12345-donate",
      "attribution": "checkout-flow",
      "metadata": {
        "order_id": "12345",
        "customer_email": "[email protected]"
      },
      "refunded": false
    }
  ]
}

Response Fields

Field	Type	Description
donation_id	string	Unique ID of the created donation
amount_cents	integer	Donation amount in cents
charity_name	string	Charity name (auto-filled from search if omitted)
ein	string	EIN (if provided)
nonprofit_id	string	Nonprofit ID (if provided)
total_donations	integer	Total non-refunded donations for your org
donation_details	array	Array containing the created donation record

Idempotency

When idempotency_key is provided and a donation with the same key already exists for your organization:

• The existing donation is returned

• The response includes the header Idempotent-Replayed: true

• No new donation is created

Charity Validation

The provided ein or nonprofit_id is validated against the charity search provider. If no matching charity is found, the request is rejected with a 400 error. When a charity is found and charity_name was not provided, it is automatically populated from the search result.

Errors

Status	Reason
400	Missing ein and nonprofit_id
400	amount_cents is missing or <= 0
400	Invalid request body
400	No charity found for the provided ein
400	No charity found for the provided nonprofit_id
403	Invalid or missing API key
500	Internal server error

Examples

Basic donation by EIN:

curl -X POST -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 5000, "ein": "53-0196605"}' \
  "https://api.thegoodapi.com/charities/donate"

Donation with idempotency and attribution:

curl -X POST -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 2500,
    "nonprofit_id": "n_abc123",
    "idempotency_key": "order-789-donate",
    "attribution": "checkout",
    "metadata": {"order_id": "789"}
  }' \
  "https://api.thegoodapi.com/charities/donate"

---

List Donations

Retrieve paginated donations for your organization with optional filtering.

GET /charities/donations

Parameters

Parameter	Type	Required	Description
attribution	string	No	Filter by attribution tag
metadata_key	string	No	Filter by metadata key existence
metadata_value	string	No	Filter by metadata value (requires metadata_key)
start_date	string	No	Filter on or after this date (YYYY-MM-DD)
end_date	string	No	Filter on or before this date (YYYY-MM-DD)
page	integer	No	Page number (minimum 1, default 1)
page_size	integer	No	Results per page (1-100, default 20)

Response

{
  "total_items": 50,
  "total_pages": 5,
  "page": 1,
  "page_size": 10,
  "donations": [
    {
      "id": "abc123def456",
      "amount_cents": 5000,
      "currency": "USD",
      "ein": "53-0196605",
      "nonprofit_id": "n_abc123",
      "charity_name": "American Red Cross",
      "created_at": "2025-06-15T10:30:00Z",
      "idempotency_key": "order-12345-donate",
      "attribution": "checkout-flow",
      "metadata": {
        "order_id": "12345"
      },
      "refunded": false
    }
  ]
}

Response Fields

Field	Type	Description
total_items	integer	Total number of matching donations
total_pages	integer	Total number of pages (0 if no results)
page	integer	Current page number
page_size	integer	Number of items per page
donations	array	Array of donation records

Donation Fields

Field	Type	Description
id	string	Unique donation ID
amount_cents	integer	Donation amount in cents
currency	string	Currency code (always USD)
ein	string	EIN of the charity
nonprofit_id	string	Provider-specific nonprofit ID
charity_name	string	Human-readable charity name
created_at	string	ISO 8601 timestamp
idempotency_key	string	Idempotency key (if provided)
attribution	string	Attribution tag
metadata	object	Arbitrary key-value pairs
refunded	boolean	Whether the donation has been refunded

Errors

Status	Reason
400	Invalid date format
403	Invalid or missing API key
500	Internal server error

Examples

List all donations:

curl -H "Authorization: your-api-key" \
  "https://api.thegoodapi.com/charities/donations"

Filter by attribution with pagination:

curl -H "Authorization: your-api-key" \
  "https://api.thegoodapi.com/charities/donations?attribution=checkout&page=1&page_size=10"

Filter by date range:

curl -H "Authorization: your-api-key" \
  "https://api.thegoodapi.com/charities/donations?start_date=2025-01-01&end_date=2025-06-30"

Filter by metadata:

curl -H "Authorization: your-api-key" \
  "https://api.thegoodapi.com/charities/donations?metadata_key=order_id&metadata_value=12345"