# Welcome to the Cooler API Enabling you to footprint carbon emissions through a set of simple APIs. The Cooler API enables you to calculate the carbon emissions (the carbon footprint) of products and services included within transactions using the simple *Footprint* endpoint, and to retrieve them using the *Transactions* endpoints. These APIs are the same we depend on for the Cooler Certified web application, which helps small businesses measure and neutralize\* their carbon emissions. *\*In the near future, you will be able to neutralize those emissions through the neutralization endpoints, as reflected in the Cooler app. Learn more at * ### Free Accounts Free accounts are limited to 10 requests per minute. and will receive a static footprint value in the API responses. To get live, real footprints, please sign up for the Pro account. ### Ready? [Get your production and test API Keys here](< https://app.cooler.dev/docs-redirect>) and through an app account. Get started right away in the [Quick Start Guide](/quick-start) ### What is Cooler? Cooler is a climate-change software company that provides automated tools for measuring and neutralizing carbon footprints in service of our mission to reduce the negative impact of business operations on global warming. \ \ We measure carbon footprints by analyzing transactions with our deeply researched, science-based carbon calculator, which uses a hybrid EEIO-LCA approach, and neutralize by purchasing carbon emissions permits from cap-and-trade markets on your behalf. Ultimately, we’re working to help you measure and neutralize as much CO2 emissions as possible to significantly reduce carbon production and decrease the greenhouse gases emitted into our air and atmosphere through commerce. # Quick Start ### The Cooler API: Measuring Carbon Footprints Use Cooler's carbon calculator API to calculate the carbon footprint of every item within your transactions. The calculator can be updated, sometimes monthly, based on a variety of economic factors. Learn more about our methodology here. ### Get your API keys Your API requests are authenticated using unique API keys. Cooler provides both a production key and a test key, allowing you to test your applications without incurring any charges. Any request that does not include an API key will result in an error. Navigate to your [account settings](< https://app.cooler.dev/docs-redirect>) to retrieve your API keys. ### Make your first footprint request Send an authenticated request to the Footprint endpoint to calculate the carbon footprint of the product or products in a transaction. You can use the default test key or your Cooler API test or production key. \ \ **NOTES**\ **CO2e** results are always in kilograms (**kg**)\ **Price** is always in dollars-cents format **$$.¢¢**, i.e. $500, $500.23, etc. \ \ For more examples, see the [API Reference](/api-reference). {% tabs %} {% tab title="curl" %} ```shell curl -X POST https://api.cooler.dev/v2/footprint/products \ -H "Content-Type: application/json" \ -H "Cooler-Api-Key: cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05" \ -d '{ "items": [{ "productPrice": 500, "productName": "Samsung A7 Galaxy", "productDescription": "Samsung A7 Galaxy", "postalCode": "02062", "newProduct": true, "externalId": "6c233e4f-3f55-43fe-b67b-0ce50e5f7177" }] }' ``` {% endtab %} {% endtabs %} ### Performance The first time Cooler footprints a product, there is a bit of latency as it categorizes and footprints the items in your transactions. Future footprinting of that same product is typically very fast. Our platform currently runs on Google Cloud and scales with demand. Though we observe system performance and uptime constantly, please let us know if you experience any performance issues by emailing support\@. # API Reference The Cooler API The Cooler API consists of three RESTful endpoints: * v2/footprint: returns the carbon footprint of each item in a transaction * transaction: returns an individual footprinted transaction by id * transactions: returns a range of one or more footprinted transactions # Carbon Footprint ## Carbon Footprint API The Footprint endpoint calculates and returns the carbon footprint(s) for one or more products within a single transaction, given a well-formed JSON request containing required properties, as shown in the examples below.\ \ Note that all footprint requests must include your API key from your Cooler [account](https://app.cooler.dev/settings). #### Parameters | KEY | TYPE | DESCRIPTION | EXAMPLE | | -------------------- | ------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | productName\* | string | name or title of the product | Samsung A7 Galaxy | | productDescription\* | string | \*product description | Keep up with life with your fast paced life with a phone that fits you, like the Samsung Galaxy A14 5G from Total by Verizon. With the speed of 5G and a powerful Galaxy processor, you can experience your day virtually lag-free. | | productPrice\* | number | price of the product | 500 | | postalCode | string | postal code of the product when it ships to the customer or your store | 49503 | | newProduct | boolean | new=true, used=false | true | | externalId | string | your system’s product id | your\_product\_id | #### Reponse Data ```json { "id": "1900b667-fbcf-4f0e-9512-b0f3b4e4e9f7", "items": [ { "id": "35c627b9-8249-427a-a050-5e3360e67503", "submission": { "id": "f2480103-0aba-4c78-826e-c03a92e130ec", "zip": "02062", "currency": "USD", "title": "Samsung A7 Galaxy", "price": 500, "description": "Samsung A7 Galaxy", "newProduct": true, "externalId": "id_you_assigned" }, "footprint": { "id": "812c7561-8448-445a-b43b-43e0659e87a4", "currency": "USD", "expiresAt": "2025-01-20T22:41:10.430Z", "carbonFootprint": 1234, "carbonFootprintSavings": null } } ], "dateCreated": "2025-01-13T22:41:10.149Z", "dateUpdated": "2025-01-13T22:41:10.149Z" } ``` ### Code Examples The following code examples use our test key—remember to replace the key with your own in your own code when calling the endpoints for production. **Javascript** ```javascript const apiUrl = "https://api.cooler.dev/v2/footprint/products"; const headers = { "Content-Type": "application/json", "Cooler-Api-Key": "cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05", }; // Define the request payload const requestBody = { items: [ { productPrice: 500, productName: "Samsung A7 Galaxy", productDescription: "Samsung A7 Galaxy", }, ], }; // Make the POST request using fetch fetch(apiUrl, { method: "POST", // Specify the HTTP method headers: headers, // Include headers body: JSON.stringify(requestBody), // Convert the payload to JSON }) .then((response) => { // Check if the response status is OK (200-299) if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.json(); // Parse the JSON response }) .then((data) => { console.log("Response:", data); // Log the successful response }) .catch((error) => { console.error("An error occurred:", error.message); // Log any errors }); ``` **Curl** ```shell curl https://api.cooler.dev/v2/footprint/products \ --request POST \ --header "Content-Type: application/json" \ --header "Cooler-Api-Key: cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05" \ --data '{ "items": [ { "productPrice": 500, "productName": "Samsung A7 Galaxy", "productDescription": "Samsung A7 Galaxy" } ] }' ```
# Transactions You can retrieve a one or more footprinted transactions using the *Transaction* and *Transactions* endpoints. Let’s start by fetching a single transaction.\ \ Note: make sure you use an actual transaction id, which you can get by footprinting a product. ### Get a Specific Transaction **Parameters** | KEY | TYPE | DESCRIPTION | | --- | ------ | -------------- | | id | string | transaction id | #### **Response** ```json { "id": "0f958fc5-e786-4d81-88ea-9bd8811d39e4", "items": [ { "id": "b4435ef8-f17e-480e-b247-3394f4befa78", "submission": { "id": "e30191b7-15fe-4dcd-aeaf-d9f5d96d61fa", "zip": "02062", "sku": null, "currency": "USD", "manufacturer": null, "title": "Samsung A7 Galaxy", "price": 500, "category": null, "description": "Samsung A7 Galaxy", "isUsed": false }, "footprint": { "id": "27eb7a5c-10d2-4549-9abb-5a8142ff3e47", "currency": "USD", "expiresAt": "2025-01-15T21:11:19.401Z", "carbonFootprint": 108, "carbonFootprintSavings": null } } ], "dateCreated": "2025-01-08T21:11:19.114Z", "dateUpdated": "2025-01-08T21:11:19.114Z" } ``` ### **Code Examples** **Javascript** ```javascript // Define the API endpoint and headers const transactionId = "e03304b0-ba04-4a28-b66e-dcfbc1a62c22"; // Replace with your own transaction ID const apiUrl = `https://api.cooler.dev/v1/transactions/${transactionId}`; const headers = { "Cooler-Api-Key": "cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05", }; // Make the GET request using fetch fetch(apiUrl, { method: "GET", headers: headers, }) .then((response) => response.json()) // Parse the JSON response .then((data) => console.log(data)) // Log the response data .catch((error) => console.error("Error:", error)); // Log any errors ``` **Curl** ```shell curl -X 'GET' \ 'https://api.cooler.dev/v1/transactions/0f958fc5-e786-4d81-88ea-9bd8811d39e4' \ -H 'accept: */*' \ -H 'COOLER-API-KEY: cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05' ``` #### Get Multiple Transactions Get one or more transactions. **Parameters** | KEY | TYPE | DESCRIPTION | | ----- | ------ | ---------------------------------------------------------------- | | skip | number | the number of transactions to skip before returning transactions | | limit | number | the maximum number of transactions to return | | env | string | dev environment; either “sandbox” or “production” | **Response** **Code Examples** ```javascript // Define the API endpoint and headers const apiUrl = "https://api.cooler.dev/v1/transactions"; const headers = { "Cooler-Api-Key": "cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05", }; // Define query parameters const queryParams = new URLSearchParams({ skip: 0, // Number of records to skip (pagination) limit: 10, // Number of records to return env: "sandbox", // Environment filter (optional) }).toString(); // Make the GET request using fetch fetch(`${apiUrl}?${queryParams}`, { method: "GET", headers: headers, }) .then((response) => response.json()) // Parse the JSON response .then((data) => console.log("Transactions:", data)) // Log the response data .catch((error) => console.error("Error:", error)); // Log any errors ``` Let’s try that in curl: ```sh curl -X GET "https://api.cooler.dev/v1/transactions?skip=0&limit=10&env=sandbox" \ -H "Cooler-Api-Key: cooler_test_acaf38b8-5d04-4aa4-87fe-91a67fc13a05" ``` # Performance The first time Cooler footprints a product, there is a bit of latency as it categorizes and footprints the items in your transactions. Future footprinting of that same product is typically very fast. Our platform currently runs on Google Cloud and scales with demand. Though we observe system performance and uptime constantly, please let us know if you experience any performance issues by emailing support@
# Methodology ### Footprinting Cooler uses peer-reviewed methodologies and rigorous scientific standards to deliver highly accurate and conservative carbon footprint calculations through our carbon calculator. Developed by [Dr. Michel Gelobter](https://www.cooler.dev/about) in collaboration with leading global, U.S., and European environmental organizations, our tools ensure that we assess and neutralize carbon emissions with the utmost integrity. It’s important to note that all carbon calculators produce estimates, not exact measurements. Cooler’s calculators provide real-time carbon footprints for consumer goods and services up to the point of sale. Using an EEIO-LCA hybrid approach, our methodology adheres to the most environmentally conservative interpretation of the Greenhouse Gas Protocol, covering Scopes 1, 2, and 3 emissions. Calculations require minimal input—such as the name of your product or service and its price. From there, Cooler leverages economic and engineering data across approximately 2,000 underlying categories and variables to estimate the carbon footprint. ### Neutralizing Emissions Cooler’s approach to emissions neutralization directly reduces industrial CO2 pollution at its source while supporting economic, social, and environmental development through community reinvestment of funds used to neutralize emissions. This service is provided automatically to our app customers, and can be extended to API users—just contact us at support@ to get started with neutralizing your carbon emissions. ### Pooled Impact Cooler pools your emissions-neutralizing fees with those from other customers to purchase pollution permits in regulated cap-and-trade markets. By reducing the availability of permits, we force industrial polluters to lower their emissions. This process certifiably eliminates greenhouse gases by preventing polluters, such as power plants, from acquiring the permits they need to emit CO2. Then, in a virtuous cycle, the permit fees are invested in conservation and clean energy projects that have generated thousands of jobs. So when you neutralize with Cooler, you’re not just stopping new carbon emissions, you’re investing in a clean, green future. ### Environmental Rights By curbing CO2 pollution and financing clean energy projects, we are also supporting fenceline and frontline communities that bear the burden of both pollution and climate change earliest and most acutely. Carbon Offsets vs Neutralizing Cooler’s method of eliminating your carbon footprint is not the same as carbon offsets. Offsets are often used by polluters to maintain business as usual and are frequently criticized for being both quantitatively and qualitatively unreliable, while Cooler’s method leads to actual, traceable reductions in GHG emissions. Here’s some [light reading](https://www.theguardian.com/environment/2023/jan/18/revealed-forest-carbon-offsets-biggest-provider-worthless-verra-aoe) on the issues with carbon offsets from a recent article. # Billing Cooler handles billing through Stripe. The following is our current pricing: | Plan | Per footprint | | --------- | ------------------------------------------- | | Developer |

free with test key,
rate limited

| | Pro | starts at .00/transaction |
Get your [Cooler account here](https://docs.cooler.dev/api-docs-home/app.cooler.dev/auth/signup), or [click here to select a plan](https://app.cooler.dev/settings/billing) if you already have a Cooler account.