Sometimes you need to include more information with a transaction. For example:
- You want to associate a transaction with a specific purchase.
- You need to include a payment reference with the transaction.
- You want to include metadata to keep the ledger in sync with an external system.
Make sure that you're set up properly: Read through the prerequisites first!. Otherwise the examples below won't work.
Attaching transaction metadata
In the game land of Cones Dunshire, building cones is a central part of playing the game. As ledgerman, we want to keep track of how much players have spent on building cones for analytical reasons. We can do this by flagging transactions that represent spending on cone building, using metadata.
leslieknope just spent 100 coin to build a minor cone. Let's create that transaction, and flag it with metadata. Create a file called
And run it with
numary exec dunshire metadata.num
Are you seeing
FATA account had insufficient funds
in your output? The source accounts need to have enough funds before you run this example. Make sure you're set up properly.
Once you've run that transaction succesfully, let's have a look at
leslieknope's balance' to find that transaction. It should be the topmost one listed. Click the details arrow to the right of the transaction to get more details.
On the transaction detail page, you'll find a snippet of JSON at the end that will look something like this:
You can see the
metadata field with the details of the information we added to the transaction.
What's going on here?
Metadata is arbitrary data that you can attach to a transaction (or an account! But more on that later). This data is typed, and can be a string or a number. You can retrieve (or even add to) this metadata later using the HTTP API, for integration into your own bespoke workflows.
Storing variables in metadata
You can store the value of template variables in metadata as well. Template variables may only be of
portion types, and must be specified like the following examples:
Formance Ledger allows you to also add metadata to accounts. This metadata can be used to construct much more sophisticated transactions, with variables that bind to specific metadata at execution time. At the moment, we don't have documentation for how to use these feature, but expect them soon.