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 number REQUIRED

The amount of the donation in cents.

nonprofit_id string REQUIRED

The id of a nonprofit from the CHANGE network.

funds_collected boolean REQUIRED

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

zip_code string

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

order_value number

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

external_id string

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

Request 

curl https://api.getchange.io/api/v1/donations \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -d 'amount=500&nonprofit_id=n_IfEoPCaPqVsFAUI5xl0CBUOx&funds_collected=true&zip_code=94104&order_value=2599&external_id=customer_1234'

Response

{
  "amount": 500,
  "id": "d_9NZ3KO6RdxUFz5Z3X9rGwlJo",
  "live_mode": true,
  "merchant_id": "m_9PQ6FQIntizelcJ1NH8lYv19",
  "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
  "order_value": null,
  "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.

Request 

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

Response

{
  "donations": [
    {
      "amount": 80658.58,
      "id": "d_l0Ymt3WrK51Bnv2OJDeKvt1i",
      "live_mode": true,
      "merchant_id": "m_GF04EsAg3Ln3iDWdn6KzO7CT",
      "nonprofit_id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
      "order_value": 4111,
      "zip_code": "63076",
      "external_id": null
    },
    {
      "amount": 87046.28,
      "id": "d_T4GD98q2DMjvJeb86Z2Q9P1U",
      "live_mode": true,
      "merchant_id": "m_GF04EsAg3Ln3iDWdn6KzO7CT",
      "nonprofit_id": "n_nIstMceV5IXNWwMOzomgHEEV",
      "order_value": 1705,
      "zip_code": "96876-2501",
      "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_NuYL6M2C1kjecXpWzKVODw7W \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY

Response

{
  "amount": 70668.54,
  "id": "d_JRJs8wYoUGwrfPAYGK5We8tY",
  "live_mode": true,
  "merchant_id": "m_mo6Xeqp0i5MXJ776gPHaq9KA",
  "nonprofit_id": "n_MUjmT5yhdf4smx1ykRwO2ovt",
  "order_value": 1226,
  "zip_code": "73156-2050",
  "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/c_NuYL6M2C1kjecXpWzKVODw7W/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/T.png",
  "id": "n_MUjmT5yhdf4smx1ykRwO2ovt",
  "name": "ONE TREE PLANTED",
  "ein": "464664562",
  "memo": null,
  "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"
}

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.

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": [
    {
      "id": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
      "name": "WATSI",
      "ein": "453236734",
      "memo": null,
      "last_verified_at": null,
      "mission": "Directly connecting people through technology to provide global access to healthcare.",
      "address_line": "548 Market St # 75903",
      "state": "CA",
      "city": "San Francisco",
      "zip_code": "94104",
      "website": "https://watsi.org/",
      "classification": "E12",
      "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/E.png"
    }
  ],
  "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"
  }
]

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.

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

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 boolean 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 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.

offset_id string

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 number

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

transportation_method string
Enum: air|truck|rail|sea

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

weight_lb number

The total weight (in pounds) of the shipment.

zip_code string

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

Request 

curl https://api.getchange.io/api/v1/climate/shipping_offset \
  -u YOUR_PUBLIC_KEY:YOUR_SECRET_KEY \
  -d 'funds_collected=true&destination_address=94133&origin_address=60148&transportation_method=air&weight_lb=3.5&zip_code=94104'

Response

{
  "amount": 18,
  "id": "c_jyWsp1Qu10TcW5KtxtiKyi8j",
  "live_mode": true,
  "merchant_id": "m_7dWHER5BmYlGy221O5VcyT1M",
  "order_value": null,
  "zip_code": "94104",
  "external_id": null
}

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.

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

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 boolean 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 number

The number of transactions to offset.

currency string
Enum: eth|btc|sol

The currency of the transaction.

offset_id string

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

zip_code string

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

Request 

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

Response

{
  "amount": 76,
  "id": "c_CtBaOkBEgiwuPHAppl0BsqRi",
  "live_mode": true,
  "merchant_id": "m_zgqBFheitz0ifGErNxDzw7t5",
  "order_value": null,
  "zip_code": "94104",
  "external_id": null
}

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
}
Made with ❤ in San Francisco