Skip to main content

Creating a retirement

Access rights

Following access rights need to be enabled for your API user in the MyPuro Portal to use these endpoints:

  • Read Transaction to list and get transactions
  • Create Retirement for creating retirements

See Access management for more details about enabling access to MyPuro resources.

Create Retirement​

To create the retirement, take the cerficiate id and account number from previous section and use the POST /mypuro/transactions/retirement endpoint to create the retirement.

Create retirement
curl -X 'POST' "/transactions/retirement" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $BASIC" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

Use the following schema for the request body to create the retirement. In the UAT environment you can use random test data for price information. Use your own email address beneficiaryContactPersonEmail to receive the notification email about the retirement:

sourceAccountNumber
required
string <uuid>

The account from where the CORCs will be retired.

offtakeAgreementId
string

Enter the reference number for the offtake agreement if one exists and has been reported to Puro.earth. This will help us help ensure that your transaction is properly tracked and aligned with the agreement details.

required
Array of objects (PostCertificateBundle)

Certificate bundles and amounts to retire.

unitPrice
required
string <decimal> ^\d+\.\d{1,2}$

Price per unit.

currency
required
string
beneficiaryName
required
string <= 100 characters

The beneficiary entity name. Examples of beneficiaries might include, but are not limited to: companies, public entities, private or public organizations. The name of the beneficiary will be visible in the public Puro Registry.

beneficiaryLocation
required
string <= 100 characters

Location where the beneficiary is registered.

beneficiaryType
required
string
Enum: "END_CONSUMER" "SUPPLIER"

Choose SUPPLIER, if you are a supplier retiring CORCs issued to you on your own behalf. Otherwise, select END_CONSUMER.

beneficiaryContactPersonEmail
required
string <email> \b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]...

Beneficiary contact person email will receive a summary of the information you have submitted here.

countryOfConsumption
required
string = 2 characters

ISO 3166-1 alpha-2 country code.

usageType
required
string
Enum: "BUNDLED_WITH_PRODUCT_OR_SERVICE" "DISCLOSURE" "GENERIC_COMPENSATION" "OTHER" "SPECIFIC_ACTIVITY_LIKE_FLIGHTS" "SUPPORT"

Usage type refers to the activity the CORCs compensate for. If the list of provided enums doesn't contain usage type relevant to you, choose OTHER.

consumptionPeriodStartDate
required
string <date>

Start date of the consumption period.

consumptionPeriodEndDate
required
string <date>

End date of the consumption period.

retirementPurpose
required
string <= 1000 characters

Enter the retirement purpose e.g. “Retired on behalf of X to offset emissions resulting from activities in 2023”. This information will be visible in our public registry.

additionalNotes
string or null <= 1000 characters
Default: null

Additional notes about the transaction.

{
  • "sourceAccountNumber": "a14e8d63-9a77-4cf9-8350-bc2fd4b47b7c",
  • "offtakeAgreementId": "cl16h6x6h0026brxdt3q7870l",
  • "bundles": [
    ],
  • "unitPrice": "10.12",
  • "currency": "EUR",
  • "beneficiaryName": "string",
  • "beneficiaryLocation": "string",
  • "beneficiaryType": "END_CONSUMER",
  • "beneficiaryContactPersonEmail": "john.doe@puro.earth",
  • "countryOfConsumption": "FI",
  • "usageType": "GENERIC_COMPENSATION",
  • "consumptionPeriodStartDate": "2024-01-01",
  • "consumptionPeriodEndDate": "2024-01-31",
  • "retirementPurpose": "string",
  • "additionalNotes": "Assets issued for the production period of 2022-01-01 till 2022-12-31."
}

List Transactions​

To view the retirement transaction, use the GET /mypuro/transactions endpoint.

List transactions
curl -X 'GET' "/transactions" \
  -H "Accept: application/json" \
  -H "Authorization: Basic $BASIC"