Ledger V1 -> V2

[TomWright]

Hi there,

I'm working on a product and we use ledger as a standalone micro-service.

I have observed that were are still using V1. It is functional and works fine, but it leaves me asking:

1. What does V2 provide that V1 does not?
2. Is this a simple upgrade or does it risk downtime or data loss?
3. Should I upgrade to V2 in order to get the latest fixes + features or stay on V1?

These are quite broad questions so I'm sorry but for that, but I couldn't find any clear upgrade path documented and am largely unfamiliar with the ledger project.

Any insight or guidance would be appreciated.

Thanks

[aalloiteau]

Hi @TomWright

Thanks for your question!

Yes, you should upgrade to Ledger v2, as it brings a number of important improvements and architectural changes compared to v1.
While v1 remains functional, v2 introduces enhanced performance, new features, and a stateless service model.
New interesting endpoints such as /volumes and _bulk, a new filtering syntax, UI and much more

You can find a high-level overview of the main changes here:
🔗 Stack v3.0 Changelog (embedding ledger 2.2)
and latest stack v3.1
🔗 Stack v3.1 Changelog (embedding ledger 2.3)

Yes, expect a (full) downtime with this upgrade. Make sure to follow the following steps and carefully test in local before production
Migrate to latest v1.X, then migrate to latest v2.0.X, then upgrade until 2.3

Note we added a zero-downtime mechanism starting Ledger 2.2

Manual Migration

• Back up your database before proceeding
• Run the command: ledger migrate

From Ledger Version 2.2+: Automatic Migration
For version 2.2 and above, you can enable automatic schema upgrades by either:

• Setting the flag: --auto-upgrade
• Or setting the environment variable: AUTO_UPGRADE

The auto-upgrade option is particularly useful in development environments but should be used with caution in production.

[TomWright]

Thank for the detailed response! I'll bring this back to the team.

One more question if you don't mind - is the update to 2.2/2.3 a hard switch over? By that I mean, are the V1 HTTP API's still available and functioning in those versions? Or will be also need to upgrade and do an all-at-once deployment?

Thanks

[aalloiteau]

Hi @TomWright,

To minimize migration impact, the ledger service retains near-complete backward compatibility with the v1 API.
The v2 API is exposed under the /v2 prefix, so both generations can coexist.

Example:

/ledger/{ledger}/transactions     → v1 endpoints
/ledger/v2/{ledger}/transactions  → v2 endpoints

SDKs now expose both .v1 and .v2 methods, allowing progressive migration rather than an all-at-once switch.

---

⚠️ Breaking Changes (even when using v1 endpoints)

While most v1 endpoints remain functional, some behaviors are no longer supported internally in the new ledger:

• Batch requests are no longer allowed. The ledger handles batching internally.
• Free-form metadata objects are no longer supported.
  Metadata must now use flat key/value pairs (no nested structures).
  Filtering based on nested metadata keys will no longer work.
• Pre/post commit volumes are no longer returned on transaction creation routes.

---

API v2 Highlights

Major changes:

• Filtering:
  All query parameters used for filtering have been removed.
  Filtering is now done via a JSON-based request body. cf docs here

• pit (Point-In-Time) parameter:
  Allows querying the ledger state at a specific timestamp.

• expand parameter:
  Available on /accounts and /transactions routes.
  Controls inclusion of balance/volume data:

  • volumes → standard volumes
  • effectiveVolumes → effective (post-commit) volumes
    Both can be combined.

• /balances route removed:
  Account balances are now directly available via /accounts.

• New endpoint /volumes
  New endpoint to get total input/output and balance w/ ability to group and query on a pit or over a period

• New endpoint /_bulk
  Batch endpoint from v1 is being replaced for a much more flexible _bulk endpoint

• New field reverted on transactions.

• New field insertionDate & updatedAt on accounts.

• Ability to filter accounts based on the time of first usage (first transaction).

• Improved revert behavior with metadata + balance accuracy.

• Improved idempotency key validation
  If the key was used before but with different transaction details, the API will now return a validation error (500)

• New parameter runtime on /transactions to select Numscript interpreter

Minor changes:

• Transaction creation now returns only the transaction object, not an array.
• Transaction property txid renamed to id.
• Route /_info now aligns with other Formance services’ response formats.
• Ability to serialize large integers as strings to avoid overflow in JSON parsers

[TomWright]

That's perfect, thanks so much for the details.