A Ledger is a data structure that implements double entry accounting. Ledgers have a perspective; they track the money movements for a single business entity.

The core primitive in a ledger is the Ledger Account. A ledger account tracks movements of money. Each account encodes the entity's relationship with other entities such as their bank, customers, and vendors.

A Ledger Account has a balance. A Ledger Line records a single change to an account's balance. Thus, the sum of the lines in an account is the account's balance. An account's balance can be zero, positive or negative.

Ledger Accounts can be split into two layers, State and Change.

The State layer tracks the entity's net worth. The total of all the account balances in the State layer adds up to the current net worth of the entity.

The Change layer tracks updates to net worth. When the total net worth changes, accounts in the Change layer track the reason for that update.

In double entry accounting, updates to the ledger must be balanced. These updates are called Ledger Entries: accounting movements that net to 0. Every ledger entry must

• contain ledger lines that add up to no net change to the State layer
• contain ledger lines that add up to an equal change in both the State and Change layers

For example, when selling a widget, the Ledger Entry would contain lines that offset the increase in a State account Bank with the increase in a Change account Widget Sales.

There can also be entries that only exist in the State layer. For example, when taking out a loan, the loaned cash in the State account Bank is offset against another State account called Loans account.

To encode more complex movements of money, Ledger Entries can contain more than two lines.

Within the State and Change layer, Ledger accounts have specific account types.

These account types enable more granular tracking than just State and Change. They are common terms used by accountants and map directly to common financial reports like Balance Sheets and Income Statements.

In FRAGMENT, ledger accounts can exist in a tree hierarchy called a Chart of Accounts:

• A parent account's balance contains the sum of all of its children's balances
• You can post ledger entries at any layer in the tree. FRAGMENT will update the balances of accounts higher up in the hierarchy
• You can query for balances on any ledger account and choose whether or not to include its children

As your product evolves, the dimensionality of your data increases. With a flat list of accounts, you might add more database tables, fields, and foreign key relationships to model this complexity. Instead, with a tree data structure, you bake it into the ledger and extend your account hierarchy.

Ledgers use a logical clock, so you can post ledger entries at any point in time, including the future. You can also query balances at any point in time. Posting a ledger entry in the past will update all balances from that point in time into the future.

Links represent an external system that moves money. Links can be any store of value be it banks, brokerages, card processors, crypto wallets, rewards points, or loan issuers.

Links contain External Accounts, which represent a single account at the external system. External Accounts have a transaction store, a log of all transactions in the external account.

Linked Ledger Accounts are ledger accounts that are tied to an external account.

Any ledger line that posts to these accounts must match 1:1 with a transaction in the external account.

Transactions in the external account that aren't yet tied to a ledger entry are unreconciled transactions.

Native Links implement a full two-way sync between FRAGMENT and the external system. Transactions are automatically imported into the transaction store.

With Native Links, the reconciliation workflow is:

• External accounts and transactions are imported automatically by FRAGMENT
• Create Ledger Accounts that are linked to External Accounts
• Track unreconciled transactions
• Reconcile imported transactions into a ledger

Custom Links provide APIs for you to integrate with any external system and import transactions into FRAGMENT. These external systems are typically 3rd party payment processors (banks, card issuers, etc.) that you work with. In certain use cases, it's also valuable to model a 1st party system you maintain as a Custom Link to ensure it and FRAGMENT stay in sync.

With a Custom Link, the reconciliation workflow is:

• Import accounts and transactions from the external system via FRAGMENT's API
• Create Ledger Accounts that are linked to Custom Accounts
• Track unreconciled transactions
• Reconcile imported transactions into a ledger

For supported integrations, you can make payments directly from the ledger. FRAGMENT creates transfers at the external system and updates the ledger as they're processed. Reconciliation is automatic.

Orders are finite-state machines that orchestrate payments. An Order's state tracks the state of its payment. An Order can be setup to post a ledger entry on each state transition. An Order can be used to handle transit accounting, payment failures and returns.

Ledger accounts in FRAGMENT support the single or multi currency mode. When you create an account in the multi currency mode, you can post ledger entries with lines in different currencies to the same account.

FRAGMENT natively supports all ISO-4217 currencies and a list of common crypto currencies. You can also add your own custom currencies to build brokerages, track rewards points or make sure pre-tax and post-tax money don't mingle.

When an account is in currency mode multi or has children with balances in multiple currencies, the account will have multiple balances. You can think of the multiple balances on a ledger account as an equation:

100 GBP - 100 USD + 100 EUR

To solve this equation:

1. Pick a currency as the target currency and look up its exchange rates
2. For each balance in a non-target currency multiply it by the exchange rate to the target currency
3. Add up the resulting balances

As you post multi-currency entries into the ledger, all the balance equations update. As exchange rates fluctuate, the solutions to balance equations update.

You can create State accounts to track assets and liabilities in the currency they're denominated in. You might have several bank accounts in different currencies and have stock, crypto and private investment portfolios. Similarly, for liabilities, you might have an invoice or loan you have to pay in a specific currency, or customer portfolios on your platform across a range of assets. You can track all of these stores of value in the same ledger.

State account balance equations track the net worth of an entity, like single currency balances. Solving the balance equation gives you the current net worth of the entity in the target currency.

Multi-currency ledger entries follow double-entry rules per currency.

To create valid ledger entries, you'll need to use Change accounts. Let's call these accounts Exposure accounts. Their purpose is to allow you to convert between currencies by tracking forex exposure.

Solving the balance equation for an Exposure Account calculates the forex gain or loss in the target currency, if you were to liquidate at the exchange rates used.

FRAGMENT uses OAuth2's client credentials flow to authenticate API clients. The flow is:

1. Get a fresh access token from the token endpoint: https://auth.fragment.dev/oauth2/token using your API client's credentials
2. Use that token in an Authorization header with the value Bearer {{access_token}} when calling the GraphQL API.

The access token expires in 1 hour. We recommend retrieving a new token for each set of calls you're making. You can generate and use multiple tokens at the same time.

You can create and view API Clients from the FRAGMENT dashboard. All API clients have full access to your workspace.

The call to get an access token follows the OAuth 2 spec, so you can use an OAuth2 library that supports the client credentials grant to retrieve the token, or make an HTTP request.

Your payload should be in the x-www-form-urlencoded format:

grant_type=client_credentials&scope=https://api.fragment.dev/*&client_id={{client_id}}

The response will be a JSON Object containing your access token.

{
    "access_token": "<access token>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Here are some code snippets that show how to hit the https://auth.fragment.dev/oauth2/token endpoint.

curl --location --request POST 'https://auth.fragment.dev/oauth2/token' \
  --header 'Authorization: Basic Mmg0dDBjdjdxdjVjOXIwcWdzMW8zZXJrdWs6c3VwZXJTZWNyZXRDbGllbnRTZWNyZXQ=' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=https://api.fragment.dev/*' \
  --data-urlencode 'client_id=2h4t0cv7qv5c9r0qgs1o3erkuk'

import http.client
import b64encode from base64

client_id = '2h4t0cv7qv5c9r0qgs1o3erkuk'
client_secret = 'superSecretClientSecret'

payload = f'grant_type=client_credentials&scope=https%3A%2F%2Fapi.fragment.dev%2F*&client_id={client_id}'
client_credentials = f'{client_id}:{client_secret}'
encoded_creds = (
  b64encode(client_credentials.encode('ascii'))
  .decode('ascii')
)

conn = http.client.HTTPSConnection("auth.fragment.dev")
headers = {
  'Authorization': f'Basic {encoded_creds}',
  'Content-Type': 'application/x-www-form-urlencoded',
}
conn.request("POST", "/oauth2/token", payload, headers)

data = conn.getresponse().read()
print(data.decode("utf-8"))

import axios from "axios";

const btoa = (str) => Buffer.from(str).toString("base64");

const clientId = "2h4t0cv7qv5c9r0qgs1o3erkuk";
const secret = "superSecretClientSecret";

const getToken = async () => {
  const auth = btoa(`${clientId}:${secret}`);
  const data = new URLSearchParams();
  data.append("grant_type", "client_credentials");
  data.append("scope", "https://api.fragment.dev/*");
  data.append("client_id", clientId);

  const response = await axios.request({
    method: "POST",
    url: 'https://auth.fragment.dev/oauth2/token',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${auth}`,
      Accept: "*/*",
    },
    data,
  });

  if (!response.data.access_token) {
    throw new Error(
      "didn't get an access token from auth endpoint"
    );
  }
  return response.data.access_token;
};

To create a ledger account linked to a Native Link, use the account ID from the external system API as the externalId. FRAGMENT will set the currency automatically.

Once linked you can:

• Make payments that automatically reconcile and post ledger entries as they process
• Track unreconciled transactions imported by FRAGMENT
• Post ledger entries that reconcile imported transactions

To create a ledger account linked to a Custom Link, use the externalId you passed into syncCustomAccounts, which ideally is also the account ID at the external system. The Linked Ledger Account will inherit its currency from the Custom Account.

Once linked you can:

• Track unreconciled transactions imported via syncCustomTxs
• Post ledger entries that reconcile imported transactions

You can query which transactions still need to be reconciled to a Linked Ledger Account using the unreconciledTxs query:

query GetUnreconciledTxs ($ledgerAccountId: ID!) {
  ledgerAccount(id: $ledgerAccountId) {
    id
    unreconciledTxs {
      nodes {
        id
        description
        amount
        externalId
        externalAccountId
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

{
  "id": "<linked ledger account id>"
}

unreconciledTxs returns a TxsConnection object which is a paginated list of transactions

To reconcile transactions from external payment systems, use the reconcileTx mutation. This mutation pulls in a transaction from the transaction store to the ledger and adds a balanced entry with a line matching the transaction amount to a linked account.

mutation ReconcileTx ($entry: LedgerEntryInput!) {
  reconcileTx(entry: $entry) {
    __typename
    ... on ReconcileTxResult {
      entry {
        id
        date
        description
      }
      lines {
        id
        date
        amount
        type
      }
    }
    ... on Error {
      code
      message
    }
  }
}

This mutation has one parameter, entry which has the same LedgerEntryInput type as other mutations. It uses the tx field to specify the transaction to reconcile:

{
  "entry": {
    "lines": [
      {
        "account": {
          "id": "linked-ledger-account-id"
        },
        "tx": {
          "id": "tx-id-from-unreconciled-txs-query-above"
        }
      },
      {
        "account": {
          "id": "offset-ledger-account-id"
        }
      }
    ]
  }
}

The result will be a ledger entry posted at the transaction posted timestamp that contains:

• A line in the linked ledger account that where the amount and description matches the external transaction
• A line in the other specified ledger account where the description matches the external transaction, but the amount is negative

You can also do more complex reconciliation where the linked ledger line is balanced by multiple other lines and override descriptions:

{
  "entry": {
    "lines": [
      {
        "account": {
          "id": "linked-ledger-account-id"
        },
        "tx": {
          "id": "tx-id-from-unreconciled-txs-query-above"
        },
        "amount": "10000"
      },
      {
        "account": {
          "id": "seller-2-accounts-payable"
        },
        "description": "Item #2234 sold",
        "amount": "8500"
      },
      {
        "account": {
          "id": "shipper-accounts-payable"
        },
        "description": "Item #2234 shipping fees",
        "amount": "1000"
      },
      {
        "account": {
          "id": "platform-fees-income-account"
        },
        "description": "Item #2234 platform fees",
        "amount": "500"
      }
    ]
  }
}

You can specify the transaction to reconcile using the ID from the external system API instead of the FRAGMENT ID:

{
  "entry": {
    "lines": [
      {
        "account": {
          "id": "linked-ledger-account-id"
        },
        "tx": {
          "externalId": "increase-api-tx-id"
        }
      },
      {
        "account": {
          "id": "offset-ledger-account-id"
        }
      }
    ]
  }
}

reconcileTx doesn't require an idempotency key. Internally, FRAGMENT creates a composite IK from:

• the ID of the transaction, and
• ID of the ledger being reconciled

• You can only reconcile a single transaction per call
• If you are reconciling a transfer between two external accounts which are both linked to the same ledger, use a transit account in between to split the transfer into two reconcileTx calls.

• externalId is used as the idempotency key, within the scope of its Custom Link
• Calling syncCustomAccounts multiple times with the same externalId will not create a new account
• Most attributes on the account can't be updated. Attempting to do so will return a BadRequestError. The exception is name, which can be updated since it's only used for display purposes

• externalId cannot contain ,, " , ', #, /, (, or )
• You can sync up to 100 Custom Accounts in one API call

• externalId is used as the idempotency key, within the scope of its account
• Calling syncCustomTxs multiple times with the same externalId will not create a new transaction
• Most attributes on the transaction can't be updated. Attempting to do so will return a BadRequestError. The exception is description, which can be updated since it's only used for display purposes

• externalId cannot contain ,, " , ', #, /, (, or )
• You can sync up to 100 Custom Transactions in one API call

You can quickly get started making bank transfers using the makeBankTransfer API. This mutation is syntactic sugar over the createOrder mutation below, so we recommend that advanced users use Orders. Idempotency keys are shared between the two mutations.

mutation MakeBankTransfer ($bankTransfer: MakeBankTransferInput!, $ik: SafeString!) {
  makeBankTransfer(bankTransfer: $bankTransfer, ik: $ik) {
    __typename
    ... on MakeBankTransferResult {
      bankTransfer {
        id
        description
        status
      }
      isIkReplay
    }
    ... on Error {
      code
      message
    }
  }
}

It has one parameter, bankTransfer, which is a MakeBankTransferInput. See below for examples.

This mutation will:

1. Create a bank transfer at the external system
2. Track when the transfer completes
3. Import the transaction associated with the transfer
4. Post a ledger entry that reconciles the transaction

Since this mutation talks to an external system, the result could be either a settled or submitted bankTransfer, depending on whether the bank could synchronously process the transfer.

If a bankTransfer is waiting on a transfer to settle at the bank, FRAGMENT will wait until the transaction posts at the bank account to post the ledger entry.

To initiate an ACH credit or wire from your bank account you need to include:

• The ledger account linked to that bank account
• A negative amount to indicate that money is leaving the account
• A payment with a destination and a type of either ach or wire
• An offsetting entry

{
  "ik": "some-ik-not-previously-used-in-create-order",
  "bankTransfer": {
    "amount": "-100000",
    "description": "Initiate customer withdrawal",
    "payment": {
      "type": "wire",
      "source": {
        "accountNumber": <bank-account-number>,
        "routingNumber": <bank-routing-number>
      }
    },
    "linkedLedgerAccount": {
      "id": <your-bank-account-id-in-fragment>
    },
    "offset": {
      "lines": [
        {
          "amount": "100000",
          "account": {
            "id": <leger-account-id-in-fragment>
          }
        }
      ]
    }
  }
}

To initiate an ACH debit, you need to include:

• The ledger account linked to that bank account
• A positive amount to indicate that money should be entering the account
• A payment with a source and a type of ach
• An offsetting entry

{
  "ik": "some-ik-not-previously-used-in-create-order",
  "bankTransfer": {
    "amount": "100000",
    "description": "Customer payment",
    "payment": {
      "type": "ach",
      "source": {
        "accountNumber": <customer-account-number>,
        "routingNumber": <customer-routing-number>
      }
    },
    "linkedLedgerAccount": {
      "id": <your-cash-account-id-in-fragment>
    },
    "offset": {
      "lines": [
        {
          "amount": "-100000",
          "account": {
            "id": <your-income-account-id-in-fragment>
          }
        }
      ]
    }
  }
}

You can send money from one bank account to another within the same link by specifying the destination bank account and a negative amount.

{
  "ik": "some-ik-not-previously-used-in-create-order",
  "bankTransfer": {
    "amount": "-1000",
    "payment": {
      "type": "internal",
      "destination": {
        "bankAccount": {
          "id": "fragment bank account id"
        }
      },
    },
    "offset": {
      "lines": [
        {
          "amount": "1000",
          "account": {
            "id": <ledger-account-id>
          }
        }
      ]
    },
    "linkedLedgerAccount": {
      "id": <your-cash-account-id-in-fragment>,
    },
    "description": "Pay out $10 to platform accounts",
}

You can also pull money into a linked bank account from another at the same bank by specifying a source and positive amount:

{
  "ik": "some-ik-not-previously-used-in-create-order",
  "bankTransfer": {
    "amount": "1000",
    "payment": {
      "type": "internal",
      "destination": {
        "bankAccount": {
          "id": "fragment bank account id"
        }
      },
    },
    "offset": {
      "lines": [
        {
          "amount": "1000",
          "account": {
            "id": <ledger-account-id>
          }
        }
      ]
    },
    "linkedLedgerAccount": {
      "id": <your-cash-account-id-in-fragment>,
    },
    "description": "Pay in $10 to platform accounts",
}

You cannot currently do an internal transfer between two linked ledger accounts when both ledger accounts are linked to the same ledger.

If the linked ledger accounts are in different ledgers then the transaction in the non-initiating ledger account will appear as an unreconciled transaction. You can retrieve the otherTxId in the response to createOrder and pass it to reconcileTx.

BankTransfer Orders have the following states:

• Submitted: If the payment is created successfully, the Order begins in a submitted state.
• Failed: If the payment isn't created successfully, the Order begins in a failed state. This is a terminal state.
• Settled: Once the payment clears, the Order transitions to a Settled state. During the payment reversal window (usually 60 days), this is a non-terminal state. Once the payment can no longer reverse, this becomes a terminal state.
• Returned: If the payment returns after settlement, the Order transitions to this state. For ACH, a return can happen up to 60 days after the original transaction. This is a terminal state.

You can use the createOrder mutation to create an Order.

mutation CreateOrder ($order: CreateOrderInput!, $ik: SafeString!) {
  createOrder(order: $order, ik: $ik) {
    __typename
    ... on CreateOrderResult {
    order {
      stateMachine {
        bankTransfer {
          status
          transitionLog {
            transition
            effect {
              entry {
                id
                description
                lines {
                  id
                  date
                  amount
                }
              }
            }
          }
        }
      }
    }
      isIkReplay
    }
    ... on Error {
      code
      message
    }
  }
}

It has one parameter, order of type CreateOrderInput, which defines the state machine of the bank transfer being made. The BankTransferStateMachineTransitionsInput type allows you to define the side-effects of each state transition. Currently, the only side-effect supported is posting a ledger entry.

Here's an example input that provides automatic accounting for payment reversals:

{
  "ik": <some-ik>,
  "order": {
    "stateMachine": {
      "bankTransfer": {
        "config": {
          "transitions": {
            "submitted_to_settled": {
              "entry": {
                "description": "hello",
                "lines": [
                  {
                    "amount": "10000",
                    "account": {
                      "id": <linked-ledger-account-id>
                    },
                    "payment": {
                      "type": "ach",
                      "destination": {
                        "accountNumber": "987654321",
                        "routingNumber": "021000021"
                      }
                    }
                  },
                  {
                    "amount": "10000",
                    "account": {
                      "id": <receivables-loan-123-due>
                    }
                  }
                ]
              }
            },
            "settled_to_returned": {
              "entry": {
                "description": "olleh (reversed hello)",
                "lines": [
                  {
                    "amount": "10000",
                    "account": {
                      "id": <linked-ledger-account-id>
                    }
                  },
                  {
                    "amount": "10000",
                    "account": {
                      "id": <collections-loan-123-pending>
                    }
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}

You're required to define the submitted_to_settled transition when creating an order, the others are optional.

To filter by the type on an Entity, send a filter argument in your query with an equalTo operator:

query GetLedgerAccounts($ledgerId: ID!, $filter: LedgerAccountsFilterSet!) {
  ledger(ledger: { id: $ledgerId}) {
    ledgerAccounts(filter: $filter) {
      nodes {
        id
        name
        type
      }
    }
  }
}

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "type": {
      "equalTo": "asset"
    }
  }
}

To search for multiple types, you can use the in operator:

{
  "filter": {
    "type": {
      "in": ["asset", "liability"]
    }
  }
}

DateFilters work similarly to TypeFilters and allow you to query for a specific date:

query GetAccountLinesOnDate($ledgerAccountId: ID!, $filter: LedgerLinesFilterSet) {
  ledgerAccount(ledgerAccount: {id: $ledgerAccountId}) {
    lines(filter: $filter) {
      nodes {
        id
        posted
        date
        amount
        description
        ledgerEntryId
      }
    }
  }
}

{
  "ledgerAccountId": <ledger-account-id>,
  "filter": {
    "date": {
      "equalTo": "1969-07-21"
    }
  }
}

To specify a set of dates:

{
  "filter": {
    "date": {
      "in": ["1969-07-20", "1969-07-21"]
    }
  }
}

To search for a date range use a DateTimeFilter

You can filter with ISO 8601 timestamps as a filter.

To find entities that were created or posted before a certain timestamp use the before operator:

query GetLedgerEntries($ledgerAccountId: ID!, $filter: LedgerLinesFilterSet) {
  ledgerAccount(ledgerAccount: {id: $ledgerAccountId}) {
    lines(filter: $filter) {
      nodes {
        id
        posted
        date
        amount
        description
        ledgerEntryId
      }
    }
  }
}

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "posted": {
      "before": "1969-07-21T02:56:00.000Z"
    }
  }
}

You can also search using the after operator:

{
  "filter": {
    "posted": {
      "after": "1969-07-21T02:56:00.000Z"
    }
  }
}

To specify a range supply both before and after. You can also use shortened dates:

{
  "filter": {
    "posted": {
      "after": "1969-01-01"
      "before": "1969-12-31"
    }
  }
}

To filter ledger accounts by their linked accounts, send a filter argument in your query with an equalTo, in, or isLinkedAccount operator:

query GetLinkedLedgerAccounts($ledgerId: ID!, $filter: LedgerAccountsFilterSet!) {
  ledger(ledger: {id: $ledgerId}) {
    id
    ledgerAccounts(filter: $filter) {
      nodes {
        id
        name
        linkedAccount {
          id
          name
        }
      }
    }
  }
}

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "isLinkedAccount": true
  }
}

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "linkedAccount": {
      "equalTo": {
        "id": <external account id>
      }
    }
  }
}

To search for multiple parents you can use the in operator:

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "linkedAccount": {
      "in": [
        { "id": <external account id 1> },
        { "id": <external account id 2> }
      ]
    }
  }
}

To filter ledger accounts by the presence of a parent or a specific parent, send a filter argument in your query with an equalTo, in, or hasParentLedgerAccount operator:

query GetLedgerAccounts($ledgerId: ID!, $filter: LedgerAccountsFilterSet!) {
  ledger(ledger: {id: $ledgerId}) {
    id
    ledgerAccounts(filter: $filter) {
      nodes {
        id
        name
        parentLedgerAccountId
        parentLedgerAccount {
          id
          name
        }
      }
    }
  }
}

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "hasParentLedgerAccount": true
  }
}

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "parentLedgerAccount": {
      "equalTo": {
        "id": "<ledger account id>"
      }
    }
  }
}

To search across multiple parents you can use the in operator:

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "parentLedgerAccount": {
      "in": [{ "id": "<parent ledger id 1>" }, { "id": "<parent ledger id 2>" }]
    }
  }
}

You can combine filters by adding multiple components to the filter block. Results are ANDed. Example:

{
  "ledgerId": "ledger-id-1",
  "filter": {
    "hasParentLedgerAccount": true,
    "type": {
      "in": ["asset", "liability"]
    }
  }
}

Each Ledger Account has five balances that can be queried:

• ownBalance The sum of all ledger lines in the account, excluding ledger lines in child ledger accounts.
• childBalance The sum of all ledger lines in child ledger accounts in the account's currency
• balance The sum of all ledger lines, including child ledger accounts in the account's currency.
• ownBalances The sum all ledger lines in the account in all currencies, excluding ledger lines in child ledger accounts..
• childBalances The sum all ledger lines in child ledger accounts in all currencies.
• balances The sum of all ledger lines, including child ledger accounts in all currencies.

query GetBalances ($ledgerId: ID!) {
  ledger(ledger: {id: $ledgerId}) {
    ledgerAccounts {
      nodes {
        id
        name
        type
        ownBalance
        childBalance
        balance

        childBalances {
          nodes {
            currency {
              code
            }
            amount
          }
        }
        balances {
          nodes {
            currency {
              code
            }
            amount
          }
        }
      }
    }

}
}

You will likely only use balance and childBalance. If you're tracking multiple currencies in the same ledger, use balances and childBalances.

You can query the balance at a particular point in time using an at argument:

query GetBalances ($ledgerId: ID!) {
  ledger(ledger: {id: $ledgerId}) {
    ledgerAccounts {
      nodes {
        id
        name
        type
        end_of_year: balance(at: "2021")
        end_of_month: balance(at: "2021-06")
        end_of_day: balance(at: "2021-06-15")
        end_of_hour: balance(at: "2021-06-15T06")
      }
    }
  }
}

If you don't specify at, you'll get the latest balance. at is supported for all balances and works down to the hour granularity.

You can also query the net change on a ledger account over a specific period:

• ownBalanceChange How much ownBalance changed.
• childBalanceChange How much childBalance changed.
• balanceChange How much balance changed.
• ownBalanceChanges How much ownBalances changed.
• childBalanceChanges How much childBalances changed.
• balanceChanges How much balances changed.

Similar to querying point-in-time balances above, if you're doing multi-currency accounting, you'll want to use the plural 'changes' fields.

You can specify the Period as a year, quarter, month, day or hour, as well as make multiple queries using aliases:

query GetBalanceChanges($ledgerId: ID!) {
  ledger(ledger: {id: $ledgerId}) {
    ledgerAccounts {
      nodes {
        id
        name
        type
        ownBalanceChange(period: "2021")
        childBalanceChange(period: "2021")
        balanceChange(period: "2021")
        currentYear: balanceChange(period: "2021")
        lastYear: balanceChange(period: "2020")
        lastYearQ4: balanceChange(period: "2020-Q4")
        lastYearDecember: balanceChange(period: "2020-12")
        lastYearChristmas: balanceChange(period: "2020-12-25")
        lastYearLastHour: balanceChange(period: "2020-12-31T23")
        childBalanceChanges(period: "2021") {
          nodes {
            currency {
              code
            }
            amount
          }
        }
        balanceChanges(period: "2021") {
          nodes {
            currency {
              code
            }
            amount
          }
        }
      }
    }

}
}

Balance queries will respect the ledger's balanceUTCOffset when specifying periods and times:

• If a ledger has an offset of -08:00, then querying balance(at: "2021-01-31") will return the balance at midnight PT on that date, or 8am on 2021-02-01 UTC.
• Likewise, querying balanceChange(period: "2021") will return the net change between 8am on 2021-01-01 UTC and 8am on 2022-01-01 UTC. This gives you the net change between midnights local time.
• Daylight savings is ignored, so every day throughout the year has exactly 24 hours. Trust us on this one.

To generate a Balance Sheet, query the balances on State accounts. Remember, we can add the at parameter to balance to get the Balance Sheet at a given point in time.

query GetBalanceSheet ($ledgerId: ID!, $filter: LedgerAccountsFilterSet!) {
  ledger(ledger: {id: $ledgerId}) {
    ledgerAccounts(filter: $filter) {
      nodes {
        id
        name
        type
        balance
      }
    }
  }
}

{
  "ledgerId": <some-ledger-id>,
  "filter": {
    "type": {
      "in": ["asset", "liability"]
    }
  }
}

To generate an Income Statement, query balance changes on Change accounts.

query GetIncomeStatement ($ledgerId: ID!, $filter: LedgerAccountsFilterSet!) {
  ledger(ledger: {id: $ledgerId}) {
    ledgerAccounts(filter: $filter) {
      nodes {
        id
        name
        type
        balanceChange(period: "1969")
      }
    }
  }
}

{
  "ledgerId": <some-ledger-id>,
  "filter": {
    "type": {
      "in": ["income", "expense"]
    }
  }
}

To generate a monthly Account Statement, query the balances. Since the date provided to at in balance is inclusive, the last day of the previous month is used to query startingBalance. For example, the balance at the end of May, inclusive of entries posted on May 31st, should be the starting balance for June.

query GetAccountStatement ($ledgerId: ID!, $filter: LedgerAccountsFilterSet!) {
  ledger(ledger: {id: $ledgerId}) {
    ledgerAccounts(filter: $filter) {
      nodes {
        id
        name
        type
        startingBalance: balance(at: "1969-05-31")
        endingBalance: balance(at: "1969-06-30")
      }
    }
  }
}

{
  "ledgerId": <some-ledger-id>,
  "filter": {
    "type": {
      "in": ["asset", "liability"]
    }
  }
}

key: {export name}/LedgerEntry/day={day}/hour={hour}/{partition}.part

Download Example File

key: {export name}/LedgerLine/day={day}/hour={hour}/{partition}.part

Download Example File

key: {export name}/LedgerAccount/day={day}/hour={hour}/{partition}.part

Download Example File