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

# Subledgers

> Segregate balances into unique ledgers. 

Subledgers allow you to segregate balances by funds flow or for each of your customers. There are two types of subledgers you can create:

1. Subledgers associated with your enterprise
2. Subledgers associated with any verified `person` or `business`

To initiate a transfer associated with a subledger, include the `subledger_reference_id` in the transfer request and we'll automatically debit or credit the appropriate subledger balance.

Funds allocated to a subledger are reserved exclusively for that subledger's use. To fund a subledger associated with a verified `person` or `business`, initiate a <Tooltip tip="Moving funds to a subledger or from the subledger back to your enterprise balance.">book transfer</Tooltip> from your enterprise balance. You can also transfer to your enterprise account from a subledger in the same way — via a book transfer. 

<iframe width="560" height="315" src="https://www.loom.com/embed/832d0bbc438b4472851ae330d6715438" title="Orum | Monitor | Subledger Book Transfer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Creating Subledgers

A subledger must be associated with your enterprise or with a verified `person` or `business`.

**Endpoints**

* [POST /deliver/subledgers](/api-reference/deliver/subledgers/post-subledger): Create a subledger
* [GET /deliver/subledgers](/api-reference/deliver/subledgers/get-subledgers): Get all subledgers
* [GET /deliver/subledgers/id](/api-reference/deliver/subledgers/get-subledger): Get a subledger by id

<Tip>
  An unlimited number of persons, businesses, or enterprises can interact with a subledger.
</Tip>

**Example**

<CodeGroup>
  ```json Request theme={null}
  {
    "subledger_reference_id": "string",
    "customer_reference_id": "string",
  }
  ```

  ```json Response theme={null}
  {
    "subledger": {
      "id": "string",
      "subledger_reference_id": "string",
      "customer_reference_id": "string",
      "customer_resource_type": "business",
      "status": "created",
      "created_at": "2024-12-05T17:08:59.940Z",
      "updated_at": "2024-12-05T17:08:59.940Z",
    }
  }
  ```
</CodeGroup>

## Initiating Book Transfers

Book transfers happen instantly and enable you to fund a subledger or move funds from the subledger back to your enterprise balance.

**Endpoints**

* [POST /deliver/booktransfers](/api-reference/deliver/booktransfers/post-booktransfer): Create a book transfer
* [GET /deliver/booktransfers](/api-reference/deliver/booktransfers/get-booktransfers): Get all book transfers
* [GET /deliver/booktransfers/id](/api-reference/deliver/booktransfers/get-booktransfer): Get a book transfer by id

<Warning>
  Book transfers cannot be cancelled.
</Warning>

**Example**

<CodeGroup>
  ```json Enterprise to Subledger theme={null}
  {
    "booktransfer_reference_id": "string",
    "amount": 0,
    "destination": {
      "subledger_reference_id": "string",
     }
  }
  ```

  ```json Subledger to Enterprise theme={null}
  {
    "booktransfer_reference_id": "string",
    "amount": 0,
    "source": {
      "subledger_reference_id": "string",
     }
  }
  ```

  ```json Response theme={null}
  {
    "transfer": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "booktransfer_reference_id": "string",
      "amount": 0,
      "source": {
        "subledger_reference_id": "string",
      },
      "status": "created",
      "status_reasons": [
        {
          "source": {
            "reason_code": "insufficient_funds",
            "reason_code_message": "string"
          }
        }
      ],
      "created_at": "2025-01-23T15:35:38.030Z",
      "updated_at": "2025-01-23T15:35:38.030Z",
      "metadata": {},
    }
  }
  ```
</CodeGroup>

## Intiating Subledger Transfers

To initiate a transfer to a subledger, use the `subledger_reference id` in the transfers request body.

<Info>
  Depending on your use case, you may be required to populate the `subledger_reference id`  with every transfer.
</Info>

<Tip>
  If you’re initiating a dual leg transfer with a subledger, one of the parties in the transfer must be associated with the subledger or be a subledger associated with your enterprise.
</Tip>

If the subledger is associated with your enterprise, then the flow of funds works in the same way as it does when you make transfers from your enterprise balance. However, if the subledger is associated with a `person` or `business`, you'll need to be configured for dual leg flow of funds.

<Note>
  Unsure if you need dual leg configuration? Send a note to [<u>service@orum.io</u>](mailto:service@orum.io) and we’ll let you know based on your use case.
</Note>

**Example**

<CodeGroup>
  ```json Request theme={null}
  "transfer_reference_id": "<string>",
    "amount": 2,
    "currency": "USD",
    "speed": "asap",
    "source": {
      "customer_reference_id": "<string>",
      "account_reference_id": "<string>",
      "statement_display_name": "<string>"
    },
    "destination": {
      "customer_reference_id": "<string>",
      "account_reference_id": "<string>",
      "statement_display_name": "<string>"
    },
    "account_statement_descriptor": "<string>",
    "metadata": {},
    "subledger_reference_id": "AcmeCo"
  }'
  ```

  ```json Response theme={null}
  {
    "transfer": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "transfer_reference_id": "<string>",
      "amount": 2,
      "currency": "USD",
      "speed": "asap",
      "source": {
        "customer_reference_id": "<string>",
        "account_reference_id": "<string>",
        "statement_display_name": "<string>",
        "trace_number": "<string>",
        "return_trace_number": "<string>"
      },
      "destination": {
        "customer_reference_id": "<string>",
        "account_reference_id": "<string>",
        "statement_display_name": "<string>",
        "trace_number": "<string>",
        "return_trace_number": "<string>"
      },
      "status": "completed",
      "status_reasons": [
        {
          "source": {
            "reason_code": "insufficient_funds",
            "reason_code_message": "<string>",
            "network_reason_code": "<string>",
            "network_reason_code_message": "<string>",
            "network_reason_code_rail_type": "<string>"
          },
          "destination": {
            "reason_code": "insufficient_funds",
            "reason_code_message": "<string>",
            "network_reason_code": "<string>",
            "network_reason_code_message": "<string>",
            "network_reason_code_rail_type": "<string>"
          }
        }
      ],
      "account_statement_descriptor": "<string>",
      "estimated_funds_delivery_date": "2023-11-07T05:31:56Z",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "metadata": {},
   	"subledger_reference_id": "AcmeCo"
    }
  }
  ```
</CodeGroup>

## Checking Balances

There are three types of balances on the Orum platform, each of which includes a pending and available balance. All balances can be accessed via API or [Monitor](/mintlify/docs/guides/monitor/monitor-overview):

* **Enterprise Balance:** Your primary operational balance. This does not include the funds that have been allocated to subledgers.
* **Subledger Balance:** The balance associated with a subledger.
* **Total Balance:** The combined balance across your enterprise and all subledgers.

<iframe width="560" height="315" src="https://www.loom.com/embed/7f12a0cc64794d07ab7903479538c65f" title="Monitor | Subledger Reporting" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />