> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ntropy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ntropy.com/_mcp/server.

# 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 supports three types:)

[//]: # (- Recurring: a transaction that repeats regularly with dynamic pricing, e.g. utilities, mortgage.)

[//]: # (- Subscription: a transaction that repeats regularly with *fixed* pricing, e.g. spotify subscription.)

[//]: # (- One-Off: not a recurrent transaction)

# 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`**

```python title="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"
)
```


<Accordion title='See the full raw output'>
```json
[
    {
        "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"
    }
]
```
</Accordion>

-------------------------------------------