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

# Delete Sub-account

> This endpoint deletes sub-account by sub-account ID. The sub-account must have zero balance before it can be deleted.
The endpoint will return an error if the sub-account has a non-zero balance. The funds in the sub-account must be transferred to another account before deletion.
Once an account is deleted, it cannot be recovered, and a new sub-account must be created if needed.
The address associated with the sub-account will also be deleted upon successful deletion of the sub-account.


Deletes a zero-balance sub-account.


## OpenAPI

````yaml DELETE /ledger/subaccounts/{subAccountIdRef}
openapi: 3.0.3
info:
  version: 3.0.2
  title: Onboard External API Gateway
  description: >-
    **Introduction**

    API Gateway for Onboard


    This specification describes API endpoints that are available to the public
    internet via the API gateway. The different endpoints require different
    authentication schemes, see documentation for what applies to the operation
    you want to access.


    **Errors**

    Uses conventional HTTP response codes to indicate success or failure. In

    general:
     
    - `2xx` status codes indicate success. Codes in the

    - `4xx` range

    indicate a client error (e.g. required parameters, failed request etc.).

    - `5xx` status codes indicate a server error occurred.
  contact:
    name: Nestcoin TechOps
    email: techops@nestcoin.com
  license:
    name: UNLICENSED
servers:
  - url: https://external.dev.onboardpay.co
    description: Gateway for external API on staging environment.
security: []
tags:
  - name: users-onboardapi
    description: Endpoints available to for merchants liquidity automation
  - name: users-users
    description: User related endpoints
  - name: users-partners
    description: Partner related endpoints
  - name: users-admin
    description: Back office related endpoints
  - name: users-user2fa
    description: User 2fa related endpoints
  - name: users-usernotifications
    description: User notifications related endpoints
  - name: users-merchantnetwork
    description: Merchant network endpoints
  - name: users-userauth
    description: Authentication endpoints
  - name: users-userservice
    description: Service endpoints
  - name: users-webhook
    description: webhook endpoints
  - name: users-config
    description: Configuration Endpoints
paths:
  /ledger/subaccounts/{subAccountIdRef}:
    delete:
      tags:
        - ledger-sub-accounts
      summary: Delete sub-account by sub-account ID.
      description: >
        This endpoint deletes sub-account by sub-account ID. The sub-account
        must have zero balance before it can be deleted.

        The endpoint will return an error if the sub-account has a non-zero
        balance. The funds in the sub-account must be transferred to another
        account before deletion.

        Once an account is deleted, it cannot be recovered, and a new
        sub-account must be created if needed.

        The address associated with the sub-account will also be deleted upon
        successful deletion of the sub-account.
      operationId: deleteSubAccountById
      parameters:
        - $ref: '#/components/parameters/LedgerSvcsubAccountIdOrRef'
      responses:
        '200':
          description: Sub-account deleted Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusDto'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
        - HMACAuth: []
components:
  parameters:
    LedgerSvcsubAccountIdOrRef:
      in: path
      name: subAccountIdRef
      description: |
        The unique onboard sub-account ID or reference
      required: true
      schema:
        type: string
  schemas:
    StatusDto:
      description: Status data, check additional message field.
      type: object
      required:
        - success
      properties:
        success:
          description: >-
            Status can be successful or failed, a value of true indicates
            success.
          type: boolean
          example: true
        message:
          type: string
          description: additional message describing status.
        data:
          type: object
          additionalProperties: true
          description: Data associated with the status, this will not always be present
        error:
          $ref: '#/components/schemas/ErrorMessageDto'
      x-common-model: StatusDto
    ErrorMessageDto:
      description: >-
        Default error object for services. This gives consistent error object
        that all services may use.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
          example: UNKNOWN_ERROR
        message:
          type: string
          description: Descriptive error message
          example: Request could not be completed due to an error
        data:
          type: object
          description: Additional data for this error message.
          additionalProperties: true
          properties: {}
      x-common-model: ErrorMessageDto
  responses:
    LedgerSvcInvalidRequest:
      description: Request could not be validated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: BAD_REQUEST
            message: Request could not be validated.
    LedgerSvcUnauthorized:
      description: Client is not authorized to make request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: UNAUTHORIZED
            message: Either client security header is missing or it is not valid.
    LedgerSvcAccessDenied:
      description: Expected permission is not available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: ACCESS_DENIED
            message: Expected permission or scope is not present.
    LedgerSvcNotFound:
      description: Entity was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: NOT_FOUND
            message: Information could not be found
    LedgerSvcServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: INTERNAL_ERROR
            message: An internal server error occurred.
  securitySchemes:
    HMACAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: |-
        Requires authentication via API key and HMAC signature.
          * `x-api-key`: Your API key generated from your Onboard Business dashboard.
          * `x-timestamp`:  Unix epoch timestamp (seconds) used in signature, allowed skew is 30 seconds
          * `x-signature`: SHA256 HMAC HEX signature calculated over  `t={x-timestamp}&{requestBody}` using your API Secret.

````