Interacting with the organization warehouse

The organization warehouse is a place where a credit owner can put credits they wish to sell and give apps / marketplace access to reserver and transfer those credits.

The organization warehouse is especially useful for marketplaces that do not wish to be custodians of the carbon credits themselves. The warehouse also makes it simple for credit owners to manage which credits are for sale without giving apps / marketplaces access to their main inventory.

Permissions

As an app, to request permission for access into an organization's warehouse you'll have to set the "warehouse" permission to "Read and write".

Reserving credits

Now, assuming your app is a front for a marketplace there will likely come the situation that a buyer wants to buy ICR credits. Before you do the transfer / retirement of the credits the buyer is buying you'll probably need to do some due diligence / make sure the buyer has funds to finish the payment. While your service is waiting for those checks it would be bad user experience if the credits are bought / transferred while the buyer is waiting for those checks. Therefore we implemented the reservation system.

When the buyer implies his intention to buy a certain amount of credits, let's say by putting those credits in a "basket", you should call the reservation endpoint on the organization that owns the credits. (docs). If you need test credits see the friendbot.

await axios.post(
          `${env.ICR_API_URL}/organizations/${input.organizationId}/warehouse/inventory/reservations`,
          {
            creditId: input.creditId,
            organizationId: input.organizationId,
            amount: input.amount,
          },
          {
            headers: {
              Authorization: `Bearer ${accessToken.token}`,
              "x-icr-api-version": "2023-06-16",
            },
          },
        )

For reference see full code here.

These credits are now reserved for your app. They are reserved for 10 minutes before being put back into the warehouse if your app has not cancelled / finished the reservation in the meantime.

Finishing reservation

Then when you are ready to finish the reservation, i.e. the buyer's funds have been checked and moved, then you can just call the finish endpoint. (docs)

 await axios.post(
          `${env.ICR_API_URL}/organizations/${input.organizationId}/warehouse/inventory/reservations/${input.reservationId}/${input.action}`,
          {
            receiverId: input.receiverId,
            retirementData: input.retirementData,
          },
          {
            headers: {
              Authorization: `Bearer ${accessToken.token}`,
              "x-icr-api-version": "2023-06-16",
            },
          },
        );

For reference see full code here.

This reserve / cancel / finish reservation system is visible for the organizations' admins on their warehouse dashboard.

Making the whole system fully transparent and secure.