> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retained earnings

> Create a retained earnings adjustment.

Use `year` for an annual retained earnings close. Alternatively, use `effective_date` to choose a specific date.

[Preview retained earnings](/api-reference/v1/preview-retained-earnings-closing-action) to see the adjustment without creating it.

## Cash and accrual reporting

Cash and accrual reports use different retained earnings adjustments.


## OpenAPI

````yaml post /v1/businesses/{businessId}/closing/retained-earnings
openapi: 3.0.1
info:
  title: API
  version: latest
servers: []
security:
  - BearerAuth: []
tags: []
externalDocs:
  url: /
paths:
  /v1/businesses/{businessId}/closing/retained-earnings:
    post:
      tags:
        - Retained earnings
      summary: Retained earnings
      description: Create a retained earnings adjustment.
      operationId: createRetainedEarningsClosingAction
      parameters:
        - name: businessId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRetainedEarningsClosingAction'
            example:
              year: 2024
              memo: Close 2024 earnings
      responses:
        '201':
          description: Retained earnings closing actions created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      closing_actions:
                        type: array
                        items:
                          $ref: >-
                            #/components/schemas/ApiRetainedEarningsClosingAction
                    required:
                      - closing_actions
                required:
                  - data
      security:
        - BearerAuth: []
components:
  schemas:
    CreateRetainedEarningsClosingAction:
      type: object
      description: Provide exactly one of year or effective_date.
      oneOf:
        - required:
            - year
        - required:
            - effective_date
      example:
        year: 2024
        memo: Close 2024 earnings
      properties:
        year:
          type: integer
          description: Year for the annual retained earnings close.
        effective_date:
          type: string
          format: date
          description: Specific date in YYYY-MM-DD format. Use instead of year.
        memo:
          type: string
          nullable: true
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
        reference_number:
          type: string
          nullable: true
        ledger_activity_start_timestamp:
          type: string
          format: date-time
          description: >-
            Optional start of ledger activity to include. Defaults to the
            business activation timestamp.
        retained_earnings_target_account:
          $ref: '#/components/schemas/AccountIdentifier'
          description: >-
            Account to receive net income. Defaults to the retained earnings
            account.
        override_default_tagging_strategy:
          type: array
          description: >-
            Tag set to close instead of the business default. Omitting this
            field uses the default strategy, which may create separate closing
            actions per entity.
          items:
            $ref: '#/components/schemas/TagKeyValue'
    ApiRetainedEarningsClosingAction:
      type: object
      properties:
        type:
          type: string
          example: Api_Retained_Earnings_Closing_Action
        id:
          type: string
          format: uuid
        business_id:
          type: string
          format: uuid
        ledger_id:
          type: string
          format: uuid
        closing_date:
          type: string
          format: date
        memo:
          type: string
          nullable: true
        metadata:
          $ref: '#/components/schemas/PlatformDefinedJson'
        reference_number:
          type: string
          nullable: true
        ledger_activity_start_timestamp:
          type: string
          format: date-time
          nullable: true
        retained_earnings_target_account:
          $ref: '#/components/schemas/AccountIdentifier'
        transaction_tags:
          type: array
          items:
            $ref: '#/components/schemas/ApiTag'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        archived_at:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - business_id
        - ledger_id
        - closing_date
        - created_at
    PlatformDefinedJson:
      type: object
      description: Arbitrary JSON data defined by the caller, with a 1KB size constraint.
      additionalProperties: true
      example:
        custom_field: value
        any valid json: below 1kb
        nested:
          meaning of life: 42
          array: []
    AccountIdentifier:
      oneOf:
        - $ref: '#/components/schemas/AccountId'
          description: ID of the account.
          title: Account ID
        - $ref: '#/components/schemas/AccountStableName'
          description: Stable name associated with the account.
          title: Account Stable Name
    TagKeyValue:
      type: object
      description: >-
        A TagKeyValue holds key=value data related to a tag. This is used when
        creating or updating taggable entities (transactions, invoices, etc.).
      properties:
        key:
          type: string
          description: The tag dimension key (e.g., "department", "project", "location").
          example: department
        dimension_display_name:
          type: string
          nullable: true
          description: >-
            If the TagDimension doesn't exist, providing this value specifies
            the display name upon database insertion. Otherwise, it is left as
            null on the TagDimension.
          example: Department
        value:
          type: string
          description: The tag value (e.g., "sales", "marketing", "engineering").
          example: sales
        value_display_name:
          type: string
          nullable: true
          description: >-
            If the TagValueDefinition doesn't exist, providing this value
            specifies the display name upon database insertion. Otherwise, it is
            left as null on the TagValueDefinition.
          example: Sales Department
      required:
        - key
        - value
    ApiTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID for the tag.
        key:
          type: string
          description: Key for the tag.
          example: ExampleTagKey
        dimension_display_name:
          type: string
          nullable: true
          description: Display name for the tag dimension.
        value:
          type: string
          description: Value for the tag.
          example: ExampleTagValue
        value_display_name:
          type: string
          nullable: true
          description: Display name for the tag value definition.
        dimension_id:
          type: string
          format: uuid
          description: ID of the tag dimension this tag belongs to.
        definition_id:
          type: string
          format: uuid
          description: ID of the tag value definition.
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: When the tag was archived.
      required:
        - id
        - key
        - value
        - dimension_id
        - definition_id
    AccountId:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - AccountId
          description: Resource type. Value will be `AccountId`.
          example: AccountId
        id:
          type: string
          format: uuid
          description: ID of the account.
    AccountStableName:
      type: object
      required:
        - type
        - stable_name
      properties:
        type:
          type: string
          enum:
            - StableName
          description: Resource type. Value will be `StableName`.
          example: StableName
        stable_name:
          type: string
          example: CURRENT_ASSETS
          description: Stable name of the account.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````