403 on v2 list transactions endpoint but not on v1

[Charzander]

There seems to be an issue with how the SDK is handling auth between these two endpoints. Observe the diff below and note that this fixes the 403s. Also note that we had to upgrade because the v1 endpoint does not correctly filter by date range and had post fetch filtering applied.

--- a/services/formance/client.py
+++ b/services/formance/client.py
@@ -69,7 +69,7 @@ class FormanceClient:
     def _list_transactions(self, customer_id: str, start: datetime | None = None, end: datetime | None = None):
         """
         List transactions for the customer's main account between [start, end).
-        Since the API's date range filtering doesn't work, we fetch all transactions and filter manually.
+        Uses Formance's filtering query syntax for proper API-level filtering.
         """
         if start and end and end <= start:
             raise ValueError("end must be after start")
@@ -77,57 +77,54 @@ class FormanceClient:
         account_id = self._get_customer_main_account(customer_id)
         transactions: list[shared.V2Transaction] = []
         cursor = None
-        # Build request body with filter parameters
-        request_body = {}
+
+        # Build query filter using Formance's filtering syntax
+        # Reference: https://docs.formance.com/modules/ledger/working-with-the-ledger/filtering-queries
+        filters = []
+
+        # Filter by destination account
         if account_id:
-            request_body["destination"] = account_id
+            filters.append({"$match": {"destination": account_id}})
+
+        # Filter by timestamp range
         if start:
-            request_body["startTime"] = start.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+            filters.append({"$gte": {"timestamp": start.isoformat()}})
         if end:
-            request_body["endTime"] = end.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+            filters.append({"$lt": {"timestamp": end.isoformat()}})
 
-        first_req = operations.ListTransactionsRequest(
+        # Combine filters with $and if multiple filters exist
+        query_filter = None
+        if len(filters) > 1:
+            query_filter = {"$and": filters}
+        elif len(filters) == 1:
+            query_filter = filters[0]
+
+        first_req = operations.V2ListTransactionsRequest(
             ledger=self._ledger_name,
-            destination=account_id,
-            start_time=start.isoformat(),
-            end_time=end.isoformat(),
+            request_body=query_filter,
         )
         while True:
             req = (
                 first_req
                 if cursor is None
-                else operations.ListTransactionsRequest(
+                else operations.V2ListTransactionsRequest(
                     ledger=self._ledger_name,
                     cursor=cursor,
+                    request_body=query_filter,
                 )
             )
-            resp = self._get_client().ledger.v1.list_transactions(request=req)
+            resp = self._get_client().ledger.v2.list_transactions(request=req)
             if resp.status_code != 200:
                 raise Exception(
                     f"Failed to list transactions for customer {customer_id} with status code: {resp.status_code}"
                 )
-            cur = resp.transactions_cursor_response.cursor
+            cur = resp.v2_transactions_cursor_response.cursor
             transactions.extend(cur.data)
             cursor = cur.next
             if not cursor:
                 break
 
         logging.debug(f"Found {len(transactions)} transactions for customer {customer_id}")
-        # Manual filtering fallback - filter by checking timestamp in each transaction
-        if start or end:
-            filtered_transactions = []
-            for tx in transactions:
-                if start and tx.timestamp < start:
-                    continue
-                if end and tx.timestamp >= end:
-                    continue
-
-                filtered_transactions.append(tx)
-            logging.debug(
-                f"Filtered {len(filtered_transactions)} transactions for customer {customer_id} between {start} and {end}"
-            )
-            return filtered_transactions
-
         return transactions

[aalloiteau]

Hi @Charzander which version of Python SDK are you using ?

Is your ledger a v1 or v2 ? Note that v1 is going to reach EOL soon, we strongly recommend you to switch to ledger v2 if not already done.

cf https://github.com/orgs/formancehq/discussions/1966#discussioncomment-14948402

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.

If your filter has this format for v2 endopint, it should work

{
  "$and": [
    {
      "$match": { "destination": account_id }
    },
		{
      "$gt": { "timestamp": start.isoformat() }
    },
    {
      "$lt": { "timestamp": end.isoformat() }
    }
  ]
}