Recurring Transactions API
Recurring transactions are a beta feature. How monetr detects them and what the object looks like are both subject to significant changes, so expect this page to move around a bunch before it settles down.
Once monetr has grouped your transactions into similar transaction clusters, it looks at each cluster and tries to work out whether it happens on a schedule. Your streaming service on the 12th every month, a paycheck every other Friday, car insurance once a year. When it finds a schedule that holds up, that's a recurring transaction.
A recurring transaction only ever goes one direction. Money going out and money coming in get looked at separately, so a cluster can have at most two of them, one for the charges and one for the refunds or deposits. Most only ever have one.
monetr wants at least three transactions before it'll call something recurring, and it has to be pretty sure about the schedule. Two charges a month apart is a coincidence as far as it's concerned.
Like the clusters, this all happens in a background job. It runs right after the clusters get recalculated, so a brand new transaction won't count toward anything until both jobs have gotten to it.
You can list every recurring transaction on a bank account, or start from a
transaction, each one has a transactionRecurringId pointing at the recurring
transaction it's part of.
You can link a recurring transaction to the thing in your budget that covers it. A charge going out gets linked to an expense, money coming in gets linked to a funding schedule, your paycheck for example. The link lives on the recurring transaction, so you set it with a PATCH here after you've created the expense or funding schedule.
A linked funding schedule comes back filled in as fundingSchedule, but a linked expense is only ever its
spendingId. If you need the expense itself, look it up by that ID.
Once a charge is linked to an expense you can also turn on autoAssign, and monetr will spend new charges from that
expense for you as they show up. More on how that works below the object table.
The recurring transaction object
The ruleset keeps its DTSTART in UTC like every other ruleset in monetr, but the schedule is really in your
account's timezone. If you want to pull dates out of it yourself, move DTSTART into your account's timezone first.
Skip that and something like BYMONTHDAY=8 lands on the 9th for anyone east of UTC.
ended and deleted aren't the same thing. Something that ended still exists, it just isn't happening anymore. If a
cluster stops recurring entirely, or the cluster itself goes away, the recurring transaction gets deleted. Its ID stops
working and the transactions that were in it go back to a null transactionRecurringId. Whatever expense or funding
schedule was linked to it sticks around, it just isn't linked to anything anymore.
Marking something as not recurring is different again. It gets deletedAt set but sticks
around, so its ID keeps working.
Recalculating doesn't touch the links. They stay put until you change them, or until you delete the expense or funding
schedule, which sets spendingId or fundingScheduleId back to null. Deleting the expense turns autoAssign off
too. The one exception is a debit that's still going and has no links at all. If two of its last three transactions
were spent from the same expense, and nothing else is linked to that expense yet, monetr links it for you and sets
autoMatched. It never turns on autoAssign for you though, that one's always your call.
With autoAssign on, any time the recalculation adds a new transaction to the recurring transaction, monetr spends it
from the linked expense. It's the same as picking the expense on the transaction yourself, so if the expense doesn't
have enough in it you get whatever's there. This happens in another background job right after the recalculation, so
give it a minute after new transactions show up.
It only looks at transactions as they get added, turning it on doesn't go back over the ones that are already part of the recurring transaction. And it leaves a few alone even then. Anything that's already spent from something stays how it is, and anything from before the day the expense was created gets skipped, since that charge was covered some other way. It's expenses only for now, funding schedules don't get this yet.
GET List recurring transactions
Returns every recurring transaction on a bank account, a page at a time. Ones that are still going come first, sorted by when the next one is expected, then the ones that have ended. You can narrow it down to one direction, or to just the ones that are still going or just the ones that ended, so you're not paging through stuff you don't care about.
Anything you've marked as not recurring is left out.
If you ask for just the ended ones with ended=true they're sorted by when they were last seen instead, most recent
first. next keeps getting worked out from the schedule even after something stops, so it doesn't say anything useful
about when it ended.
The name isn't on the recurring transaction itself, it's on the cluster. If you want something to show, look up the
cluster by its transactionClusterId.
In the app: The recurring page, under transactions in the sidebar.
Auth: API key, subscription required.
Path parameters
Query parameters
Example
Each item is a recurring transaction object. A bank account with no recurring transactions, or one that isn't yours, isn't an error. You just get back an empty array.
Errors
GET Get a recurring transaction
Returns one recurring transaction. You'll usually get the ID from a transaction's transactionRecurringId, or from
listing them.
This still works for one you've marked as not recurring, it'll just have deletedAt set.
In the app: Hovering the recurring icon next to a transaction, the recurring card on a transaction's details page, and the recurring transaction's own details page.
Auth: API key, subscription required.
Path parameters
Example
That one's a monthly charge on the 12th that went up from 15.49 partway through, which is why amounts has
two entries.
Errors
PATCH Link an expense or funding schedule
Links a recurring transaction to the expense or funding schedule that covers it, or clears that link. This is also
where you turn autoAssign on or off, and how you undo mark as not recurring. Those are the
only things you can change on a recurring transaction, everything else comes from monetr working it out.
A debit can only be linked to an expense, not a goal. A credit can only be linked to a funding schedule. For now an expense or funding schedule can only be linked to one recurring transaction at a time.
In the app: Picking or creating an expense or funding schedule on a recurring transaction's details page, the
recurring page, or the recurring card on a transaction's details page. When it's a new one the app creates it first and
then links it with this. Also the switch next to the expense on a recurring transaction's details page, which turns
autoAssign on and off.
Auth: API key, subscription required.
Path parameters
Body
Send whatever you're changing. Anything else in the body gets rejected.
Sending a different ID just moves the link over, you don't have to clear it first. Clearing spendingId turns
autoAssign off along with it, since there's nothing left to spend from. You can link an expense and turn on
autoAssign in the same request, like the example does.
Example
You get the recurring transaction back with the new link and updatedAt bumped to now. A funding schedule you linked
comes back filled in as fundingSchedule, an expense is just the spendingId.
History
deletedAtcan be sent as null to undo mark as not recurring.
Errors
DELETE Mark as not recurring
Tells monetr that something isn't actually recurring. It drops out of the list, its
link to an expense or funding schedule gets cleared along with autoAssign, and monetr won't link an expense to it for
you anymore. You can undo it by updating it with deletedAt set to null, but
the link and autoAssign don't come back with it.
It doesn't really go away though. monetr keeps it around with deletedAt set so it remembers you said no, otherwise the
next recalculation would just find the same schedule and bring it right back. You can still
get it by its ID, and its transactions still point at it with transactionRecurringId,
so check deletedAt if you're following that ID from a transaction.
The one way it can come back is if the cluster stops recurring entirely. Then it gets deleted for real like anything else, and if the cluster starts recurring again later you'll get a brand new one.
In the app: The Not Recurring button on a recurring transaction's details page, or on the recurring card on a transaction's details page.
Auth: API key, subscription required.
Path parameters
Example
Returns 200 with an empty body.