The FRAGMENT workflow is:

• Ledger: a data structure modeling funds for a single entity. Ledgers are created using the createLedger mutation. The FRAGMENT CLI provides a convenient wrapper around this mutation. If your use case requires you to manage multiple Ledgers, call the createLedger mutation directly from your application.
• API: data is created in a Ledger via the GraphQL API. Use addLedgerEntry to post logical Ledger Entries, reconcileTx to reconcile transactions from an external system to your Ledger, and createOrder or makeBankTransfer to make payments. See Accounting, Reconciliation, and Payments to learn more about the API.
• Schema: a JSON-based declarative source of truth for the structure of your Ledger. In your CI or deployment system, use the CLI to run fragment store-schema. This creates or updates your Schema like a database migration. When this is run, FRAGMENT automatically migrates all Ledgers using the Schema with the updated Ledger Accounts and Ledger Entry types.

The API URL for your environment can be found in the API Clients page of the Dashboard.

You can find the GraphQL schema hosted at:

https://api.fragment.dev/schema.graphql

You can use this schema as input to auto-generate an SDK to use to call the FRAGMENT API. The GraphQL Foundation maintains an updated list of tools. We recommend that you do this as part of your CI, to ensure that you always have the latest schema.

There are only integer amounts in the API. This forces you to use the minor units in the appropriate currency. For USD, a single unit is 1 cent. To represent $1.25, you'd pass in 125.

In financial systems, it's important to achieve exactly-once processing. For example, when debiting a customer's bank account, only one ACH Debit should be made. FRAGMENT's API is idempotent, so your system needs to only handle at-least-once processing when calling the FRAGMENT API.

To achieve idempotency, mutations in the FRAGMENT API require a unique and stable idempotency key (IK). These let you confidently retry operations without them running twice. If you execute a mutation more than once with the same IK and variables, FRAGMENT will ignore your request and return the original response with the isIkReplay flag set to true. IKs in FRAGMENT:

• are scoped per-Ledger. If you send multiple requests with the same IK to a single ledger, only one mutation will execute with isIkReplay: false, while the rest will return the original response with isIkReplay: true. If you send multiple requests with the same IK to multiple different ledgers, all mutations will execute and return isIkReplay: false.
• are valid for 30 days. If you resend an IK after 30 days, it could be executed as a fresh request.
• are only valid for 1 hour when initiating transfers at Increase through the makeBankTransfer or createOrder mutations. This is so we match Increase's idempotency window. All other FRAGMENT mutations support IKs for 30 days.

When referencing an entity in FRAGMENT, the API requires you to provide a MatchInputs. This gives you the flexibility to match for an entity in multiple ways.

Each entity has a FRAGMENT-generated id which can be used in all queries.

For Ledgers, it's recommended to query with the IK's you've provided to FRAGMENT instead. This lets you not store the FRAGMENT ID of the Ledger in your system.

{
  "ledger": {
    "ik": "ledger-ik"
  }
}

You can also match LedgerAccounts via their path. The path is a forward-slash-delimited string containing the IK of a Ledger Account and all its direct ancestors. When querying with path, you'll also need to provide a LedgerMatchInput to identify which Ledger the Ledger Account belongs to.

{
  "path": "parent-ik/child-ik/grandchild-ik",
  "ledger": {
    "ik": "ledger-ik"
  }
}

Errors are first-class citizens of our API. All mutations return a union type that represents either an error or a successful result. For example, the response type of the addLedgerEntry mutation is as follows:

union AddLedgerEntryResponse = AddLedgerEntryResult | BadRequestError | InternalError

When calling the API, your code should:

1. Query the __typename field to see if the operation was successful.
2. Handle non-200 responses. This typically happens due to transient errors or if your query does not conform to FRAGMENT's GraphQL spec (i.e: omitting a required variable or selecting a nonexistent field).
3. Handle error type 200 responses. This is always a BadRequestError or InternalError.
4. Handle success types (i.e. AddLedgerEntryResult).

Fields that return lists support cursor-based pagination.

• Results are returned under a nodes property as an array. The pageInfo property contains cursors pointing to the next page and previous pages
• You can send a cursor to the after or before arguments on list fields to retrieve a specific page
• The first argument sets the page size. The default is 20 and the maximum is 200
• Once a page size has been set in the initial request, all subsequent pagination has to use the same page size
• Results are returned in a deterministic order. This is generally reverse chronological; newest first. This sort is by posted date for Ledger Lines and Ledger Entries, or creation date for other entities.

query GetLedgerAccounts(
    $ledgerIk: SafeString!
    $after: String
    $first: Int
    $before: String
  ) {
    ledger(ledger: { ik: $ledgerIk }) {
      ledgerAccounts(
        after: $after
        first: $first
        before: $before
      ) {
        nodes {
          path
          name
          type
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
      }
    }
  }

{
  "ledgerIk": "ik-used-to-create-ledger",
  "first": 2
}

This query uses pagination to retrieve 2 Ledger Accounts at a time.

{
  "data": {
    "ledger": {
      "ledgerAccounts": {
        "nodes": [
          {
            "path": "assets/test-assets/test:1",
            "name": "Test 1",
            "type": "asset"
          },
          {
            "path": "assets/test-assets/test:2",
            "name": "Test 2",
            "type": "asset"
          }
        ],
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "<some-end-cursor>",
          "hasPreviousPage": false,
          "startCursor": null
        }
      }
    }
  }
}

This would be the response.

{
  "ledgerIk": "ik-used-to-create-ledger",
  "after": "<some-end-cursor>"
}

To retrieve the next page, send the same query but with the after parameter set on ledgerAccounts.

{
  "data": {
    "ledger": {
      "ledgerAccounts": {
        "nodes": [
          {
            "path": "assets/test-assets/test:3",
            "name": "Test 3",
            "type": "asset"
          },
          {
            "path": "assets/test-assets/test:4",
            "name": "Test 4",
            "type": "asset"
          }
        ],
        "pageInfo": {
          "hasNextPage": false,
          "endCursor": null,
          "hasPreviousPage": true,
          "startCursor": "<some-start-cursor>"
        }
      }
    }
  }
}

The response looks like this.

{
  "ledgerIk": "ik-used-to-create-ledger",
  "before": "<some-start-cursor>"
}

To retrieve the previous page of results, send the same query but with the before parameter set on ledgerAccounts. The response will be the first page of results.

You can filter result sets via the filter parameter on Connection types when performing list queries. The API Reference documents this in detail.

The API has several filter types built-in:

• TypeFilters (e.g. LedgerAccountTypeFilter or TxTypeFilter)
• DateFilter
• DateTimeFilter
• Boolean
• ExternalAccountFilter
• LedgerAccountFilter

query GetLedgerAccounts(
  $ledgerIk: SafeString!
  $accountsFilter: LedgerAccountsFilterSet!
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerAccounts(filter: $accountsFilter) {
      nodes {
        id
        name
        type
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "type": {
      "equalTo": "asset"
    }
  }
}

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

query GetAccountLinesOnDate(
  $accountMatch: LedgerAccountMatchInput!
  $linesFilter: LedgerLinesFilterSet!
) {
  ledgerAccount(ledgerAccount: $accountMatch) {
    lines(filter: $linesFilter) {
      nodes {
        id
        posted
        date
        amount
        description
        ledgerEntryId
      }
    }
  }
}

{
  "accountMatch": {
    "ledger": {
      "ik": "ik-used-to-create-ledger"
    },
    "path": "liabilities/customer-deposits/customer:123"
  },
  "linesFilter": {
    "date": {
      "equalTo": "1969-07-21"
    }
  }
}

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

query GetLedgerEntries(
  $accountMatch: LedgerAccountMatchInput!
  $linesFilter: LedgerLinesFilterSet
) {
  ledgerAccount(ledgerAccount: $accountMatch) {
    lines(filter: $linesFilter) {
      nodes {
        id
        posted
        date
        amount
        description
        ledgerEntryId
      }
    }
  }
}

{
  "accountMatch": {
    "ledger": {
      "ik": "ik-used-to-create-ledger"
    },
    "path": "liabilities/customer-deposits/customer:123"
  },
  "linesFilter": {
    "posted": {
      "before": "1969-07-21T02:56:00.000Z"
    }
  }
}

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

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

query GetLinkedLedgerAccounts(
  $ledgerIk: SafeString!
  $accountsFilter: LedgerAccountsFilterSet!
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerAccounts(filter: $accountsFilter) {
      nodes {
        path
        name
        linkedAccount {
          externalId
          name
        }
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "isLinkedAccount": true
  }
}

query GetLedgerAccounts(
  $ledgerIk: SafeString!
  $accountsFilter: LedgerAccountsFilterSet!
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerAccounts(filter: $accountsFilter) {
      nodes {
        path
        name
        parentLedgerAccount {
          path
          name
        }
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "hasParentLedgerAccount": true
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "linkedAccount": {
      "equalTo": {
        "linkId": "link-id",
        "externalId": "<external account id"
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "linkedAccount": {
      "in": [
        { "id": <external account id 1> },
        { "id": <external account id 2> }
      ]
    }
  }
}

query GetLedgerAccounts(
  $ledgerIk: SafeString!
  $accountsFilter: LedgerAccountsFilterSet!
) {
  ledger(ledger: { ik: $ledgerIk }) {
    ledgerAccounts(filter: $accountsFilter) {
      nodes {
        path
        name
        parentLedgerAccount {
          path
          name
        }
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "filter": {
    "parentLedgerAccount": {
      "equalTo": {
        "ledger": {
          "ik": "ik-used-to-create-ledger"
        },
        "path": "liabilities/customer-deposits/customer:123"
      }
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "filter": {
    "parentLedgerAccount": {
      "in": [
        { "id": "<parent ledger account id 1>" },
        { "id": "<parent ledger account id 2>" }
      ]
    }
  }
}

{
  "ledgerIk": "ik-used-to-create-ledger",
  "accountsFilter": {
    "hasParentLedgerAccount": true,
    "type": {
      "in": ["asset", "liability"]
    }
  }
}

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. In FRAGMENT, you model your Ledger using a Schema.

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

{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
      },
      {
        "key": "debt-root",
        "name": "Debt",
        "type": "liability",
      },
    ]
  }
}

{
  "chartOfAccounts": {
    "defaultCurrencyMode": "single",
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset"
      }
    ]
  },
}

{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "Customer 1",
        "type": "liability",
        "children": [
          {
            "key": "Available"
          },
          {
            "key": "Unsettled",
          },
          {
            "key": "Blocked"
          },
        ]
      }
    ]
  }

A Ledger Entry is a single update to a Ledger. A Ledger Entry consists of two or more Ledger Lines. The sum of the amounts of the Ledger Lines must follow the Accounting Equation.

This is a simple Ledger Entry containing two Ledger Lines. One Ledger Line posts to an Asset account and the other posts to an Income account.

{
  "ledgerEntries": {
    "types": [
      {
        "type": "buy_materials",
        "lines": [
          {
            "key": "bank",
            "account": { "path": "assets-root/bank" },
            "amount": "-{{materials_cost}}"
          },
          {
            "key": "materials_expense",
            "account": { "path": "expense-root/materials" },
            "amount": "{{materials_cost}}"
          }
        ]
      }
    ]
  }
}

{
  "type": "buy_materials",
  "ledger": {
    "ik": "my-ledger-ik"
  },
  "parameters": {
    "materials_cost": "1500"
  }
}

{
  "ledgerEntries": {
    "types": [
      {
        "type": "sell_something",
        "lines": [
          {
            "key": "sales_to_bank",
            "account": { "path": "assets-root/bank" },
            "amount": "{{sales_before_tax}} + {{tax_payable}}"
          },
          {
            "key": "income_from_sales_before_tax",
            "account": { "path": "income-root/sales" },
            "amount": "{{sales_before_tax}}"
          },
          {
            "key": "tax_payable",
            "account": { "path": "debt-root/tax_payables" },
            "amount": "{{tax_payable}}
          }
        ]
      }
    ]
  }
}

The Chart of Accounts can include Ledger Account templates. A template is a repeated subtree of Ledger Accounts that are configured in the Schema. Templates can be useful when your Ledger models financial relationships with a repeated entity, such as users of your product.

{
  "chartOfAccounts": {
    "accounts": [
      {
        "key": "user",
        "type": "liability",
        "template": true,
        "children": [
          {
            "key": "available"
          },
          {
            "key": "unsettled"
          },
          {
            "key": "blocked"
          }
        ]
      },
      {
        "key": "bank",
        "type": "asset",
        "template": false
      }
    ]
  }
}

The template field in the Schema signifies a Ledger Account template. When the Schema is applied, this subtree is not instantiated. Instead, accounts in this subtree are created just-in-time when you first post a Ledger Entry to this part of the tree.

{
  "ledgerEntries": {
    "types": [
      {
        "type": "user_funding",
        "lines": [
          {
            "key": "funds_arrive_in_bank",
            "account": {
              "path": "bank"
            },
            "amount": "-{{funding_amount}}"
          },
          {
            "key": "user_balance",
            "account": {
              "path": "user:{{user_id}}/available"
            },
            "amount": "{{funding_amount}}"
          }
        ]
      }
    ]
  }
}

Ledger Entries that posts to Ledger Account templates specify an identifier within the Ledger Account path. When the Ledger Entry is posted, the path is constructed with the parameters provided to the API. The Ledger Account subtree gets created if necessary.

In this example, the path for the available account for user 1234 would be liabilities-root/user:1234/available.

The templated path syntax lets you use identifiers from your system to refer to Ledger Accounts in FRAGMENT. It is also used when querying.

Ledger Accounts in FRAGMENT support the single or multi currency mode. A Ledger Account in the single currency mode only accepts Ledger Lines of the same currency as the Ledger Account. In the multi currency mode, Ledger Lines of any currency are allowed.

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

{
  "chartOfAccounts": {
    "defaultCurrency": {
      "code": "USD"
    },
    "defaultCurrencyMode": "single",
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset"
      }
    ]
  }
}

In most use cases, all Ledger Accounts in a Ledger will share the same currency and currencyMode. For convenience, you can set these as defaults within Schema.

{
  "chartOfAccounts": {
    "defaultCurrency": {
      "code": "USD"
    },
    "defaultCurrencyMode": "single",
    "accounts": [
      {
        "key": "assets-root",
        "name": "Assets",
        "type": "asset",
        "currency": {
          "code": "CAD"
        }
      }
    ]
  }
}

To override the default for a specific Ledger Account, you can set currency and currencyMode directly on that account.

{
  "ledgerEntries": {
    "types": [
      {
        "type": "buy_materials",
        "lines": [
          {
            "key": "bank",
            "account": { "path": "assets-root/bank" },
            "amount": "-{{materials_cost}}",
            "currency": {
              "code": "{{expense_currency}}"
            }
          },
          {
            "key": "materials_expense",
            "account": { "path": "expense-root/materials" },
            "amount": "{{materials_cost}}",
                  "currency": {
              "code": "{{expense_currency}}"
            }
          }
        ]
      }
    ]
  }
}

You can also parameterize the currency for a Ledger Line. This is required when posting Ledger Entries to Ledger Accounts with the multi currency mode. For more on how you might use the multi currency mode, see Multi-currency.

In Accounting, Ledger Entries are recorded at the time the money movement event happened. However, since there is latency in software systems, you can't post a Ledger Entry exactly when the corresponding event happens. To solve this, Ledgers use a logical clock.

Ledger Entries have two time timestamps:

• posted: the logical time for the Ledger Entry
• created: the system time the Ledger Entry was recorded in FRAGMENT

You provide posted in LedgerEntryInput when you call the API. FRAGMENT automatically generates created based off internal system time.

You can post Ledger Entries at any point in time, including the future. You can also query balances at any timestamp. Posting a Ledger Entry will update all balances from the posted time into the future.

FRAGMENT supports querying a Ledger Account for its balances, historical balances, and balance changes.

query GetBalances ($ledgerIk: SafeString!) {
  ledger(ledger: {ik: $ledgerIk}) {
    ledgerAccounts {
      nodes {
        id
        name
        type
        ownBalance
        childBalance
        balance
        childBalances {
          nodes {
            currency {
              code
            }
            amount
          }
        }
        balances {
          nodes {
            currency {
              code
            }
            amount
          }
        }
      }
    }
  }
}

query GetBalances ($ledgerIk: SafeString!) {
  ledger(ledger: {ik: $ledgerIk}) {
    ledgerAccounts {
      nodes {
        id
        name
        type
        end_of_year: balance(at: "1969")
        end_of_month: balance(at: "1969-07")
        end_of_day: balance(at: "1969-07-21")
        end_of_hour: balance(at: "1969-07-21T02")
      }
    }
  }
}

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

Links mirror external systems that move and store money. Links can be any store of value be it banks, brokerages, card processors, crypto wallets, rewards points, or loan issuers.