Skip to main content

Retiring Assets

info

You need a traderId of the Trader which assets are to be retired. See Discover Assets page to fetch the traderId.

Registering a Retirement is an asynchronous process yielding a retirement task. Status of the retirement is observed from this task.

Processing time of a Retirement

Due to Puro's transaction approval process the settlement of a retirement can be deferred and take some time. The approval is requested from the seller if the seller is a Puro.earth Platform Agreement signed Trader. Until the transaction is either approved or rejected the Task stays in PENDING state.

If the seller trader is not linked to a Puro.earth Platform Agreement signed Trader, or if the transaction auto-approval is turned on by the seller, then the Retirement is completed almost immediately.

It is recommended that the Sales Channel throttle retry calls to the Retirement status endpoint.

Register a Retirement​

Retirements are registered using POST /saleschannel-services/v1/traders/{traderId}/inventory/retire endpoint. Monetary information, seller ID, beneficiary information, retirement purpose as well as start and end IDs of bundles to be retired will be given as the request payload.

Due to the underlying registry changes, the asset start has to always be the first certificate of a bundle.

When retiring assets for the trader currently owning the assets, then specifying the monetary value can be omitted. In such case, set the monetary value to null for all bundles. You will still be required to supply a currency.

Hide the beneficiary from the Registry​

The Beneficiary can request a reasonable time delay, no longer than 12 months, in publishing Beneficiary and Retirement purpose.

See section 5.1.2 in Puro.earth General Rules V4.0

Hidden beneficiary and retirement purpose

You can hide the beneficiary from the retirement in https://registry.puro.earth/ up to 12 months from the retirement date. The beneficiaryHiddenUntil attribute controls this behaviour. The beneficiary name and retirement purpose are hidden until the given date-time. By default the beneficiary name and retirement purpose are public.

Detailed payload for registering a retirement​

beneficiaryName
required
string

The name of the beneficiary of the retirement.

beneficiaryLocation
required
string non-empty

The location of the beneficiary of the retirement.

beneficiaryType
string
Default: "END_CONSUMER"
Enum: "END_CONSUMER" "SUPPLIER"

The type of the beneficiary. END_CONSUMER is an end consumer, SUPPLIER is a CO2 removal method supplier.

beneficiaryHiddenUntil
string or null <date-time>
Default: null

The date until which the beneficiary is hidden.

consumptionCountryCode
required
string[A-Z]{2}

The code of the country in which the to-be retired certificates are consumed.

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

Type of the activity associated with the retirement.

required
object

The period during which the to-be retired assets where used.

retirementPurpose
required
string non-empty

The purpose for which the certificates are retired.

required
Array of objects non-empty

All assets which are involved in this retirement. For all bundles, either all bundles have a monetary unit-price, or none of them do.

currency
required
string or null
Enum: "EUR" "USD"

The currency of the monetary value of this trade.

{
  • "beneficiaryName": "ACME Corp Oy",
  • "beneficiaryLocation": "Helsinki",
  • "beneficiaryType": "END_CONSUMER",
  • "beneficiaryHiddenUntil": "2022-01-01T00:00:00.000Z",
  • "consumptionCountryCode": "FI",
  • "usageType": "GENERIC_COMPENSATION",
  • "consumptionPeriod": {
    },
  • "retirementPurpose": "To compensate for flight emissions from business trips in 2022.",
  • "assets": [
    ],
  • "currency": "EUR"
}
Register a retirement
curl -X 'POST' "/saleschannel-services/v1/traders/{traderId}/inventory/retire" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "beneficiaryName": "ACME Corp Oy", \
    "beneficiaryLocation": "Helsinki", \
    "beneficiaryType": "END_CONSUMER", \
    "beneficiaryHiddenUntil": "2022-01-01T00:00:00.000Z", \
    "consumptionCountryCode": "FI", \
    "consumptionPeriod": { \
      "start": "2023-01-01T00:00:00.000Z", \
      "end": "2023-12-31T00:00:00.000Z" \
    }, \
    "retirementPurpose": "To compensate for flight emissions from business trips in 2023.", \
    "assets": [ \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_1", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_100", \
        "unitPrice": 0.01 \
      } \
    ], \
    "currency": "EUR" \
  }'

Check the Retire task status​

Via the Get status of a retirement task​

A successful response from registering a retirement contains the id of the created retirement task which can be used to query for the retirement status.

Get status of a retirement task
curl -X 'GET' "/saleschannel-services/v1/traders/{traderId}/inventory/retire/{taskId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Resending the Register a retirement task request​

As trade registering endpoint is idempotent with the help of the Idempotency-Key. You can request the status of the trade by resending the exact same payload with the same Idempotency-Key used initially for registering the retirement.

Response​

Both of these endpoints return the retirement task status

taskId
required
string

The ID of this task

status
required
string
Enum: "STARTED" "SUCCESS" "FAILED" "PENDING" "REJECTED"

The new status of the transaction.

idempotencyKey
string <^[\w-]{1,64}$> ^[\w-]{1,64}$

Idempotency keys are client-generated strings which ensure that requests can be safely retried.

message
string

Human-readable message field describing the state of the task.

object

Details on the created retirement, if the retirement task completed successfully.

{
  • "taskId": "cl3y5zbkb0062wuxd52u85agi",
  • "status": "PENDING",
  • "idempotencyKey": "cl3y5zbka0036wuxdtoxdl36a",
  • "message": "Task is waiting to be picked up.",
  • "responsePayload": {
    }
}
Asset bundles

The asset start and end ranges have to be specified separately for each bundle in the inventory, even if the separate bundles would form a continuous range of certificates. For example if the seller has two bundles and the retirement contains assets from both, then the retirement must contain two separate asset ranges.

For example:

Register a retirement
curl -X 'POST' "/saleschannel-services/v1/traders/{traderId}/inventory/retire" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ \
    "beneficiaryName": "ACME Corp Oy", \
    "beneficiaryLocation": "Helsinki", \
    "beneficiaryType": "END_CONSUMER", \
    "beneficiaryHiddenUntil": "2022-01-01T00:00:00.000Z", \
    "consumptionCountryCode": "FI", \
    "consumptionPeriod": { \
      "start": "2023-01-01T00:00:00.000Z", \
      "end": "2023-12-31T00:00:00.000Z" \
    }, \
    "retirementPurpose": "To compensate for flight emissions from business trips in 2023.", \
    "assets": [ \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_1", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_20", \
        "unitPrice": 0.01 \
      }, \
      { \
        "start": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_50", \
        "end": "6e0edefa8-cbde-4c19-896a-edafb7a8e030_100", \
        "unitPrice": 0.01 \
      } \
    ], \
    "currency": "EUR" \
  }'