Update Metadata Behavior

Last updated: October 7, 2025

The Update Metadata endpoint in Formance Ledger performs an additive, idempotent update of metadata on transactions or accounts. It’s designed to simplify partial metadata updates without overwriting unrelated keys.

Using the UI

Navigate to the account details in the user interface and update the desired metadata field directly.

Using the API

Make a request to the metadata endpoint to update specific values. The update operation is additive

Endpoint:

POST /{ledger}/transactions/{txid}/metadata
POST /{ledger}/accounts/{accountid}/metadata

Operation type:

Additive & idempotent partial update.

Behavior details:

Scenario

Behavior

Effect in DB / History

Key does not exist

Creates new metadata key-value pair

New entry created

Key exists with a different value

Updates existing key with new value

ledger records a new version of metadata (+ timestamp update if feature XXX_METADATA_HISTORY in SYNC).

Key exists with the same value

Request succeeds with HTTP 204 No Content

No database update or timestamp change

Practical Notes

  • The operation is idempotent — repeated calls with the same metadata produce no side effects.

  • The ledger preserves all existing keys not included in the update request.

  • The effective metadata value and its “as-of” timestamp remain unchanged when the new value equals the old one.

  • While redundant updates are harmless (no risk of data duplication or history noise), avoiding them can reduce API and DB load.