Updates to the Registry

Upcoming API Changes

The registry modification introduces some breaking changes to the API. This document summarizes the main differences. Please check our release notes regularly for the latest updates on each release.

Puro.earth is transitioning its underlying registry service. This change is motivated by our commitment to provide our Connect API users with a state-of-the-art infrastructure that supports the dynamic needs of the carbon removal industry. By adopting this new technology, we aim to offer our users improved service quality, including better transaction speed, and enhanced security features.

This strategic move aligns with our ongoing efforts to support environmental sustainability through technological excellence. We believe that this transition will significantly benefit our users, empowering them to participate more effectively in the global effort to combat climate change.

We understand that changes of this nature come with questions and considerations, and we are here to support our Connect API users through this transition, ensuring a seamless and positive experience.

The API now reports trades, retirements, and offramps to the registry differently, which makes them incompatible with previous versions. Production facilities and traders' assets also have more information than before.

info

All Sales Channel Services API endpoints (/saleschannel-services/*) have been renamed to include v1 in the endpoint (/saleschannel-services/v1/*)

Trader's Inventory

Bundle start and end numbers

Bundle's certificate's numerical range will not be globally unique anymore after the update, but instead they will be unique per issuance. As an example, two bundles can share the same numerical range 1-10, but they are made distinct by adding the issuance's Id as a prefix to the range, for example <ISSUANCE_ID_1>_1-10 and <ISSUANCE_ID_2>_1-10. To accommodate this change, the issuance Id is added as a prefix to the start and end numbers of the bundle. This ensures that the API user can work with a distinct set of certificates, even if the start and end numbers are repeated in different issuances in the future. For existing bundles the old numerical ranges are kept, but the range is still prefixed with the issuance Id.

Currently

{
  "start": "12345",
  "end": "12350"
}

Upcoming version

{
  "start": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_12345",
  "end": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_12350"
}

Certificate Id

Certificate Ids of a bundle is exposed through the certificates attribute, for example:

{
  "volume": 100,
  ...
  "certificates": "PURO_PR_CORC100+_FI_577166_2020_055a3fbe-eabc-4535-b9cf-1028e7d18f89_1-100"
}

The certificate Id encodes different properties of the certificates separated with an underscore (_).

Field	Description	Example
Standard	Abbreviation of the Carbon Removal Program.	PURO
Registry Id	Identifier of the Registry.	PR
Credit Type	Credit type of the certificate. This is a human readable form of the credit type, the creditTypeId is the machine readable form of the same data.	CORC100+
Country Code	Production Facility country code. 2 letter alphabetical country code as per ISO 3166.	FI
Production Facility Code	6 character unique code for the Production Facility.	577166
Vintage	Production vintage of the certificate.	2020
Issuance Id	Issuance transaction's Id of the certificates.	055a3fbe-eabc-4535-b9cf-1028e7d18f89
Serial Number	Generated serial number for the issued certificates. The number can overlap with other issued certificates, but guaranteed to be unique within one issuance. Previously the start and end numbers of a batch.	1-100

Serial Number

The Serial Number indicates the range of certificates in a bundle. For example, a bundle with 100 certificates will have a Serial Number from 1 to 100. Previously, the Serial Number was composed of a GSRN and a sequential number with leading zeros, such as 643002406555908611 + 000000000001. This format will be preserved for the existing certificates and bundles. However, for the new certificates issued after the Registry update, the Serial Number will start from 1 and increase by 1 for each certificate.

Discovering Assets

GET /saleschannel-services/traders/{traderId}/inventory

[
  {
    "volume": 100,
    "productionFacilityId": "cl5qo433z000047xdadi2amx0",
    "supplierId": "cl8x3mgx40001xd7o37z3j7yl",
    "methodologyCode": "C03000000",
    "issuingDate": "2020-01-01T00:00:00.000Z",
    "expirationDate": null,
    "creditTypeId": "CORC_100",
    "standard": "PURO",
    "countryCode": "FI",
    "productionStartDate": "2020-01-01T00:00:00.000Z",
    "productionEndDate": "2020-12-31T00:00:00.000Z",
    "vintage": 2020,
    "start": "643002406555908611000000000001",
    "end": "643002406555908611000000000100"
  }
]

GET /saleschannel-services/v1/traders/{traderId}/inventory

[
  {
    "volume": 100,
    "productionFacilityId": "cl5qo433z000047xdadi2amx0",
    "supplierId": "cl8x3mgx40001xd7o37z3j7yl",
    "methodologyCode": "C03000000",
    "issuingDate": "2020-01-01T00:00:00.000Z",
    "expirationDate": null,
    "creditTypeId": "CORC_100",
    "standard": "PURO",
    "countryCode": "FI",
    "productionStartDate": "2020-01-01T00:00:00.000Z",
    "productionEndDate": "2020-12-31T00:00:00.000Z",
    "vintage": 2020,
    "start": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000001",
    "end": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000100",
    "certificates": "PURO_PR_CORC100+_FI_577166_2020_055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000001-643002406555908611000000000100"
  }
]

Transactions

The Registry will have multiple bundles with the same start and end numbers in the future. To avoid confusion and ensure the right certificates are transacted, the issuanceId is necessary.

warning

The upcoming changes will affect how users select certificates within a bundle. Unlike the current system, where users can choose any certificate(s) for trading, retiring, or offramping, the new system will only allow users to select certificates from the start of a bundle.

Let's say that we have the following bundle available in the inventory:

GET /saleschannel-services/traders/{traderId}/inventory

[
  {
    "volume": 100,
    ...
    "start": "643002406555908611000000000001",
    "end": "643002406555908611000000000100"
  }
]

The user could select any certificate within and including the start and end numbers, for example select five certificates from the middle.

{
  "start": "643002406555908611000000000033",
  "end": "643002406555908611000000000037"
}

In the future this is not possible. All selections must include the start value of the bundle. Selection of five certificates would then be as such (including the issuanceId):

{
  "start": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000001",
  "end": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000005"
}

Trading Assets

POST /saleschannel-services/traders/{traderId}/inventory/trade

{
  "buyerId": "clc0c5of30123rsph3yui9cwo",
  "assets": [
    {
      "start": "643002406555908611000000000001",
      "end": "643002406555908611000000000100",
      "unitPrice": 149.95
    }
  ],
  "currency": "EUR"
}

POST /saleschannel-services/v1/traders/{traderId}/inventory/trade

{
  "buyerId": "clc0c5of30123rsph3yui9cwo",
  "assets": [
    {
      "start": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000001",
      "end": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000100",
      "unitPrice": 149.95
    }
  ],
  "currency": "EUR"
}

Retiring Assets

POST /saleschannel-services/traders/{traderId}/inventory/retire

{
  "beneficiaryName": "ACME Corp Oy",
  "beneficiaryLocation": "Helsinki",
  "beneficiaryType": "END_CONSUMER",
  "consumptionCountryCode": "FI",
  "consumptionPeriod": {
    "start": "2020-01-01T00:00:00.000Z",
    "end": "2020-12-31T00:00:00.000Z"
  },
  "retirementPurpose": "To compensate for flight emissions from business trips in 2022.",
  "usageType": "GENERIC_COMPENSATION",
  "assets": [
    {
      "unitPrice": 149.95,
      "start": "643002406555908611000000000001",
      "end": "643002406555908611000000000100"
    }
  ],
  "currency": "EUR"
}

POST /saleschannel-services/v1/traders/{traderId}/inventory/retire

{
  "beneficiaryName": "ACME Corp Oy",
  "beneficiaryLocation": "Helsinki",
  "beneficiaryType": "END_CONSUMER",
  "consumptionCountryCode": "FI",
  "consumptionPeriod": {
    "start": "2020-01-01T00:00:00.000Z",
    "end": "2020-12-31T00:00:00.000Z"
  },
  "retirementPurpose": "To compensate for flight emissions from business trips in 2022.",
  "usageType": "GENERIC_COMPENSATION",
  "assets": [
    {
      "unitPrice": 149.95,
      "start": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000001",
      "end": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000100"
    }
  ],
  "currency": "EUR"
}

Offramping Assets

POST /saleschannel-services/traders/{traderId}/inventory/offramp

{
  "assets": [
    {
      "start": "643002406555908611000000000001",
      "end": "643002406555908611000000000100"
    }
  ]
}

POST /saleschannel-services/v1/traders/{traderId}/inventory/offramp

{
  "assets": [
    {
      "start": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000001",
      "end": "055a3fbe-eabc-4535-b9cf-1028e7d18f89_643002406555908611000000000100"
    }
  ]
}

Production Facilities

GET /saleschannel-services/v1/production-facilities/{productionFacilityId}

{
  "id": "cl1bv7mkq00342qxd0fdt8ko7",
  "gsrn": "643002406801000015",
  "code": "577166",
  "name": "Biochar facility",
  "countryCode": "FI",
  "methodologyCodes": ["string"]
}

Code

Each Production Facility has a unique code of six alphanumeric characters. The certificate Id includes this code as well.

GSRN

The gsrn field is no longer in use. Production Facilities that already have a gsrn will retain it, but new ones will not have one. The gsrn field will be null for those facilities.