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

Name	Type	Description
page	number	For pagination. Which page would you like to be returned? The default value is 1.
per_page	number	For pagination. How many project results you would like per page. The default value is 20.
trades_per_wallet	number	The number of trades shown per wallet. By default all trades are returned. The array is ordered by most recent trades at the top.
trade_type	string	Which types of trade to return. By default all types of trades are shown. Valid values are BUY and SELL.
wallet_min_quantity	number	Defines the minimum available balance (in grams) a wallet must contain to be returned. By default, this value is 0 so it shows all wallets. Passing a value of 1 will return all non-zero wallets.

Headers

Name	Type	Description
Authorization*	string	Bearer ${API_KEY}

200: OK

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.

Example

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

Schema

{
    projects: Array<{
        project_id: string
        vintages: Array<{
            vintage_id: string
            wallets: Array<{
                type: string
                quantity_grams: string
                trades: Array<{
                    execution_date: string
                    quantity_grams: string
                    price_cents: string
                    type: 'BUY' | 'SELL'
                }>
            }>
        }>
    }>
    pagination: {
        per_page: number
        total_pages: number
        total_items: number
        current_page: number
        previous_page: number
        next_page: number
    }
}

401: Unauthorized Your API key is unrecognized or inactive

Example

{
    "statusCode": 401,
    "message": "Unauthorized"
}

Schema

{
    statusCode: number
    message: string
}

403: User does not have `API User` role.

Example

{
    "error": "Forbidden",
    "message": "Permission denied according to assigned roles.",
    "statusCode": 403
}

Schema

{
    statusCode: number
    message: string
    error: string
}

500: Server error An unexpected error has occurred on the server.

Example

{
    "statusCode": 500,
    "message": "Internal server error"
}

Schema

{
    statusCode: number
    message: string
}