Warehouse

Organization warehouse

The organization warehouse is where an organization can deposit their credits and give apps access to the warehouse inventory where they can transfer them without asking for permission to do so each time.

But to move credits from the warehouse they first need to be put into the reservation queue, where they are reserved for the app that put them in the queue. This is so that the app can verify off platform data / actions before finalizing a transfer / retirement action. This can be very handy for marketplaces that do not wish to hold the credits themselves and instead use the warehouse system to reserve and transfer the credits when an actual buyer / retiree has been found.

list all credits in the warehouse inventory

Get warehouse inventory

This endpoint returns a paginated list of the organization's warehouse inventory.

get

/organizations/{id}/warehouse/inventory

Path parameters

idstringrequired

Query parameters

developmentstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/warehouse/inventory?development=text'

200

200

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "credits": [
    {
      "id": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
      "inventoryId": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
      "organizationId": "1b0e4f37-59ca-489a-8a23-ee3152812cb8",
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "amount": 7,
      "type": "exPost",
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      }
    }
  ]
}

This returns a list of all the credits in the organization's warehouse. Ids for the projects that issued those credits are also in place so using this endpoint in conjunction with the projects or project endpoints is handy.

Callable by any access token with permissions "organization_warehouse:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Second Tab

inventory reservations

Get warehouse reservations

This endpoint returns a paginated list of ALL of the organization's warehouse reservations. Both active, expired and finished.

get

/organizations/{id}/warehouse/inventory/reservations

Path parameters

limitnumberrequired

The amount of items to return

Example: 10

pagenumberrequired

The page to return

Example: 0

idstringrequired

The organization's id

Example: 1b0e4f37-59ca-489a-8a23-ee3152812cb8

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations'

200

200

{
  "pagination": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "reservations": [
    {
      "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
      "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "amount": 10,
      "createdAt": "2022-01-01T00:00:00Z",
      "retirementId": "1",
      "updatedAt": "2022-01-01T00:00:00Z",
      "tokenId": "123e4567-e89b-12d3-a456-426614174000",
      "tokenAddress": "0x123456789abcdef",
      "reservedToDate": "2022-01-01T00:00:00Z",
      "isComplete": true,
      "state": "pending",
      "type": "exPost",
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      },
      "reserver": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Reserver 1"
      }
    }
  ]
}

Returns a paginated list of all reservations, and the state of those reservations, made against the organization's warehouse.

Callable by any access token with permissions "organization_warehouse:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

reserve credits

Reserve credits from warehouse

This endpoint reserves credits from the organization warehouse. They are reserved for 10 minutes. In the meantime the reserver can be sure that the credits are available for them. This is especially useful for marketplaces that don't want the extra complexity of custody-ing user's credits.

post

/organizations/{id}/warehouse/inventory/reservations

Path parameters

idstringrequired

Query parameters

developmentstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Body

amountnumberrequired

The amount of credits to reserve

Example: 10

creditIdstringrequired

The id of the credit to reserve

Example: exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations?development=text' \
  --header 'Content-Type: application/json' \
  --data '{"amount":10,"creditId":"exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"}'

200

200

{
  "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "amount": 10
}

Reserving credits from a warehouse for later transfer. They are reserved for up to 10 minutes before they are moved back into the warehouse.

Callable by any access token with permissions "organization_warehouse:write".

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 10,
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"
}'

Typescript

specific reservation

Get warehouse reservation

This endpoint returns a specific warehouse reservation. It can be used to check if a reservation is still active or not.

get

/organizations/{id}/warehouse/inventory/reservations/{reservationId}

Path parameters

idstringrequired

The organization's id

Example: 1b0e4f37-59ca-489a-8a23-ee3152812cb8

reservationIdstringrequired

The reservation id

Example: 123e4567-e89b-12d3-a456-426614174000

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}'

200

200

{
  "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "amount": 10,
  "createdAt": "2022-01-01T00:00:00Z",
  "retirementId": "1",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x123456789abcdef",
  "reservedToDate": "2022-01-01T00:00:00Z",
  "isComplete": true,
  "state": "pending",
  "type": "exPost",
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "num": "713"
  },
  "reserver": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Reserver 1"
  }
}

Gets a specific reservation made.

Callable by any access token with permissions "organization_warehouse:read".

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

cancel specific reservation

Cancel warehouse reservation

This endpoint cancels a specific warehouse reservation. If the reservation is active the credits will be immediately made available in the organization's warehouse.

delete

/organizations/{id}/warehouse/inventory/reservations/{reservationId}

Path parameters

idstringrequired

reservationIdstringrequired

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}'

200

200

{
  "id": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "amount": 10,
  "createdAt": "2022-01-01T00:00:00Z",
  "retirementId": "1",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x123456789abcdef",
  "reservedToDate": "2022-01-01T00:00:00Z",
  "isComplete": true,
  "state": "pending",
  "type": "exPost",
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "num": "713"
  },
  "reserver": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Reserver 1"
  }
}

Cancels an outstanding reservation your app made.

Callable by any access token with permissions "organization_warehouse:write".

cURL

curl -X 'DELETE' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

finish outstanding reservation

Finish warehouse reservation

This endpoint finishes a specific warehouse reservation. This moves the credits out of the organization's warehouse and into the receiver's wallet, either as retired credits or the credits themselves.

post

/organizations/{id}/warehouse/inventory/reservations/{reservationId}//{action}

Path parameters

idstringrequired

The organization's id

Example: 1b0e4f37-59ca-489a-8a23-ee3152812cb8

reservationIdstringrequired

The reservation id

Example: 123e4567-e89b-12d3-a456-426614174000

actionstring · enumrequired

The action to take. One of transfer, transfer_retire

Example: transfer

Options: transfer, transfer_retire

Header parameters

x-icr-api-versionstring · default: 2023-06-16

API version

Body

receiverIdstring

The id of organization that will be receiving the credits

Example: 123e4567-e89b-12d3-a456-426614174000

receiverAddressstring

The wallet address that will be receiving the credits

Example: 0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1

transferCommentstring

Comment for the transfer

Example: This is a comment

priceInfoall of

Price information for the transfer. If the transfer / retirement is caused by a purchase, this is required.

retirementDataall of

Retirement data - only required if action is transfer_retire or retire

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}/{action}' \
  --header 'Content-Type: application/json' \
  --data '{"receiverId":"123e4567-e89b-12d3-a456-426614174000","receiverAddress":"0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1","transferComment":"This is a comment","priceInfo":{"price":5,"currency":"USD"},"retirementData":{"reason":"Retirement reason","beneficiaryName":"John Doe","comment":"This is a comment"}}'

200

200

{
  "success": true,
  "transactionId": "text",
  "state": "processed"
}

This can only be called withing 10minutes from the creation of the reservation.

Callable by any access token with permissions "organization_warehouse:write".

cURL

curl -X 'POST' \
  'https://api.carbonregistry.com/organizations/{ORG_ID}/warehouse/inventory/reservations/{RESERVATION_ID}/{ACTION}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16' \
  -H 'Content-Type: application/json' \
  -d '{
  "receiverId": "123e4567-e89b-12d3-a456-426614174000",
  "receiverAddress": "0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
  "transferComment": "This is a comment",
  "retirementData": {
    "reason": "Retirement reason",
    "beneficiaryName": "John Doe",
    "comment": "This is a comment"
  }
}'

Typescript