Inventory

See credits you own but haven't retired yet

Overview

Get information about the carbon credits you own that haven't been retired yet. You can also see the purchase history of each project/vintage.

Example cURL Request

curl --request GET 'https://${BASE_URL}/api/inventory?page=1&per_page=20' \
--header 'Authorization: Bearer ${API_KEY}'

Wallets

Your inventory is held in "wallets". Each wallet has a type and is associated to a specific project and vintage. The only wallet type currently supported is CAAS, but more wallet types may be added in the future.

Fractionalised Retirements

The wallet data contains the quantity of carbon credits you own, in grams, that haven't yet been retired. This can occur when using the Request Retirement and passing a value for quantity_grams that isn't in whole tonnes i.e. the value doesn't divide evenly by 1,000,000. This is known as a "fractionalised" retirement because you are requesting the retirement of a fraction of a tonne.

Purchases are always made in whole tonnes. As an example, if you retire 750,000 (three quarters of a tonne) the system will purchase a whole tonne (1,000,000 grams) but only queue 750,000 grams for retirement. This is due to a limitation on the underlying registries where retirements can only occur in whole tonnes. In this example, you still own the remaining 250,000 grams but they will not be queued for retirement.

You can use this end point to view those 250,000 grams.

When To Use This Endpoint

If you always retire in whole tonnes you do not need to use this endpoint as purchases are made on the fly at the same time as retirement so your inventory will always be zero.

If you retire in fractions you may wish to check your inventory before purchasing more credits from the market so you use up your inventory first.

Trade History

The trade history supplied with each wallet is useful to see what prices you have paid for these credits in the past. For example, in a scenario where you sell credits to your own customers, you may take the last price paid for a specific project/vintage in order to determine what price to charge your own customers.

This is in contrast to when you might use the market data which will have the current price. If we did not supply the trade history you wouldn't know what you paid for the credits and therefore you couldn't be sure what to charge your own customers.

Endpoint Specification

Get inventory for tenant

GET /api/inventory

Get information about the carbon credits you own that haven't been retired yet. You can also see the purchase history for each project/vintage.

Query Parameters

Headers

price_cents is per tonne. 1 tonne is 1,000,000 grams. Purchases are always made in whole tonnes.

Prices are in USD cents.

quantity_grams is the amount of credits, in grams, that you own that has not been retired.

If a trade type is BUY the quantity_grams and price_cents is how much you purchased and at what price.

If a trade type is SELL the quantity_grams and price_cents is how much you sold and at what price. Selling isn't currently possible for CaaS customers so you would only see BUY trade types. This may be a feature we implement in the future.

{
    "projects": [
        {
            "project_id": "003ksr13jstw0zcq8g",
            "vintages": [
                {
                    "vintage_id": "0049zfm3m2vbnpxacv",
                    "wallets": [
                        {
                            "type": "CAAS",
                            "quantity_grams": "999970",
                            "trades": [
                                {
                                    "execution_date": "2023-08-16T11:16:00.643Z",
                                    "quantity_grams": "1000000",
                                    "price_cents": "4500",
                                    "type": "BUY"
                                },
                                {
                                    "execution_date": "2023-08-16T09:10:12.062Z",
                                    "quantity_grams": "10000000",
                                    "price_cents": "2450",
                                    "type": "SELL"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "pagination": {
        "per_page": 20,
        "total_pages": 1,
        "total_items": 1,
        "current_page": 1,
        "previous_page": null,
        "next_page": null
    }
}

Last updated