Filtering Accounts with the first_usage Field

Introduction

The Formance Ledger offers a powerful filtering syntax to help you query accounts, transactions, and volumes in a precise way. A new filterable field, first_usage, has been introduced on the /accounts and /volumes endpoints. This field allows you to filter based on the very first time an account was used, making it easier to target accounts according to their lifecycle in your ledger.

What is first_usage?

• Definition: first_usage is a timestamp that represents the first time an account has been involved in a transaction.

• Behavior: If a back-dated transaction is posted (i.e., with a timestamp earlier than the account’s current first_usage), the first_usage value is updated accordingly.

• Filterability: You can use first_usage with the standard comparison operators:

  • $lt / $lte (before or on a given timestamp)

  • $gt / $gte (after or on a given timestamp)

This means first_usage can safely be used in filters without ambiguity or inconsistency.

Practical Example

Scenario

You want to retrieve all accounts that were first used before January 1, 2023. This can help you, for example, analyze legacy accounts or perform reporting on accounts that have been active since a certain period.

Request Example

GET /ledger/accounts 
{ "$and": 
   [ 
      {"$match": { "address": "user:" } }, 
      { "$lt": { "first_usage": "2023-01-01T00:00:00Z" } } 
   ]
}

Response Example

{ "data": [ 
  { 
    "address": "users:001",
    "metadata": {},
    "first_usage": "2022-06-15T10:23:54Z" 
  }, 
  { 
    "address": "users:045", 
    "metadata": {}, 
    "first_usage": "2022-12-30T14:11:07Z" 
   } 
], "cursor": { "pageSize": 15 } }

Here, only accounts first used before 2023-01-01T00:00:00Z are returned.

Conclusion

The first_usage field is a reliable way to query accounts and volumes based on their first transaction date. With support for comparison operators, it gives you flexibility to:

• Identify legacy or newly created accounts

• Run time-based reporting

• Enforce business rules based on account activity windows

By leveraging this field, you gain a finer level of control over your ledger queries.