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.

GEThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory

Path parameters

id*string

Query parameters

Header parameters

Response

200

Body

application/json

credits*array of ApiCreditDto (object)

The credits of the organization

organizationId*string

The ID of the organization that owns the warehouse

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

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory?development=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

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

GEThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations

Path parameters

limit*number

The amount of items to return

Example: 10

page*number

The page to return

Example: 0

id*string

The organization's id

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

Header parameters

Response

200

Body

application/json

pagination*ApiPaginationDto (object)

reservations*array of ApiReservationDto (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

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.

POSThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations

Path parameters

id*string

Query parameters

Header parameters

Body

application/json

amount*number

The amount of credits to reserve

Example: 10

creditId*string

The id of the credit to reserve

Example: "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"

Response

200

Body

application/json

id*string

The unique identifier of the reservation, used to finish / cancel it

Example: "d449c665-3100-40c6-91ad-9d3f0a9fd343"

creditId*string

The unique identifier of the credit

Example: "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"

serialization*string

The serialization of the reservation

Example: "ICR-ISL-354-78040-14-R-0-2021"

amount*number

The amount reserved

Example: 10

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations?development=text', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount": 10,
      "creditId": "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"
    }),
});
const data = await response.json();

Response

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.

GEThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}

Path parameters

id*string

The organization's id

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

reservationId*string

The reservation id

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

Header parameters

Response

200

Body

application/json

id*string

The unique identifier of the reservation, used to finish / cancel it

Example: "d449c665-3100-40c6-91ad-9d3f0a9fd343"

creditId*string

The unique identifier of the credit

Example: "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"

serialization*string

The serialization of the reservation

Example: "ICR-ISL-354-78040-14-R-0-2021"

amount*number

The amount reserved

Example: 10

createdAt*string (date-time)

The creation date of the reservation

Example: "2022-01-01T00:00:00Z"

state*enum

The state of the reservation - if undefined the reservation is still waiting to be actived / finished.

Example: "pending"

pendingcancelledcompletedfailednullnull

retirementIdstring

The retirement ID of the reservation

Example: "1"

updatedAt*string (date-time)

The update date of the reservation

Example: "2022-01-01T00:00:00Z"

tokenId*string

The token ID of the reservation

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

tokenAddress*string

The token address of the reservation

Example: "0x123456789abcdef"

type*enum

The type of the reservation

Example: "exPost"

exPostexAnte

reservedToDate*string (date-time)

The reserved to date of the reservation

Example: "2022-01-01T00:00:00Z"

isComplete*boolean

The completion status of the reservation

Example: true

project*all of

The project of the reservation

reserver*all of

The reserver of the reservation

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

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

DELETEhttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}

Path parameters

id*string

reservationId*string

Header parameters

Response

200

Body

application/json

id*string

The unique identifier of the reservation, used to finish / cancel it

Example: "d449c665-3100-40c6-91ad-9d3f0a9fd343"

creditId*string

The unique identifier of the credit

Example: "exPost-2-0x51298f2f1142ecb129a2db5e6afd24f34f2e53f1"

serialization*string

The serialization of the reservation

Example: "ICR-ISL-354-78040-14-R-0-2021"

amount*number

The amount reserved

Example: 10

createdAt*string (date-time)

The creation date of the reservation

Example: "2022-01-01T00:00:00Z"

state*enum

The state of the reservation - if undefined the reservation is still waiting to be actived / finished.

Example: "pending"

pendingcancelledcompletedfailednullnull

retirementIdstring

The retirement ID of the reservation

Example: "1"

updatedAt*string (date-time)

The update date of the reservation

Example: "2022-01-01T00:00:00Z"

tokenId*string

The token ID of the reservation

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

tokenAddress*string

The token address of the reservation

Example: "0x123456789abcdef"

type*enum

The type of the reservation

Example: "exPost"

exPostexAnte

reservedToDate*string (date-time)

The reserved to date of the reservation

Example: "2022-01-01T00:00:00Z"

isComplete*boolean

The completion status of the reservation

Example: true

project*all of

The project of the reservation

reserver*all of

The reserver of the reservation

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

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

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.

POSThttps://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}/{action}

Path parameters

id*string

The organization's id

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

reservationId*string

The reservation id

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

action*enum

The action to take. One of transfer, transfer_retire

Example: "transfer"

transfertransfer_retire

Header parameters

Body

application/json

priceInfoall of

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

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"

retirementDataall of

Retirement data - only required if action is transfer_retire or retire

Response

200

Body

application/json

success*boolean

transactionId*string

state*enum

The state of the transaction - usually this will be pending_queue in this response and you'll need to query / poll the reservation or transaction endpoint to know whether the transaction failed to process or not.

processedfailedpending_queuepending_onchainpending_requestrejectedpending_reservedcancelled

Request

JavaScriptCurlPython

const response = await fetch('https://api.carbonregistry.com/organizations/{id}/warehouse/inventory/reservations/{reservationId}/{action}', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "success": false,
  "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