API Reference

Donations

To create a donation, use the /api/v1/donations endpoint. In the response, you'll get a donation ID, which you can use to retrieve information about your donation. We also have endpoints that simplify making carbon offset donations.

Create a donation

post /api/v1/donations

Creates a donation to any nonprofit. Change keeps track of your donations, bills you at the end of the month, and handles the nonprofit payouts for you.

Parameters

amount REQUIRED

The amount of the donation in cents.

nonprofit_id

The id of a nonprofit from the Change network. If this is not provided, a campaign_id must be provided.

campaign_id

The id of a campaign. If this is not provided, a nonprofit_id must be provided.

funds_collected REQUIRED

Whether you are collecting payment for the donation. This helps us issue the correct tax receipt at the end of the year.

count

The number of donations to submit.

cover_fees

Whether the amount parameter should include processing fees. Default is false.

external_id

An external ID associated with the donation, e.g. an order ID, SKU, or customer ID.

order_value

Cart or order volume (in cents) associated with the donation. Change provides AOV metrics if order values are provided.

zip_code

A zip code to associate with the donation. Change provides geography-based analytics if zip codes are provided.

metadata

Arbitrary metadata to be stored with the donation. Must be a valid JSON object.

Request 

curl https://api.getchange.io/api/v1/donations \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 500,
        "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
        "funds_collected": false,
        "external_id": "customer_1234",
        "order_value": 2599,
        "zip_code": "94104",
        "metadata": {
          "order-number": "90210"
        }
      }'

Response

{
  "amount": 500,
  "id": "d_n1Syk2W3qIB9PBGSj7G48JqK",
  "live_mode": true,
  "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
  "order_value": 2599,
  "zip_code": "94104",
  "external_id": "customer_1234",
  "metadata": {
    "order-number": "90210"
  },
  "currency": "USD"
}

List your donations

get /api/v1/donations

Retrieves a list of donations you've previously made. The donations are returned in order of creation, with the most recent donations appearing first. This endpoint is paginated.

Parameters

page number

Which page to return. This endpoint is paginated, and returns maximum 30 donations per page.

nonprofit_id string

The id of a nonprofit from the Change network.

external_id string

An external ID associated with the donation, e.g. an order ID, SKU, or customer ID. This field is set when a donation is created.

start_timestamp number

Starting timestamp of donations being retrieved. Send as a unix timestamp.

end_timestamp number

Ending timestamp of donations being retrieved. Send as a unix timestamp.

Request 

curl https://api.getchange.io/api/v1/donations \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -d 'page=1' \
  -G

Response

{
  "donations": [
    {
      "amount": 1000,
      "id": "d_yEUDGfW5GFHT19kmsxttbbR7",
      "live_mode": true,
      "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
      "order_value": 4247,
      "zip_code": "30868-5110",
      "external_id": null,
      "metadata": {
        "key": "value"
      },
      "currency": "USD"
    },
    {
      "amount": 500,
      "id": "d_cNmomJNEjw4om0MJbAiMNnh4",
      "live_mode": true,
      "nonprofit_id": "n_nIstMceV5IXNWwMOzomgHEEV",
      "order_value": 2212,
      "zip_code": "67635-3886",
      "external_id": null,
      "metadata": {
        "key": "value"
      },
      "currency": "USD"
    }
  ],
  "page": 1
}

Retrieve a donation

get /api/v1/donations/{id}

Retrieves the details of a donation you've previously made.

Parameters

id string REQUIRED

The id of a donation. Ids are returned when a donation is created.

Request 

curl https://api.getchange.io/api/v1/donations/d_cNmomJNEjw4om0MJbAiMNnh4 \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "amount": 500,
  "id": "d_cNmomJNEjw4om0MJbAiMNnh4",
  "live_mode": true,
  "nonprofit_id": "n_MUjmT5yhdf4smx1ykRwO2ovt",
  "order_value": 3148,
  "zip_code": "39083-3275",
  "external_id": null,
  "metadata": {
    "key": "value"
  },
  "currency": "USD"
}

Retrieve carbon offset stats

get /api/v1/donations/{id}/climate_stats

Measures your impact in relatable terms. Provide the id of the carbon offset to see stats about that specific donation. To see aggregated stats for all of your carbon offsets, see the /climate/stats endpoint.

Parameters

id number REQUIRED

The id of a created carbon offset

Request 

curl https://api.getchange.io/api/v1/donations/d_cNmomJNEjw4om0MJbAiMNnh4/climate_stats \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "amount": 10000,
  "trees": 163.9,
  "co2_tonnes_offset": 10
}

Nonprofits

Most U.S. nonprofits exist in the CHANGE platform. Each nonprofit has a CHANGE-issued ID; these IDs are used to reference nonprofits throughout our APIs. You can search for nonprofits manually on the dashboard, or you can seach programmatically.

Show a nonprofit

get /api/v1/nonprofits/{id}

Retrieves information for a nonprofit. Missions may be enhanced by AI.

Parameters

id string REQUIRED

The id of a nonprofit from the CHANGE network.

Request 

curl https://api.getchange.io/api/v1/nonprofits/n_MUjmT5yhdf4smx1ykRwO2ovt \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "id": "n_MUjmT5yhdf4smx1ykRwO2ovt",
  "name": "One Tree Planted Inc",
  "ein": "464664562",
  "pending_payout_amount": 1500,
  "socials": {
    "facebook": "onetreeplanted",
    "instagram": "onetreeplanted",
    "twitter": "onetreeplanted",
    "youtube": "channel/UCSyNWLnxtob29DOoPGpT1Ug"
  },
  "email": "hello@onetreeplanted.org",
  "icon_url": "https://d2m0e1zy3fwxmp.cloudfront.net/public-benefit.png",
  "impact_stats": [
    {
      "action": "plants",
      "action_past_tense": "planted",
      "impact": "tree",
      "impact_plural": "trees",
      "price": 100,
      "amount": 1,
      "type": "dynamic",
      "cover_photo_url": null,
      "id": "is_fxSVY0Y2Tr"
    }
  ],
  "categories": [
    "Environment and Climate"
  ],
  "payable": true,
  "pending_payout_amounts": {
    "USD": "1500.0"
  },
  "address_line": "145 PINE HAVEN SHORES RD",
  "city": "SHELBURNE",
  "classification": "T22",
  "mission": "Planting trees in areas that need support.",
  "state": "VT",
  "website": "WWW.ONETREEPLANTED.ORG",
  "zip_code": "05482-7703",
  "category": "public benefit",
  "cover_image_url": null,
  "logo_url": null
}

Search a nonprofit

get /api/v1/nonprofits

Retrieves a list of nonprofits that match the search parameters. Missions may be enhanced by AI. This endpoint is paginated.

Parameters

public_key string REQUIRED

Your account's public key.

search_term string

A string to search. This can be the name of a nonprofit, or an EIN. If you do not provide this parameter, you'll get featured nonprofits.

categories[] array

List of categories to search. Valid categories are: 'arts and culture', 'education', 'environment', 'animals', 'healthcare', 'human services', 'international affairs', 'public benefit', 'religion', 'mutual benefit', 'unclassified'.

page number

The page to return. This endpoint is paginated, and returns up to 30 nonprofits by default.

limit number

A limit on the number of nonprofits to be returned. Limit can range between 1 and 200, and the default is 30.

Request 

curl https://api.getchange.io/api/v1/nonprofits \
  -d 'public_key=YOUR_PUBLIC_KEY&search_term=watsi&page=1&limit=10' \
  -G

Response

{
  "nonprofits": [
    {
      "id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
      "name": "Watsi",
      "ein": "453236734",
      "socials": {
        "facebook": "Watsi.org",
        "instagram": "watsi",
        "twitter": "watsi"
      },
      "email": "connect@watsi.org",
      "icon_url": "https://d2m0e1zy3fwxmp.cloudfront.net/healthcare.png",
      "impact_stats": [
        {
          "action": "sponsors",
          "action_past_tense": "sponsored",
          "impact": "surgery",
          "impact_plural": "surgeries",
          "price": 10000,
          "amount": 1,
          "type": "dynamic",
          "cover_photo_url": null,
          "id": "is_wVHZUiHvML"
        }
      ],
      "categories": [
        "Healthcare",
        "Human Services"
      ],
      "payable": true,
      "address_line": "548 Market St # 75903",
      "city": "San Francisco",
      "classification": "E12",
      "mission": "Directly connecting people through technology to provide global access to healthcare.",
      "state": "CA",
      "website": "https://watsi.org/",
      "zip_code": "94104",
      "category": "healthcare",
      "cover_image_url": null,
      "logo_url": null,
      "stats": [
        "$100 sponsors 1 surgery"
      ]
    }
  ],
  "page": 1
}

Get social media content

get /api/v1/nonprofits/{id}/social_media_content

Retrieves social media content for the given nonprofit. CHANGE generates ready-to-post, social-media optimized images that are customized with your company name. This endpoint is not authenticated; pass your account's public key as a parameter instead. Note that this endpoint does not post anything to social media.

Parameters

id string REQUIRED

The id of a nonprofit from the CHANGE network.

public_key string REQUIRED

Your account's public key.

Request 

curl https://api.getchange.io/api/v1/nonprofits/n_IfEoPCaPqVsFAUI5xl0CBUOx/social_media_content \
  -d 'public_key=YOUR_PUBLIC_KEY' \
  -G

Response

[
  {
    "theme": "pink",
    "url": "https://generated-social-media-content--production.s3.us-west-1.amazonaws.com/bc470139f3db7120b2e5de99507e2418.jpg"
  },
  {
    "theme": "white",
    "url": "https://generated-social-media-content--production.s3.us-west-1.amazonaws.com/c4f1280a75c890ec697dcda0225ad33d.jpg"
  },
  {
    "theme": "black",
    "url": "https://generated-social-media-content--production.s3.us-west-1.amazonaws.com/340ed7919e61062605e5a8f9b330e57a.jpg"
  }
]

Create an Instant Payout

post /api/v1/nonprofits/{id}/instant_payouts

Immediately starts a payout to a nonprofit. Normally, nonprofits are paid once per month. If you want a nonprofit to receive your donations sooner, use this endpoint. You will receive an invoice for the donation funds within 24 hours of using this endpoint.

Parameters

id string REQUIRED

The id of a nonprofit from the CHANGE network.

Request 

curl https://api.getchange.io/api/v1/nonprofits/n_IfEoPCaPqVsFAUI5xl0CBUOx/instant_payouts \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -X POST

Response

{
  "instant_payouts": [
    {
      "name": "Do Good Donuts",
      "account_id": "a_jRpQcNSlWogosvceel7EP2Lv",
      "amount": 3000,
      "currency": "USD",
      "status": "pending"
    }
  ]
}

List your Instant Payouts

get /api/v1/nonprofits/{id}/instant_payouts

Retrieves a list of instant payouts you've previously made that are either pending or complete for the last month. The instant payouts are returned in order of creation, with the most recent instant payouts appearing first.

Parameters

id string REQUIRED

The id of a nonprofit from the CHANGE network.

Request 

curl https://api.getchange.io/api/v1/nonprofits/n_IfEoPCaPqVsFAUI5xl0CBUOx/instant_payouts \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "instant_payouts": [
    {
      "name": "Do Good Donuts",
      "account_id": "a_5jrLK7VWVhrdt4cPSgiEvK8X",
      "amount": 4000,
      "currency": "USD",
      "status": "pending"
    },
    {
      "name": "Do Good Donuts",
      "account_id": "a_5jrLK7VWVhrdt4cPSgiEvK8X",
      "amount": 12000,
      "currency": "USD",
      "status": "complete"
    }
  ]
}

Nonprofit Requests

If a nonprofit you like isn't in our system, you can request it. We'll review your request, and if everything checks out, we'll add it to our system.

Request a nonprofit

post /api/v1/nonprofit_requests

Requests a nonprofit.

Parameters

name REQUIRED

The name of the nonprofit.

ein REQUIRED

The EIN of the nonprofit.

address_line

The address of the nonprofit.

city

The city the nonprofit is in.

state

The state the nonprofit is in.

classification

The NTEE code for the nonprofit.

mission

The mission of the nonprofit.

socials

The social handles of the nonprofit. Accepted keys are: facebook, instagram, tiktok, twitter, youtube.

website

The website of the nonprofit.

admin_email

A contact email for the nonprofit.

payout_email

An email address to use for the nonprofit's payouts.

image_url

The URL of an image that represents the nonprofit.

Request 

curl https://api.getchange.io/api/v1/nonprofit_requests \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Do Good",
        "ein": "123-45678",
        "address_line": "123 Charity Ln",
        "city": "San Francisco",
        "state": "CA",
        "classification": "N12",
        "mission": "To do more good.",
        "socials": {
          "twitter": "dogooderz"
        },
        "website": "dogood.org"
      }'

Response

{
  "result": {
    "address_line": "123 Charity Ln",
    "city": "San Francisco",
    "classification": "N12",
    "admin_email": null,
    "ein": "123-45678",
    "image_url": null,
    "mission": "To do more good.",
    "name": "Do Good",
    "payout_email": null,
    "socials": {
      "twitter": "dogooderz"
    },
    "status": "pending",
    "website": "dogood.org",
    "id": "nr_02RkrZnRnOAu4xReskliKV5g"
  }
}

List your nonprofit requests

get /api/v1/nonprofit_requests

Retrieves your nonprofit requests. Check the status field for the current status of the request. For accepted requests, the nonprofit_id field will be populated with your requested nonprofit's Change ID.

Parameters

There are no parameters.

Request 

curl https://api.getchange.io/api/v1/nonprofit_requests \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "result": [
    {
      "address_line": "123 Charity Ln",
      "city": "San Francisco",
      "classification": "N12",
      "admin_email": "oliver.cummerata@maggio.name",
      "ein": "123-45678",
      "image_url": null,
      "mission": "To do more good.",
      "name": "Do Good",
      "payout_email": null,
      "socials": {
        "twitter": "dogooderz"
      },
      "status": "pending",
      "website": "dogood.org",
      "id": "nr_x7eZdurHi9QYqnM8e57RpxBB"
    }
  ]
}

Show a nonprofit request

get /api/v1/nonprofit_requests/{id}

Retrieves a nonprofit request. Check the status field for the current status of the request. For accepted requests, the nonprofit_id field will be populated with your requested nonprofit's Change ID.

Parameters

id string REQUIRED

The id of a nonprofit request.

Request 

curl https://api.getchange.io/api/v1/nonprofit_requests/nr_OT4P1sNjI4N3IUdbiIEs4UBc \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "result": {
    "address_line": "123 Charity Ln",
    "city": "San Francisco",
    "classification": "N12",
    "admin_email": "ronnie_harris@langworth-gleason.info",
    "ein": "123-45678",
    "image_url": null,
    "mission": "To do more good.",
    "name": "Do Good",
    "payout_email": null,
    "socials": {
      "twitter": "dogooderz"
    },
    "status": "pending",
    "website": "dogood.org",
    "id": "nr_OT4P1sNjI4N3IUdbiIEs4UBc"
  }
}

Transfers

(Ask us for access) If you use Stripe to collect payments, you can make donations by transferring Stripe funds directly to Change.

Capture a Stripe Transfer

post /api/v1/transfers

(Ask us for access) Creates a donation from an existing Stripe Transfer. A successful response will be empty with a status of 200.

Parameters

nonprofit_id REQUIRED

The ID of a nonprofit from the Change network.

stripe_destination_payment_id REQUIRED

The destination payment ID of a Stripe Transfer. You can find this ID in the response from Stripe when creating a Stripe Transfer, or when capturing a Stripe PaymentIntent containing transfer_data.

Request 

curl https://api.getchange.io/api/v1/transfers \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
        "stripe_destination_payment_id": "py_00000000000000000000000"
      }'

Reports

See the impact you've made with the Reports API. Generate reports that summarize your giving in relatable terms.

Fetch impact report

get /api/v1/reports/impact

Fetches a report detailing the aggregated impact of your donations.

Parameters

account_id string

An account id to filter donations that are included in the report. Leave this blank to include all donations made by you or your managed accounts.

external_id string

An external id to filter donations that are included in the report.

start_timestamp number

Starting timestamp of data to be included in the report. Send as a unix timestamp.

end_timestamp number

Ending timestamp of data to be included in the report. Send as a unix timestamp.

Request 

curl https://api.getchange.io/api/v1/reports/impact \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "data": [
    {
      "id": "n_MUjmT5yhdf4smx1ykRwO2ovt",
      "name": "One Tree Planted Inc",
      "ein": "464664562",
      "socials": {
        "facebook": "onetreeplanted",
        "instagram": "onetreeplanted",
        "twitter": "onetreeplanted",
        "youtube": "channel/UCSyNWLnxtob29DOoPGpT1Ug"
      },
      "email": "hello@onetreeplanted.org",
      "icon_url": "https://d2m0e1zy3fwxmp.cloudfront.net/public-benefit.png",
      "impact_stats": [
        {
          "action": "plants",
          "action_past_tense": "planted",
          "impact": "tree",
          "impact_plural": "trees",
          "price": 100,
          "amount": 1,
          "type": "dynamic",
          "cover_photo_url": null,
          "id": "is_SE0TpIbfeI"
        }
      ],
      "categories": [
        "Environment and Climate"
      ],
      "payable": true,
      "address_line": "145 PINE HAVEN SHORES RD",
      "city": "SHELBURNE",
      "classification": "T22",
      "mission": "Planting trees in areas that need support.",
      "state": "VT",
      "website": "WWW.ONETREEPLANTED.ORG",
      "zip_code": "05482-7703",
      "category": "public benefit",
      "cover_image_url": null,
      "logo_url": null,
      "total_impact": [
        "planted 327 trees"
      ]
    },
    {
      "id": "n_nIstMceV5IXNWwMOzomgHEEV",
      "name": "Aim For Mental Health Inc",
      "ein": "473992060",
      "socials": {
        "facebook": "AIMforMentalHealth",
        "instagram": "aimmentalhealth",
        "twitter": "AimMentalHealth",
        "youtube": "channel/AimMentalHealth"
      },
      "email": null,
      "icon_url": "https://d2m0e1zy3fwxmp.cloudfront.net/healthcare.png",
      "impact_stats": [
        {
          "action": "sponsor",
          "action_past_tense": "sponsored",
          "impact": "therapy session",
          "impact_plural": "therapy sessions",
          "price": null,
          "amount": null,
          "type": "generic",
          "cover_photo_url": null,
          "id": "is_ZAFYwmfBTb"
        },
        {
          "action": "sponsor",
          "action_past_tense": "sponsored",
          "impact": "book for a child",
          "impact_plural": "books for children",
          "price": 700,
          "amount": null,
          "type": "dynamic",
          "cover_photo_url": null,
          "id": "is_5X40vAfbCO"
        },
        {
          "action": "purchases",
          "action_past_tense": "purchased",
          "impact": "pencil for a test taker in need",
          "impact_plural": "pencils for test takers in need",
          "price": 10,
          "amount": null,
          "type": "dynamic",
          "cover_photo_url": null,
          "id": "is_CF7xkdPpvm"
        },
        {
          "action": "sponsor",
          "action_past_tense": "sponsored",
          "impact": "trips to San Francisco",
          "impact_plural": "trips to San Francisco",
          "price": null,
          "amount": null,
          "type": "generic",
          "cover_photo_url": null,
          "id": "is_MFU51uHg4T"
        }
      ],
      "categories": [
        "Healthcare",
        "Human Services"
      ],
      "payable": true,
      "address_line": "PO BOX 4235",
      "city": "CARMEL",
      "classification": "F32",
      "mission": "WE FIND AND FUND THE MOST PROMISING YOUTH MENTAL HEALTH RESEARCH IN THE WORLD SO WE CAN FIND REAL SOLUTIONS WITH IMMEDIATE IMPACTS. WE RAISE AWARENESS WITHIN OUR COMMUNITIES REGARDING THE MENTAL HEALTH CRISIS AMONG OUR YOUTH.",
      "state": "CA",
      "website": "WWW.AIMFORMENTALHEALTH.ORG",
      "zip_code": "93921-4235",
      "category": "healthcare",
      "cover_image_url": null,
      "logo_url": null,
      "total_impact": [
        "sponsored therapy sessions",
        "sponsored books for children",
        "purchased pencils for test takers in need",
        "sponsored trips to San Francisco"
      ]
    }
  ],
  "filters": {
    "end_timestamp": 1699568893
  }
}

Prebuilt Pages

Our prebuilt pages allow you to easily accept donations without integrating a payment processor.

post /api/v1/payments/checkout_link

Creates a Stripe Checkout link to collect donations for a specific nonprofit. Donation processing fees are automatically deducted from the collected amount.

Parameters

amount REQUIRED

The amount of the donation in cents.

cancel_url REQUIRED

The url the donor will be redirected to if they cancel checkout. Must be prefixed with https://

nonprofit_id REQUIRED

The id of a nonprofit from the Change network.

success_url REQUIRED

The url the donor will be redirected to upon a successful donation. Must be prefixed with https://

external_id

An external ID associated with the donation, e.g. an order ID, SKU, or customer ID. Will be attached to the donation created by a successful checkout.

metadata

Arbitrary metadata to be stored with the donation. Must be a valid JSON object. Will be attached to the donation created by a successful checkout.

Request 

curl https://api.getchange.io/api/v1/payments/checkout_link \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 500,
        "cancel_url": "https://your-domain.com/cancel",
        "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
        "success_url": "https://your-domain.com/success",
        "external_id": "customer_1234"
      }'

Response

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_123"
}
Made with ❤ in San Francisco