Skip to main content

Delayed Assignment of ledger_account_lock_version

Clayton Kohler

In order to better support high-throughput ledgering, we’re implementing an under-the-hood change that will batch the creation of some ledger entries. You can expect to see an improvement in your write throughput as a result. This speedup will most likely not require any changes to your integration, but read on to see if changes are required for yours.

This guide will cover

What is changing?

You may notice a behavior change when writing certain ledger entries. For these entries, you will see an initial response with a null value for ledger_account_lock_version in the response to the Ledger Transactions API:

{ 
    "id": "592712a9-1658-4492-9771-922b0e816f1e", 
    "object": "ledger_transaction",
    …
    "ledger_entries": [ 
        { 
            "id": "f7fc5295-6953-475a-a7f9-74934918f5e1",
            "object": "ledger_entry",
            …
            "ledger_account_lock_version": 355, 👈 non-null is still possible 
            …
        },
        { "id": "e8c9f3cc-fdb2-4555-b66d-94f2fa5c87e5",
        "object": "ledger_entry",
        …
        "ledger_account_lock_version": null, 👈 null value in response
        …
        }
     ], 
     …
}

For these entries, a lock version will typically be assigned about one second after the Ledger Entry was created, at the same time the Ledger Account balance is updated to reflect the Ledger Entry itself.

This behavior will only occur with entries that do not enforce a lock on a ledger account using the lock_version, pending_balance_amount, posted_balance_amount, available_balance_amount, or show_resulting_ledger_account_balances parameters.

How can I adjust to the change?

If your code relies on the ledger_account_lock_version in the response to creating an entry, you may need to make changes. Your use case for that data will dictate the kind of change that should be made; reach out to our Support team if you rely on that value being present for your business logic.

If you want to always guarantee that a non-null ledger_account_lock_version is returned, you can pass a locking parameter such as show_resulting_ledger_account_balances when creating the ledger entry.

Additionally, if your code calls Get Ledger Account immediately after writing a transaction to that account, the balance returned on the account is no longer always read-after-write consistent. If you need the balance of the account to immediately reflect a transaction, be sure to include a lock on the entry for the account, or use the show_resulting_ledger_account_balances parameter.

What’s happening under the hood?

For some of our customers, a disproportionate number of ledger entries are written to one or two Ledger Accounts (such as “Cash” or “Card Settlement”). It’s important that these “hot” ledger accounts can record a high throughput of entries. Therefore, in these cases we process updates in batches which combine Ledger Entries for a particular Ledger Account which are created within the same time window.

For other Ledger Accounts, such as customer wallet accounts, avoiding race conditions is more important than high throughput. Therefore, entries that enforce locks are guaranteed to be processed synchronously, not batched.

When is this happening?

This change will take effect on March 6th, 2023.

Related articles