# Create Checkout Session Source: https://docs.cnaught.com/api-reference/checkout-sessions/create-checkout-session /api-reference/openapi.yaml post /checkout/sessions Creates a Checkout Session that, when completed, will result in an order for the specified amount of carbon credits (in kilograms). The total price must be at least $0.50 (the corresponding amount will depend on the per kg price of the specified portfolio). The Quotes API can be used to check the price before attempting to create a session. # Get Checkout Session Source: https://docs.cnaught.com/api-reference/checkout-sessions/get-checkout-session /api-reference/openapi.yaml get /checkout/sessions/{id} Returns the Checkout Session with the given id # Get Climate Impact Data Source: https://docs.cnaught.com/api-reference/climate-impact/get-climate-impact-data /api-reference/openapi.yaml get /impact/data Returns information about the total climate impact of the carbon credit purchases for this account (or a subaccount). This is the underlying information that is displayed on the hosted public impact page for the account / subaccount. You can optionally use the 'from' and/or 'to' query parameters to only show impact for orders in a particular time period. # Get Hosted Climate Impact Page Configuration Source: https://docs.cnaught.com/api-reference/climate-impact/get-hosted-climate-impact-page-configuration /api-reference/openapi.yaml get /impact/hosted-page-config Returns information about the hosted public climate impact page configuration for the account (or a subaccount) # Overview Source: https://docs.cnaught.com/api-reference/introduction Our API allows you to easily purchase carbon credits for various activities. ## API endpoint The base URL for this version of the API is `https://api.cnaught.com/v1`. All endpoints described in this documentation are relative to this base URL. ## Authentication Clients must authenticate by including their [CNaught API Key](security.md#api-key) in the `Authorization` header. If the API key is invalid, a `401` error code will be returned. ## Subaccounts Subaccounts can be used to segregate your orders. For example, you could segregate orders by department. Or, if you are using CNaught to provide carbon credits to your customers, you could use a different subaccount for each customer. You can then retrieve orders or impact data for just that subaccount. You can specify a subaccount by including a `X-Subaccount-Id` header in an API call. Doing so in the [Place order](/api-reference/orders/create-carbon-credits-order) API call will associate the order with that subaccount, and doing so in the [Get List of Orders](/api-reference/orders/get-list-of-orders) API call will only retrieve orders associated with that subaccount. All APIs which support specifying a subaccount will mention it in their reference documentation. A subaccount can have its own default portfolio, which changes the price of an order placed for it. If you quote a purchase before placing it, pass the same `X-Subaccount-Id` header to both the quote and the order call — otherwise the quote is priced against your organization's default portfolio while the order is fulfilled from the subaccount's, and the two can disagree. We will need to provision your account for subaccount support before you can create and use subaccounts. Please contact `support@cnaught.com` if you would like to use this feature. ## Checkout Sessions A Checkout Session represents a user's session as they pay for a one-time purchase of carbon credits. Checkout Sessions are most commonly used in conjuntion with Subaccounts. The API flow will look something like the following: 1. User clicks CTA for purchasing credits 2. Create Subaccount for user 3. Create Checkout Session for the Subaccount (provide a `success_url` to redirect the user to once they complete checkout) 4. Redirect user to `checkout_url` of the session. This is essentially a hosted checkout page that will securely handle the purchase of carbon credits. 5. User fills in payment method info and completes checkout. At this point, CNaught will be notified of the session completion and handle fulfilling the carbon credits. 6. The user will be automatically redirected to `success_url`. ## Webhooks When placing orders, if the optional `notification_config` parameter is provided, the API will make an HTTP POST request to the URL specified in that parameter with details in the request body when the order state changes - eg an order becomes fulfilled or is cancelled. Here is an example of the POST request body sent after an order becomes fulfilled ```json theme={null} { "order": { "id": "Gre28Fc35bt3", "state": "fulfilled", "placed_on": "2018-05-05T23:23:22.29Z", "amount_kg": 356.25, "price_usd_cents": 2350 } } ``` * The API will make a POST request, not a GET request, to the `notification_config.url` parameter. The request body will contain the order details. * To acknowledge the webhook has been successfully received and processed, respond with a `200` response code. * If a webhook invocation does not receive a `200` response, CNaught will periodically retry the callback URL until either 24 hours have passed or a `200` response code is received. ## Rate limiting The CNaught API employs rate limiting to help maximize stability. Users who exceed these limits may see 429 responses. The current limits are 100 write and 100 read operations per second, though these may change. Your code should handle rate limiting gracefully by building a retry mechanism. We recommend the retry mechanism to follow a randomized exponential backoff schedule. ## Idempotency The CNaught API supports idempotency for order placement / cancellation, allowing you to retry a request multiple times while only performing the action once. This helps avoid unwanted duplication in case of failures and retries. For example, in the case of a timeout error, it is possible to safely retry sending the same API order placement call multiple times with the guarantee that the order will only be placed once. To enable idempotency for an API request, include the `Idempotency-Key:` header in the request. The `` should be a unique identifier for the request with a maximum of 512 characters. If you don't receive a response (for example, in case of a timeout), you can safely retry the request with the same header. If CNaught has already processed the request, the response to the first attempt will be returned without duplication. This will be indicated by the inclusion of a `X-Idempotent-Replay: true` header in the response. How you create unique keys is up to you - one possibility is V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are expected to be unique per user account. Submitting a request with the same idempotency key as a previous request but different payload (e.g. different URL or request body) will result in a `422` response status code a problem details response body with a type of `https://api.cnaught.com/v1/errors/idempotency-changed-payload`. This is done to prevent accidental mistakes due to client logic bugs. If a request with an idempotency key is submitted while a previous request with the same idempotency key is still being processed, a `409` response status code and a problem details response body with a type of `https://api.cnaught.com/v1/errors/idempotency-concurrent-requests` is returned. In this case, your application should retry the request after a short delay. Both success and error responses are eligible to be cached and returned without execution for an idempotent request. The few exceptions are error responses corresponding to transient conditions: e.g. `409` conflict responses as described above, `429` responses due to rate limiting, or any `5xx` responses due to temporary server errors. Idempotency keys are scoped to your user account and expire after 24 hours. ## Error codes The API indicates failure with `4xx` and `5xx` HTTP status codes. `4xx` status codes indicate an error due to the request provided (for example, a required parameter was omitted). `5xx` error indicate an error with CNaught's servers. When an 4xx error occurs during invocation of a request, the API responds with a [problem details](https://tools.ietf.org/html/rfc7807) HTTP response payload. Some common errors returned by the API, and their meanings are: | Status Code | Error | Description | | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Bad Request | The request contained some invalid parameters. The details are specific to the operation in question | | 401 | Unauthorized | A request did not have a valid, active API key corresponding to an active user | | 403 | Forbidden | A request could not be processed because the relevant order or user was not in a state where the requested operation is valid. The details are specific to the operation in question. | | 409 | Conflict | A second request with same Idempotency Key as a previous one was submitted while the previous request was still processing. Retry the request after backoff. | | 422 | Unprocessable Entity | A second request with same Idempotency Key as a previous one but with different payload was submitted. This likely indicates a logic error in the client code. | | 429 | Too Many Requests | A rate limit was exceeded for an API request. Retry the request with expontential backoff. | | 503 | Service Unavailable | The API is temporarily offline due to some infrastructure component (eg database) being unavailable. Retry the request with exponential backoff. | Some errors can be resolved simply by retrying the request. The following error codes are likely to be resolved with successive retries. | Status Code | Error | | ----------- | ------------------- | | 409 | Conflict | | 429 | Too Many Requests | | 502 | Bad Gateway | | 503 | Service Unavailable | | 504 | Gateway Timeout | The individual API endpoints further document the possible error codes they can return. Except for the `429` status code, it is recommended that the maximum number of retries be limited to 5 attempts per request. The number of retries can be higher for `429` errors but if you notice consistent throttling, please contact the support team at [support@cnaught.com](mailto:support@cnaught.com). ### Error object The problem details information is represented as a JSON object with the following optional properties: | Property | Description | | --------- | ------------------------------------------ | | `type` | A URI representing the type for the error | | `title` | A short human readable description of type | | `details` | Additional details of the error | | `status` | HTTP status code of the error | In addition to the properties listed above, the problem details object may list additional properties that help to troubleshoot the problem. Here is an example of a response to a submit order request with a missing required parameter: ```json theme={null} { "errors": { "amount_kg": [ "The amount_kg field is required." ] }, "type": "https://api.cnaught.com/v1/errors/invalid-parameters", "title": "Your request parameters didn't validate", "status": 400 } ``` # Cancel Order Source: https://docs.cnaught.com/api-reference/orders/cancel-order /api-reference/openapi.yaml post /orders/{id}/cancel When cancelling an order that has been fulfilled, a credit for the price of the order will be applied to the current invoice. This means that it is possible for the credit for a cancellation to appear on the invoice of the following billing period. For example, if a billing period ends between when the order was placed and when it is cancelled, then the credit will be applied to the latter billing period rather than the one during which the order was placed. # Create Carbon Credits Order Source: https://docs.cnaught.com/api-reference/orders/create-carbon-credits-order /api-reference/openapi.yaml post /orders Places an order for the specified amount of carbon credits (in kilograms), or for the specified total price (in USD cents). The order will remain in the `placed` state until it can be matched to available credits, after which the order will be fulfilled and moved to the `fulfilled` state. If specifying total price, we will determine the amount of carbon credits based on the unit price of the portfolio used for the order. Because the amount must be an integer number of kilograms, the final actual total price might be slightly different than the specified total price. # Create Carbon Credits Order for Vehicle Ride Source: https://docs.cnaught.com/api-reference/orders/create-carbon-credits-order-for-vehicle-ride /api-reference/openapi.yaml post /orders/ride [Deprecated] Use `/quotes/ground-transport` with `passenger_car_van_or_suv` as the `vehicle_type` to calculate ride emissions. Then pass the result to `/orders` to place the order.

Places an order for carbon credits for a vehicle ride of the given distance (in kilometers). The order will remain in the `placed` state until it can be matched to available credits, after which the order will be fulfilled and moved to the `fulfilled` state. # Get List of Orders Source: https://docs.cnaught.com/api-reference/orders/get-list-of-orders /api-reference/openapi.yaml get /orders Gets a list of orders in reverse chronological order up to the provided `limit` number of orders per call. Pagination is supported by passing the first order `id` from a previous call into `ending_before` to retrieve the previous page, or the last order `id` from a previous call into `starting_after` to retrieve the next page. # Get Order By Id Source: https://docs.cnaught.com/api-reference/orders/get-order-by-id /api-reference/openapi.yaml get /orders/{id} Returns information about an order # Get List of Portfolios Source: https://docs.cnaught.com/api-reference/portfolios/get-list-of-portfolios /api-reference/openapi.yaml get /portfolios Gets the list of portfolios the user is able to use for purchasing credits. This list is not paginated - the full list of portfolios is returned. The portfolio objects in the list do not include details about the project categories comprising the portfolio - those can be retrieved for each portfolio using the [Get Portfolio By Id](/api-reference/portfolios/get-portfolio-by-id) API endpoint. # Get Portfolio By Id Source: https://docs.cnaught.com/api-reference/portfolios/get-portfolio-by-id /api-reference/openapi.yaml get /portfolios/{id} Returns information about a portfolio, including the project categories that comprise the portfolio, as well as price info. # Get Project By Id Source: https://docs.cnaught.com/api-reference/projects/get-project-by-id /api-reference/openapi.yaml get /projects/{id} Returns information about a project, including credit issuances by vintage year # Get Project Category By Id Source: https://docs.cnaught.com/api-reference/projects/get-project-category-by-id /api-reference/openapi.yaml get /project-categories/{id} Returns information about a project category # Get Quote by Emissions Mass Source: https://docs.cnaught.com/api-reference/quotes/get-quote-by-emissions-mass /api-reference/openapi.yaml post /quotes Get a price quote for offsetting the given amount of carbon emissions. # Get Quote for Air Freight Emissions Source: https://docs.cnaught.com/api-reference/quotes/get-quote-for-air-freight-emissions /api-reference/openapi.yaml post /quotes/air-freight Get a price quote for offsetting air freight shipment carbon emissions. Will return the amount of CO₂e to offset and total price. # Get Quote for Flight Emissions Source: https://docs.cnaught.com/api-reference/quotes/get-quote-for-flight-emissions /api-reference/openapi.yaml post /quotes/flight Get a price quote for offsetting flight carbon emissions. Will return the amount of CO₂e to offset and total price. # Get Quote for Ground Freight Emissions Source: https://docs.cnaught.com/api-reference/quotes/get-quote-for-ground-freight-emissions /api-reference/openapi.yaml post /quotes/ground-freight Get a price quote for offsetting ground freight shipment carbon emissions. Will return the amount of CO₂e to offset and total price. # Get Quote for Ground Transport Emissions Source: https://docs.cnaught.com/api-reference/quotes/get-quote-for-ground-transport-emissions /api-reference/openapi.yaml post /quotes/ground-transport Get a price quote for offsetting ground transportation carbon emissions. Will return the amount of CO₂e to offset and total price. # Get Quote for Office Space Emissions Source: https://docs.cnaught.com/api-reference/quotes/get-quote-for-office-space-emissions /api-reference/openapi.yaml post /quotes/office-space Get a price quote for offsetting office space carbon emissions. Will return the amount of CO₂e to offset and total price. # Get Quote for Train Emissions Source: https://docs.cnaught.com/api-reference/quotes/get-quote-for-train-emissions /api-reference/openapi.yaml post /quotes/train Get a price quote for offsetting train carbon emissions. Will return the amount of CO₂e to offset and total price. # Get Vehicle Ride Credits Price Quote Source: https://docs.cnaught.com/api-reference/quotes/get-vehicle-ride-credits-price-quote /api-reference/openapi.yaml post /quotes/ride [Deprecated] Use `/orders/ground-transportation` and pass `passenger_car_van_or_suv` as the `vehicle_type`.

Get a price quote for offsetting car ride carbon emissions. Will return the amount of CO₂e to offset and total price. # Create Subaccount Source: https://docs.cnaught.com/api-reference/subaccounts/create-subaccount /api-reference/openapi.yaml post /subaccounts Creates a new Subaccount. # Delete Subaccount Source: https://docs.cnaught.com/api-reference/subaccounts/delete-subaccount /api-reference/openapi.yaml delete /subaccounts/{id} Deletes the Subaccount with the given id. This operation will fail if the subaccount has orders associated with it. # Get List of Subaccounts Source: https://docs.cnaught.com/api-reference/subaccounts/get-list-of-subaccounts /api-reference/openapi.yaml get /subaccounts Gets a list of subaccounts in reverse chronological order up to the provided `limit` number of subaccounts per call. Pagination is supported by passing the first subaccount `id` from a previous call into `ending_before` to retrieve the previous page, or the last subaccount `id` from a previous call into `starting_after` to retrieve the next page. # Get Subaccount By Id Source: https://docs.cnaught.com/api-reference/subaccounts/get-subaccount-by-id /api-reference/openapi.yaml get /subaccounts/{id} Returns information about a subaccount # Remove Logo From Subaccount Source: https://docs.cnaught.com/api-reference/subaccounts/remove-logo-from-subaccount /api-reference/openapi.yaml delete /subaccounts/{id}/logo Removes the logo for a Subaccount with given id. # Update Subaccount Source: https://docs.cnaught.com/api-reference/subaccounts/update-subaccount /api-reference/openapi.yaml put /subaccounts/{id} Updates the Subaccount with the given id. This does not include updating the logo: there are separate endpoints for doing so. Aside from the logo, all properties should be included in the request body. Not including the default portfolio id in the update request will have the effect of making the subaccount not have an explicit default portfolio (making it inherit the default portfolio from the parent user). # Update Subaccount Logo By Uploading Image Content Source: https://docs.cnaught.com/api-reference/subaccounts/update-subaccount-logo-by-uploading-image-content /api-reference/openapi.yaml put /subaccounts/{id}/logo Updates the logo for a Subaccount with given id with the image contents sent in the request body. The request body should be the binary image contents in a supported image format, and the request should include a Content-Type header specifying the image content type. Supported image types are: PNG (image/png), JPEG (image/jpeg), WEBP (image/webp), and SVG (image/svg+xml). # Update Subaccount Logo From URL Source: https://docs.cnaught.com/api-reference/subaccounts/update-subaccount-logo-from-url /api-reference/openapi.yaml post /subaccounts/{id}/logo Updates the logo for a Subaccount with given id by downloading from given URL. The URL should point to a valid image in a supported image format, and should include the content type for the image in the HTTP response when the image is retrieved from the URL. Supported image types are: PNG (image/png), JPEG (image/jpeg), WEBP (image/webp), and SVG (image/svg+xml). # Changelog Source: https://docs.cnaught.com/changelog This page documents all notable changes to this project. ## 2026-01-14 / APIs, Documentation * Eliminated sandbox environment, updated quickstart guide and FAQ accordingly. ## 2025-03-06 / APIs * Added price information for a portfolio to [Get Portfolio By Id](/api-reference/portfolios/get-portfolio-by-id) API. * Added additional fields and credit issuance data to [Get Project By Id](/api-reference/projects/get-project-by-id) API. * Added [Delete Subaccount By Id](/api-reference/subaccounts/delete-subaccount) API ## 2024-03-23 / APIs * Added option to place generic orders by specifying total order price. ## 2024-01-30 / APIs * Added APIs for adding, updating and removing logo images for subaccounts. ## 2024-01-27 / APIs * Added APIs for retrieving project details by id , project category details by id , portfolio details by id and list of portfolios for user. ## 2023-11-09 / Node SDK * Node SDK version 2.0.0 \*\* The SDK is now based on fetch instead of Axios. Axios relies on XMLHttpRequest which isn't supported in Cloudflare Workers, Next.js Edge, Deno, Bun, etc. By using fetch, the SDK is now compatible with those runtimes. \*\* All API methods now allow specifying additional options to send to fetch . This enables you to control framework-specific fetch behavior (eg revalidate for Next.js) \*\* The SDK is now distributed as an ESM module \*\* Added support for subaccounts for grouping related orders. \*\* Added APIs for retrieving climate impact data and hosted impact page configuration . ## 2023-11-01 / APIs * Added support for subaccounts for grouping related orders. * Added APIs for retrieving climate impact data and hosted impact page configuration . ## 2023-10-10 / APIs * Added order number to order details ## 2023-09-25 / APIs * Get Order API now includes information about projects used to fulfill the order * Place Order API now allows specifying the portfolio to use for the order ## 2022-11-10 / APIs * Implemented Idempotency Key support. ## 2022-10-27 / Website * Send users daily digest of transactions. Who doesn't like more emails? ## 2022-10-21 / Node SDK * Updated node SDK to support cancelling orders ## 2022-10-07 / APIs * Added ability to cancel orders through the API via the /orders//cancel URI. * The docs can be found here. ## 2022-08-26 / Node SDK * Node SDK initial release. [https://twitter.com/shrutikapoor08/status/1006655474270232576](https://twitter.com/shrutikapoor08/status/1006655474270232576) ## 2022-08-19 / APIs * Added ability to get price quote before placing order. No code survives contact with the user. ## 2022-07-31 / APIs * Initial release of API. Hello World, we made a thing! Changes previous to the oldest date in this document are not noted in this changelog. # Examples Source: https://docs.cnaught.com/examples These examples demonstrate how to build carbon credit user experiences with the CNaught APIs. Web app for offsetting travel to events, built with Next.js and CNaught TypeScript SDK. Demonstrates using the API to purchase carbon credits, and retrieve and display total climate impact, as well as implementing webhooks. Additional examples will be added as we build them. # FAQ Source: https://docs.cnaught.com/faq You have questions? We have answers #### What does CNaught do? CNaught is a software company that enables organizations to reduce the carbon footprint of their business activities. We provide a carbon credit API to help create carbon-neutral products and services. #### How do I get started? You can sign up for free at [app.cnaught.com](http://app.cnaught.com). Once billing has been set up, you can place orders for carbon credits via the API or SDKs. We provide free credits you can use during the initial integration process. If you would like to keep test orders separate from production orders, you can set up a separate organization for testing your API integration. If you do this, reach out to `support@cnaught.com` and we'll provide free credits for the test organization. #### What is a carbon credit? A carbon credit (often called a carbon offset) is a credit for greenhouse emissions reduced or removed from the atmosphere by an emission reduction project, which can be used by governments, industry, or private individuals to compensate for the emissions they generate elsewhere. One carbon credit is equal to one metric ton of carbon dioxide, or in some markets, carbon dioxide equivalent gases (CO2e). #### How does this work? Customers purchase carbon credits from CNaught via their web dashboard or our API. Orders can be placed in quantities as low as a kilogram (the equivalent of powering a lightbulb for one day). CNaught matches that order in exactly the same amount with verified carbon removals and offsets (credits) that we have already purchased and retired. Once we allocate these credits to CNaught customers, we remove them from our inventory and do not allocated them to more than one customer. Customers are provided a certificate noting the quantity of the credit and the project that it was matched with. #### How do I know carbon is being removed? CNaught purchases and retires carbon removal and offset credits from projects that we have vetted and meet our requirements for permanence, additionality, and risk. These projects have been certified by registries, including Verra, Gold Standard, and American Carbon Registry, which require meeting measurement and verification standards. CNaught also uses data from third-party ratings providers, including BeZero, Sylvera, and Renoster to select the highest quality projects available to minimize the risk of project underperformance. #### Do you differentiate between removal and offsets? No. Carbon removal and offsets are both an integral part of the climate solution. CNaught has adopted the [Oxford Principles for Net Zero Aligned Offseting](https://www.smithschool.ox.ac.uk/sites/default/files/2022-01/Oxford-Offsetting-Principles-2020.pdf) which includes both carbon removal (active elimination of carbon dioxide through techniques including planting trees) and carbon offsets (prevention of additional carbon dioxide generation through techniques including forrest conservation). #### Can I choose the project for my credits? No. To simplify the purchase process and to encourage the adoption of a wide range of carbon credit solutions, CNaught matches customers with projects. #### How does CNaught’s pricing work? CNaught’s standard pricing is based on pay-as-you-go usage charges. There are no monthly recurring charges, fees to access the platform, or transaction charges. For full details, please see our pricing page. **Carbon credits** For carbon credits, we charge a flat rate per ton. **Carbon estimates** Usage of estimate endpoints is free for CNaught customers. #### How many api keys can I have? You are allowed a maximum of 2 API Keys at a time. When a new key is created, the old one will be rotated out but will remain active for 24 hours. Still have questions? [Contact us](mailto:support@cnaught.com) # Introduction Source: https://docs.cnaught.com/introduction CNaught makes it easy to help your customers compensate for their carbon footprint. Hero ## Getting started Start here on your journey to integrate Carbon Credits into your product. Follow our quickstart guide to start placing Carbon Credits orders in just a few minutes. Learn more about the different features of CNaught available via the API. ## Explore Additional resources to help with your integration. Use one of our SDKs to speed up integration See some examples of how to use the CNaught API # Quickstart Source: https://docs.cnaught.com/quickstart This short tutorial will teach you the basics of making requests to the CNaught APIs. ## Assumptions This tutorial assumes that you have a CNaught account. If not, [sign up for a free account](https://app.cnaught.com/api/auth/signup). ## Steps The first step is to generate an API key, which will allow you access to the CNaught APIs. Follow these steps: 1. [Log in](https://app.cnaught.com/api/auth/login) to CNaught. 2. Navigate to the [Developers](https://app.cnaught.com/developers) page in your new test organization. 3. Click the **Set up API** to create a production key (which will require you to set up a payment method). Creating an api key Save your API key somewhere safe; you will only be able to see it once. You can rotate your API key to a new one; the old one will remain valid for 24 hours. Submit a credits order. Replace the `` placeholder with the API key obtained in Step 1, and specify the amount of carbon credits (in kg of CO2e) you wish to purchase. ```bash theme={null} curl -X POST "https://api.cnaught.com/v1/orders" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"amount_kg": 10, \"metadata\": \"This is a test\"}' ``` You'll receive a response like this: ```bash theme={null} { "id": "Umx5c6F7pH7r", "created_on": "2021-09-15T05:14:38.13", "metadata": "This is a test", "amount": 10 } ``` The `id` (in this case `Umx5c6F7pH7r`) will allow you to retrieve your order. ## Next You should now have a basic idea of how to use the CNaught APIs. To learn more, read [the API documentation](/api-reference/introduction) for complete details on the API and its features. # Overview Source: https://docs.cnaught.com/sdks/overview Our SDKs make it easier and faster to integrate carbon credits into your application. Node.js SDK for CNaught API. Additional languages will be supported soon.