# Retirements

Initiate retirements of monthly certificates within an account.

Endpoint: POST /api/ledger/retire
Version: 1.0.0
Security: JWT

## Query parameters:

  - `onBehalfOfAccountId` (string)
    Account id for which the request is being made: defaults to the primary account id of the requester unless specified

## Request fields (application/json):

  - `requests` (array)
    List of requests

  - `requests.correlationId` (string)
    An opaque value that will be returned in the responses and error messages to correlate the response or error with the corresponding request
    Example: "1"

  - `requests.certificateSerialNumberRange` (string, required)
    Certificate serial number ranges as returned by the holdings call, may not be combined with other ranges, even if contiguous
    Example: "NAR-REC-1234-CA-06-2024-555555-1 to 66"

  - `requests.quantity` (number, required)
    The quantity of the transaction
    Example: "55"

  - `requests.subaccountId` (string, required)
    The subaccount identifier
    Example: "77"

  - `requests.isPublic` (boolean)
    Whether the retirement will be public

  - `requests.retirementTypeCode` (string, required)
    The retirement type code: see documentation for allowed values
    Example: "GRN"

  - `requests.retirementReasonCode` (string)
    The retirement reason code: see documentation for allowed values
    Example: "22"

  - `requests.countrySubdivisionCode` (string)
    The retirement state, ISO-3166-2 for US states
    Example: "CA"

  - `requests.retirementYear` (integer)
    The retirement/compliance year
    Example: 2024

  - `requests.notificationName` (string)
    The name of the notification recipient (e.g, beneficial owner)
    Example: "John Doe"

  - `requests.notificationEmail` (string)
    The e-mail address(es) of the notification recipient (e.g, beneficial owner)
    Example: "jdoe@acmecorp.com"

  - `requests.additionalDetails` (string)
    Additional details text, may be required in some cases: see documentation for more information
    Example: "Voluntary Retirement for Acme Corp."

  - `requests.retirementCertificateType` (string)
    'SINGLE'. Only used for retirementTypeCodes GRN and  BBO
    Example: "SINGLE"

## Response 200 fields (application/json):

  - `submissionId` (string, required)
    Submission identifier for issue investigation
    Example: "1"

  - `responses` (array)
    List of responses

  - `responses.correlationId` (string)
    An opaque value that will be returned in the responses and error messages to correlate the response or error with the corresponding request
    Example: "1"

  - `responses.certificateSerialNumberRange` (string, required)
    Certificate serial number ranges as returned by the holdings call, may not be combined with other ranges, even if contiguous
    Example: "NAR-REC-1234-CA-06-2024-555555-1 to 66"

  - `responses.quantity` (number, required)
    The quantity of the transaction
    Example: "55"

  - `responses.subaccountId` (string, required)
    The subaccount identifier
    Example: "77"

  - `responses.isPublic` (boolean)
    Whether the retirement will be public

  - `responses.retirementTypeCode` (string, required)
    The retirement type code: see documentation for allowed values
    Example: "GRN"

  - `responses.retirementReasonCode` (string)
    The retirement reason code: see documentation for allowed values
    Example: "22"

  - `responses.countrySubdivisionCode` (string)
    The retirement state, ISO-3166-2 for US states
    Example: "CA"

  - `responses.retirementYear` (integer)
    The retirement/compliance year
    Example: 2024

  - `responses.notificationName` (string)
    The name of the notification recipient (e.g, beneficial owner)
    Example: "John Doe"

  - `responses.notificationEmail` (string)
    The e-mail address(es) of the notification recipient (e.g, beneficial owner)
    Example: "jdoe@acmecorp.com"

  - `responses.additionalDetails` (string)
    Additional details text, may be required in some cases: see documentation for more information
    Example: "Voluntary Green-e retirement"

  - `responses.retirementCertificateType` (string)
    'SINGLE'. Only used for retirementTypeCodes GRN and  BBO
    Example: "SINGLE"

  - `responses.transferId` (string, required)
    The transfer identifier
    Example: "5678"

  - `responses.remainingCertificateSerialNumberRange` (string)
    The certificate serial number range remaining in the account after the operation
    Example: "NAR-REC-1234-CA-06-2024-555555-56 to 66"

## Response 400 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 401 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 403 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 413 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 429 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code

## Response 500 fields (application/json):

  - `submissionId` (string)
    Submission identifier for issue investigation

  - `errors` (array)
    List of errors

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `errors.field` (string)

  - `errors.code` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error code