Skip to main content

Transactions

Transactions in the Registry API represent events that change the state of certificates in the registry, such as issuances, transfers, and retirements.

Data schema​

A transaction object contains the following information:

  • transactionId: The unique UUID identifier for the transaction.
  • volume: The total count of certificates involved in the transaction.
  • completedOn: The date and time when the transaction was completed.
  • accountHolderName: The name of the account holder involved in the transaction. The account holder name is available for issuances, retirements, and withdrawals, but not exposed for transfers currently.
  • type: The type of transaction (Issuance, Transfer, InternalTransfer, Retirement, Withdrawal).
  • bundles: An array of certificate bundles involved in the transaction.
  • labels: An array of labels associated with the transaction and it's CORCs. Labels indicate additional accreditation the CORCs may have been associated with. Label details can be fetched from the labels endpoint.
  • issuanceDetails: Additional details for issuance transactions.
  • retirementDetails: Additional details for retirement transactions.

Transaction Types and Details​

The type field indicates the transaction type:

  • Issuance: Creation of new certificates in the registry
  • Transfer: Transfer of certificates between different owners
  • InternalTransfer: Transfer between accounts of the same owner (restricted for regular API users)
  • Retirement: The certificates are used for compensation, and taken from circulation.
  • Withdrawal: Corrections to issuances, which removes certificates from circulation

Certificate Bundles​

The bundles array contains certificate bundles involved in the transaction, with fields like certificates, volume, methodologyCode, productionFacilityCode, vintage, production dates, and creditType.

Special Transaction Details​

  • Issuance transactions include an issuanceDetails object with issuance date, issuance id, and audit body.
  • Retirement transactions include a retirementDetails object with beneficiary information, consumption details, and retirement purpose.

Listing Transactions​

To retrieve a list of transactions, you can use the /registry/transactions endpoint with a GET request. This endpoint supports filtering and pagination parameters:

  • transactionType: Filter by transaction type (Issuance, Transfer, InternalTransfer, Retirement, Withdrawal)
  • productionFacilityCode: Filter by production facility code
  • limit: The maximum number of items to return (default: 100, max: 100)
  • offset: The number of items to skip (default: 0)

Example Requests​

Simple example​

List transactions
curl -X 'GET' "/registry/transactions?limit=100&offset=0" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $BASIC"

Filtering example​

List transactions
curl -X 'GET' "/registry/transactions?transactionType=Issuance&limit=100&offset=0" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $BASIC"

Response Structure​

The response includes a pagination object with information about the total number of items, the current offset, and the limit applied. The data array contains the list of transaction objects.

{
  "pagination": {
    "total": 50,
    "offset": 0,
    "limit": 10
  },
  "data": [
    {
      "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "volume": 100,
      "completedOn": "2024-01-01T12:00:00Z",
      "accountHolderName": "Carbon Removal Inc.",
      "type": "Issuance",
      "bundles": [
        {
          "certificates": "PURO_PR_CORC100+_FI_148003_2024_0052850a-1263-4d3f-af6f-a91288df04e3_1-100",
          "volume": 100,
          "methodologyCode": "C03000000",
          "productionFacilityCode": "OC4C00",
          "vintage": 2022,
          "productionStartDate": "2022-01-01T00:00:00.000Z",
          "productionEndDate": "2022-12-12T00:00:00.000Z",
          "creditType": "CORC_100",
          "issuanceId": "0052850a-1263-4d3f-af6f-a91288df04e3",
          "issuanceDate": "2024-01-01T00:00:00.000Z"
        }
      ],
      "labels": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "CCP-Approved"
        }
      ],
      "issuanceDetails": {
        "issuanceDate": "2024-01-01T00:00:00.000Z",
        "issuanceId": "0052850a-1263-4d3f-af6f-a91288df04e3",
        "auditBody": "Auditor Ltd."
      }
    }
    // Additional transactions...
  ]
}

Getting a Specific Transaction​

To retrieve information about a specific transaction, you can use the /registry/transactions/{transactionId} endpoint with a GET request, where {transactionId} is the unique identifier of the transaction.

Example Request​

Get transactions by id
curl -X 'GET' "/registry/transactions/{transactionId}" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $BASIC"

Response Structure​

The response contains a single transaction object with detailed information:

{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "volume": 100,
  "completedOn": "2024-01-01T12:00:00Z",
  "accountHolderName": "Carbon Removal Inc.",
  "type": "Issuance",
  "bundles": [
    {
      "certificates": "PURO_PR_CORC100+_FI_148003_2024_0052850a-1263-4d3f-af6f-a91288df04e3_1-100",
      "volume": 100,
      "methodologyCode": "C03000000",
      "productionFacilityCode": "OC4C00",
      "vintage": 2022,
      "productionStartDate": "2022-01-01T00:00:00.000Z",
      "productionEndDate": "2022-12-12T00:00:00.000Z",
      "creditType": "CORC_100",
      "issuanceId": "0052850a-1263-4d3f-af6f-a91288df04e3",
      "issuanceDate": "2024-01-01T00:00:00.000Z"
    }
  ],
  "labels": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "CCP-Approved"
    }
  ],
  "issuanceDetails": {
    "issuanceDate": "2024-01-01T00:00:00.000Z",
    "issuanceId": "0052850a-1263-4d3f-af6f-a91288df04e3",
    "auditBody": "Auditor Ltd."
  }
}

Next Steps​

Now that you understand how to retrieve information about transactions, you can proceed to learn about Certificates in the Registry API.