> For the complete documentation index, see [llms.txt](https://documentation.carbonregistry.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.carbonregistry.com/documentation/carbonregistry.com/api/apps/examples/interacting-with-the-organization-warehouse.md).

# Interacting with the Organization Warehouse

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".

<figure><img src="/files/FKa8g2BfpcdtdXLeYmSk" alt=""><figcaption></figcaption></figure>

### 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.&#x20;

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](/documentation/carbonregistry.com/api/endpoints/v0.5/organizations.md#organization-warehouse)). If you need test credits see the [friendbot](/documentation/carbonregistry.com/api/endpoints/v0.5/organizations.md#friendbot-test-credits).

```typescript
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](https://github.com/Mojoflower-garden/best-marketplace/blob/b6d497e12322b353003aeae7630f9d8804e5ff07/src/server/api/routers/icr.ts#L395).

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](/documentation/carbonregistry.com/api/endpoints/v0.5/organizations.md#organization-warehouse))

```typescript
 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](https://github.com/Mojoflower-garden/best-marketplace/blob/b6d497e12322b353003aeae7630f9d8804e5ff07/src/server/api/routers/icr.ts#L288).&#x20;

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

<figure><img src="/files/4klLAwVVMHKAVDs8Mao7" alt=""><figcaption></figcaption></figure>

Making the whole system fully transparent and secure.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.carbonregistry.com/documentation/carbonregistry.com/api/apps/examples/interacting-with-the-organization-warehouse.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.