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

get

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

Path parameters

idstringRequired

Query parameters

developmentstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

get

HTTPcURLJavaScriptPython

GET /organizations/{id}/warehouse/inventory HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "credits": [
    {
      "id": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1",
      "inventoryId": "d449c665-3100-40c6-91ad-9d3f0a9fd343",
      "organizationId": "1b0e4f37-59ca-489a-8a23-ee3152812cb8",
      "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"
      },
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "amount": 7,
      "type": "exPost"
    }
  ],
  "organizationId": "123e4567-e89b-12d3-a456-426614174000"
}

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

get

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

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-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

get

HTTPcURLJavaScriptPython

GET /organizations/{id}/warehouse/inventory/reservations HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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",
      "state": "pending",
      "retirementId": "1",
      "updatedAt": "2022-01-01T00:00:00Z",
      "tokenId": "123e4567-e89b-12d3-a456-426614174000",
      "tokenAddress": "0x123456789abcdef",
      "type": "exPost",
      "reservedToDate": "2022-01-01T00:00:00Z",
      "isComplete": true,
      "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

post

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.

Path parameters

idstringRequired

Query parameters

developmentstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Body

amountnumberRequired

The amount of credits to reserve

Example: 10

creditIdstringRequired

The id of the credit to reserve

Example: exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1

Responses

200Success

application/json

post

HTTPcURLJavaScriptPython

POST /organizations/{id}/warehouse/inventory/reservations HTTP/1.1
Host: api.carbonregistry.com
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "amount": 10,
  "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"
}

200Success

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

get

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

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-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

get

HTTPcURLJavaScriptPython

GET /organizations/{id}/warehouse/inventory/reservations/{reservationId} HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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",
  "state": "pending",
  "retirementId": "1",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x123456789abcdef",
  "type": "exPost",
  "reservedToDate": "2022-01-01T00:00:00Z",
  "isComplete": true,
  "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

delete

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

Path parameters

idstringRequired

reservationIdstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

delete

HTTPcURLJavaScriptPython

DELETE /organizations/{id}/warehouse/inventory/reservations/{reservationId} HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "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",
  "state": "pending",
  "retirementId": "1",
  "updatedAt": "2022-01-01T00:00:00Z",
  "tokenId": "123e4567-e89b-12d3-a456-426614174000",
  "tokenAddress": "0x123456789abcdef",
  "type": "exPost",
  "reservedToDate": "2022-01-01T00:00:00Z",
  "isComplete": true,
  "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

post

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.

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: transferPossible values:

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Body

priceInfoall ofOptional

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

receiverIdstringOptional

The id of organization that will be receiving the credits

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

receiverAddressstringOptional

The wallet address that will be receiving the credits

Example: 0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1

transferCommentstringOptional

Comment for the transfer

Example: This is a comment

retirementDataall ofOptional

Retirement data - only required if action is transfer_retire or retire

Responses

200Success

application/json

post

HTTPcURLJavaScriptPython

POST /organizations/{id}/warehouse/inventory/reservations/{reservationId}/{action} HTTP/1.1
Host: api.carbonregistry.com
Content-Type: application/json
Accept: */*
Content-Length: 302

{
  "priceInfo": {
    "price": 5,
    "currency": "USD"
  },
  "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"
  }
}

200Success

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