Updated

API Reference

Donations

To create a donation, use the /donations/create 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 REQUIRED

The id of a nonprofit from the CHANGE network.

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.

batch

A list of donation objects to process a batch of donations at once.

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.

account_id

For Marketplace API donations only. The id of the managed account.

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.

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"
      }'

Response

{
  "amount": 500,
  "id": "d_Ul2ABU2Mi4SUl18Se3sBCwyb",
  "live_mode": true,
  "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
  "order_value": 2599,
  "zip_code": "94104",
  "external_id": "customer_1234"
}

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.

account_id string

For Marketplace API donations only. The id of the managed account.

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": 4417,
      "zip_code": "21191",
      "external_id": null
    },
    {
      "amount": 500,
      "id": "d_cNmomJNEjw4om0MJbAiMNnh4",
      "live_mode": true,
      "nonprofit_id": "n_nIstMceV5IXNWwMOzomgHEEV",
      "order_value": 3315,
      "zip_code": "24832-0799",
      "external_id": null
    }
  ],
  "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": 2099,
  "zip_code": "97021",
  "external_id": null
}

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.

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

{
  "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/public-benefit.png",
  "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": "[email protected]",
  "display_impact": [
    "$1 sponsors one tree planted"
  ],
  "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"
}

Search a nonprofit

get /api/v1/nonprofits

Retrieves a list of nonprofits whose names match the provided name. This endpoint is paginated.

Parameters

name string

A string to search.

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 at a time.

Request 

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

Response

{
  "nonprofits": [
    {
      "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/healthcare.png",
      "id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
      "name": "Watsi",
      "ein": "453236734",
      "socials": {
        "facebook": "Watsi.org",
        "instagram": "watsi",
        "twitter": "watsi"
      },
      "email": "[email protected]",
      "display_impact": [],
      "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",
      "stats": []
    }
  ],
  "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.

account_id string

For Marketplace API donations only. The id of the managed account.

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"
  }
]

Climate

Our Climate API helps you make donations that offset your carbon consumption, whether you're shipping physical items or executing cryptocurrency transactions. You can also get understandable stats about your contributions to the environment that are easy to share with your users.

Draft a shipping carbon offset

get /api/v1/climate/shipping_offset

If you want to calculate and donate a carbon offset in one step, skip to Create a Shipping Offset. Drafts a carbon offset for the amount needed to offset a physical shipment. The amount depends on the weight, primary transportation method, and distance of the shipment. Provide the distance of the shipment using the origin and destination address, or directly with the number of miles. This endpoint returns the id of the drafted carbon offset that remains valid for one week. You can capture a drafted carbon offset by providing the id when you create a shipping offset. See the Carbon offsets guide for more on using this endpoint.

Parameters

transportation_method string REQUIRED
Enum: air|truck|rail|sea

The primary transportation method of the shipment. The default is air.

weight_lb number REQUIRED

The total weight (in pounds) of the shipment.

destination_address number

The destination zip code (US only) of the shipment. If you send this parameter, also send origin_address.

distance_mi number

The total distance (in miles) of the shipment. You can use this parameter in place of origin_address and destination_address.

origin_address number

The origin zip code (US only) of the shipment. If you send this parameter, also send destination_address.

account_id string

For Marketplace API donations only. The id of the managed account.

Request 

curl https://api.getchange.io/api/v1/climate/shipping_offset \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -d 'transportation_method=air&weight_lb=15&destination_address=94133&origin_address=60148' \
  -G

Response

{
  "amount": 18,
  "live_mode": true,
  "offset_id": "offset_NUnjekyUv5uZkqU4XPcklTt5"
}

Create a shipping carbon offset

post /api/v1/climate/shipping_offset

Makes a donation to verified carbon reduction projects to offset the carbon emissions of a physical shipment. The amount depends on the weight, primary transportation method, and distance of the shipment. Provide the distance of the shipment using the origin and destination address, or directly with the number of miles. If you already drafted a carbon offset, just pass the offset ID.

Parameters

funds_collected REQUIRED

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

destination_address

The destination zip code (US only) of the shipment. If you send this parameter, also send origin_address.

distance_mi

The total distance (in miles) of the shipment. You can use this parameter in place of origin_address and destination_address.

offset_id

The ID for a drafted carbon offset. You can use this parameter in place of origin_address, destination_address, distance_mi, transporation_method and weight_lb.

origin_address

The origin zip code (US only) of the shipment. If you send this parameter, also send destination_address.

batch

A list of carbon offset objects to process a batch of carbon offsets at once.

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.

transportation_method

The primary transportation method of the shipment. The default is air.

weight_lb

The total weight (in pounds) of the shipment.

zip_code

The customer's zip code. Provide this to unlock geographic insights. This field is not used to calculate the shipping offset.

project_id

BETA: The ID for the project type you are looking to support.

account_id

For Marketplace API donations only. The id of the managed account.

Request 

curl https://api.getchange.io/api/v1/climate/shipping_offset \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "funds_collected": false,
        "destination_address": 94133,
        "origin_address": 60148,
        "external_id": "customer_1234",
        "order_value": 2599,
        "transportation_method": "air",
        "weight_lb": 15,
        "zip_code": "94104"
      }'

Response

{
  "amount": 18,
  "id": "c_pfJKWT4BmFnCAbJ3qf1QglHf",
  "live_mode": true,
  "nonprofit_id": "n_F6VhFP1nlN5V1Sr92CEQ3xom",
  "order_value": 2599,
  "zip_code": "94104",
  "external_id": "customer_1234"
}

Draft a crypto carbon offset

get /api/v1/climate/crypto_offset

If you want to calculate and donate a carbon offset in one step, skip to Create a Crypto Offset. Drafts a carbon offset for the amount needed to offset a cryptocurrency transaction. This endpoint returns the id of the drafted carbon offset that remains valid for one week. You can capture a drafted carbon offset by providing the id when you create a crypto offset. See the Carbon offsets guide for more on using this endpoint.

Parameters

currency string REQUIRED
Enum: eth|btc|sol

The currency of the transaction.

count number

The number of transactions to offset. Default is 1.

account_id string

For Marketplace API donations only. The id of the managed account.

Request 

curl https://api.getchange.io/api/v1/climate/crypto_offset \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -d 'currency=eth&count=2' \
  -G

Response

{
  "amount": 76,
  "live_mode": true,
  "offset_id": "offset_jSbZaU84AhYGlKlsxtdVYmUh"
}

Create a crypto carbon offset

post /api/v1/climate/crypto_offset

Makes a donation to verified carbon reduction projects to offset the carbon emissions due to a cryptocurrency transaction. The amount depends on the number of transactions and currency. If you already drafted a carbon offset, just pass the offset ID.

Parameters

funds_collected REQUIRED

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

count

The number of transactions to offset.

currency

The currency of the transaction.

offset_id

The ID for a drafted carbon offset. You can use this parameter in place of currency and count.

zip_code

The customer's zip code. Provide this to unlock geographic insights.

order_value

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

external_id

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

account_id

For Marketplace API donations only. The id of the managed account.

Request 

curl https://api.getchange.io/api/v1/climate/crypto_offset \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "funds_collected": false,
        "count": 2,
        "currency": "eth",
        "zip_code": "94104",
        "order_value": 2599,
        "external_id": "customer_1234"
      }'

Response

{
  "amount": 76,
  "id": "c_9edHTmBnPzswKyDTrBQTs4zn",
  "live_mode": true,
  "order_value": 2599,
  "zip_code": "94104",
  "external_id": "customer_1234"
}

Retrieve carbon offset stats

get /api/v1/climate/stats

Measures your impact in relatable terms. Returns aggregate stats for all of your carbon offsets. To see stats about a specific carbon offset, see the donations/{id}/climate_stats endpoint.

Parameters

There are no parameters.

Request 

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

Response

{
  "amount": 1000000,
  "trees": 16393.4,
  "co2_tonnes_offset": 1000
}

Marketplace

Our Marketplace API allows you to power donations on your platform with managed accounts. A parent account can create donations and fetch analytics on behalf of its managed accounts. Managed accounts can directly connect their bank accounts to fund donations. From fundraising platforms to ridesharing apps, the Marketplace API makes it easy to manage donations across a network of users.

Create a managed account

post /api/v1/accounts

Creates a managed account. Managed accounts can be used in marketplace integrations.

Parameters

email REQUIRED

The email of the account holder.

name

The name of the account holder.

Request 

curl https://api.getchange.io/api/v1/accounts \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json" \
  -d '{
        "email": "[email protected]",
        "name": "Jane Doe"
      }'

Response

{
  "id": "a_0aoQ4Myyc9yHgSVcziJIxg1p",
  "name": "Jane Doe",
  "active": false,
  "email": "[email protected]",
  "signed_agreement": false,
  "sign_page_url": "",
  "saved_payment_method": false
}

post /api/v1/accounts/{id}/link_bank_token

Creates a link token for the account. Link tokens are used on the client for connecting bank accounts via Plaid Link. See the Build a Marketplace recipe for usage instructions.

Parameters

id string REQUIRED

The id of an account. Ids are returned when an account is created.

Request 

curl https://api.getchange.io/api/v1/accounts/a_wh6BDyemeU4bxrD2LdIUBR1e/link_bank_token \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -H "Content-Type: application/json"

Response

"link-sandbox-9912b386-eef4-44e1-b3bf-56ea5fd372ec"

Attach a bank to a managed account

post /api/v1/accounts/attach_bank_account

Attaches a bank account to a managed account via bank link token. See the Build a Marketplace recipe for usage instructions.

Parameters

link_token REQUIRED

A link token from Change. Generate link tokens using the Create a link bank token endpoint.

plaid_public_token REQUIRED

A public token generated by Plaid. See the Build a Marketplace recipe to learn how to get this token.

bank_account_id REQUIRED

A bank account id generated by Plaid. See the Build a Marketplace recipe to learn how to get this token.

Request 

curl https://api.getchange.io/api/v1/accounts/attach_bank_account \
  -H "Content-Type: application/json" \
  -d '{
        "link_token": "link-sandbox-000000000000000000000000000000000000",
        "plaid_public_token": "public-sandbox-000000000000000000000000000000000000",
        "bank_account_id": "1111111111111111111111111111111111111"
      }'

Response

{
  "id": "a_LARt1HYpxrx9nZ24TbOgJOGT",
  "name": "EmmerichLLC",
  "active": true,
  "email": "[email protected]",
  "signed_agreement": true,
  "sign_page_url": "",
  "saved_payment_method": true
}

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": [
    {
      "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/public-benefit.png",
      "id": "n_MUjmT5yhdf4smx1ykRwO2ovt",
      "name": "One Tree Planted Inc",
      "ein": "464664562",
      "socials": {
        "facebook": "onetreeplanted",
        "instagram": "onetreeplanted",
        "twitter": "onetreeplanted",
        "youtube": "channel/UCSyNWLnxtob29DOoPGpT1Ug"
      },
      "email": "[email protected]",
      "display_impact": [
        "$1 sponsors one tree planted"
      ],
      "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",
      "display_aggregate_impact": [
        "326.7 trees planted"
      ]
    },
    {
      "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/healthcare.png",
      "id": "n_nIstMceV5IXNWwMOzomgHEEV",
      "name": "Aim For Mental Health Inc",
      "ein": "473992060",
      "socials": {
        "facebook": "AIMforMentalHealth",
        "instagram": "aimmentalhealth",
        "twitter": "AimMentalHealth",
        "youtube": "channel/UCoBov-MpEPB14BrIWY96m5A"
      },
      "email": null,
      "display_impact": [],
      "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",
      "display_aggregate_impact": [
        "$479.00 donated"
      ]
    }
  ],
  "filters": {
    "end_timestamp": 1630605175
  }
}
Made with ❤ in San Francisco