Overview

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.

Sandbox Mode

CNaught includes a sandbox mode which allows you to try all the different API functions without incurring any costs or actually purchasing credits.

In the web dashboard, you can toggle sandbox mode via a switch in the sidebar.

For making API requests, you use the same endpoints for sandbox mode as production mode, but passing a sandbox API key. Both a sandbox and production API keys can be created from the Developers page. Before a production API key is created, you must complete the quickstart guide which will prompt you to enter payment information.

Authentication

Clients must authenticate by including their CNaught API Key in the Authorization header. If the API key is invalid, a 401 error code will be returned.

Use your sandbox API key to make sandbox requests and production API key for production requests.

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 call will associate the order with that subaccount, and doing so in the 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.

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

{
  "order": {
    "id": "Gre28Fc35bt3",
    "state": "fulfilled",
    "placed_on": "2018-05-05T23:23:22.29Z",
    "amount_kg": 356.25,
    "price_usd_cents": 2350
  }
}

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:<key> header in the request. The <key> 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 HTTP response payload.

Some common errors returned by the API, and their meanings are:

Some errors can be resolved simply by retrying the request. The following error codes are likely to be resolved with successive retries.

The individual API endpoints further document the possible error codes they can return.

Error object

The problem details information is represented as a JSON object with the following optional properties:

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:

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