Skip to navigation
Transaction Enrichment

Recurrence

Understanding recurrence in financial transactions is crucial for categorizing and predicting future cash flows. The Recurrence API allows you to identify and categorize recurring patterns found in the transactions of an account holder, such as periodic payments or subscriptions. These patterns are classified into a recurrence type and a recurrence group that encodes detailed information about its periodicity, transaction counterparty and amount metrics.

Understanding recurrence

We identify recurring patterns from transaction dates, counterparty identity, and amount behavior. Transactions can be grouped across gaps, so a monthly subscription can still be recognized when a payment is missing. When the available details could refer to multiple counterparties or patterns, we leave the transactions ungrouped rather than force a match.

Recurrence groups

A recurrence group is a grouping of transactions with the same recurring pattern. Every transaction in a recurring pattern shares the same counterparty, but not necessarily amounts. This means that:

  • We might have transactions with different amounts in the same recurring group.
  • There could be multiple recurrence groups per counterparty/general category.
  • We could have non-recurrent transactions with a counterparty (e.g Amazon Web Services) even if there’s already transactions with the same counterparty belonging to a group.

Supported periodicities are daily, weekly, bi-weekly, semi-monthly (twice per calendar month), monthly, bi-monthly, quarterly, semi-yearly, yearly, and other.

Example usage

SDK
from ntropy_sdk import SDK
sdk = SDK("cd1H...Wmhl")
for i in range(1,5):
    sdk.transactions.create(
        id=f"netflix-{i}",
        description=f"Recurring Debit Purchase Card 1350 #{i} netflix.com Netflix.com CA",
        amount=17.99,
        currency="USD",
        entry_type="outgoing",
        date=f"2021-0{i}-01",
        account_holder_id="35b927b6-6fda-40aa-93b8-95b47c2b2cad",
    )
    
    sdk.transactions.create(
        id=f"netflix-{i}",
        description=f"Payment #{i} from netflix.com Netflix.com CA",
        amount=1000,
        currency="USD",
        entry_type="incoming",
        date=f"2021-0{i}-01",
        account_holder_id="35b927b6-6fda-40aa-93b8-95b47c2b2cad",
    )
recurring_groups = sdk.account_holders.recurring_groups(
    "35b927b6-6fda-40aa-93b8-95b47c2b2cad"
)
[
    {
        "id": "5a38529e-2df2-3e34-ac4d-98dcd294b781",
        "start_date": "2024-01-20",
        "end_date": "2024-04-20",
        "total_amount": 4000.0,
        "average_amount": 1000.0,
        "periodicity_in_days": 31.0,
        "periodicity": "monthly",
        "counterparty": {
            "id": "dc425051-df94-3509-9103-cf8c0f0bcf6a",
            "name": "Netflix",
            "website": "netflix.com",
            "logo": "https://logos.ntropy.com/netflix.com",
            "mccs": [],
            "type": "organization"
        },
        "categories": {
            "general": "entertainment - television - subscriptions", 
        },
        "transaction_ids": [
            "sub-4",
            "sub-3",
            "sub-2",
            "sub-1"
        ],
        "entry_type": "outgoing"
    },
    {
        "id": "7e529088-cc5b-3eed-8050-b98034bc5184",
        "start_date": "2024-01-20",
        "end_date": "2024-04-20",
        "total_amount": 4000.0,
        "average_amount": 1000.0,
        "periodicity_in_days": 31.0,
        "periodicity": "monthly",
        "counterparty": {
            "id": "dc425051-df94-3509-9103-cf8c0f0bcf6a",
            "name": "Netflix",
            "website": "netflix.com",
            "logo": "https://logos.ntropy.com/netflix.com",
            "mccs": [],
            "type": "organization"
        },
        "categories": {
            "general": "income - paycheck",
        },
        "transaction_ids": [
            "sal-4",
            "sal-3",
            "sal-2",
            "sal-1"
        ],
        "entry_type": "incoming"
    }
]