Recurring Transactions API

Beta

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

AttributeTypeDescription
transactionRecurringIdstring (ulid)Identifies the recurring transaction. It stays the same between recalculations as long as the cluster keeps recurring in the same direction.
bankAccountIdstring (ulid)The bank account it belongs to.
transactionClusterIdstring (ulid)The similar transactions cluster it was found in.
spendingIdstring (ulid), nullableThe expense tracking this, if you've linked one. Only ever set on debits. See Link an expense or funding schedule.
fundingScheduleIdstring (ulid), nullableThe funding schedule tracking this, if you've linked one. Only ever set on credits.
fundingScheduleobjectThe funding schedule in fundingScheduleId, if there is one. Left out otherwise.
windowstringRoughly how often it happens. One of weekly, biweekly, firstAndFifteenth, fifteenthAndLast, monthly, bimonthly, quarterly or yearly. biweekly is every two weeks, bimonthly every two months.
rulesetstringThe actual schedule, as a recurrence rule. The days in it are your account's days, see the note below the table.
firsttimestampThe earliest transaction that's part of it. If something stopped for a long stretch and then started up again, this is from when it started back up.
lasttimestampThe most recent transaction that's part of it.
nexttimestampWhen monetr expects the next one, as of the last recalculation. Nothing updates it in between, so if the job hasn't run in a while this can already be in the past.
endedbooleanTrue once it's gone too long without a new transaction. monetr gives it half a period of slack past when the next one was due, and never less than 3 days, since charges like to wander around a bit.
confidencenumberHow sure monetr is about the schedule, between 0.6 and 1. Anything under 0.6 doesn't get to be a recurring transaction at all.
directionstringdebit for money leaving the account, credit for money coming in. Same as the sign on the transactions, debits are positive amounts and credits are negative.
amountsobjectHow many times each amount showed up. Keys are amounts in the currency's smallest unit, as strings since it's JSON, and values are counts. Handy for spotting a price change.
lastAmountintegerThe amount of the most recent transaction, in the currency's smallest unit. Usually your best guess for what the next one will be. See Currencies.
autoMatchedbooleanTrue when monetr linked the expense for you, because you kept spending its recent transactions from that expense. Goes back to false as soon as you change the link yourself.
autoAssignbooleanTrue when monetr spends new charges from the linked expense for you. Can only be on while an expense is linked, so it's always false on credits.
createdAttimestampWhen monetr first decided it was recurring.
updatedAttimestampWhen it was last recalculated or linked. This changes on every recalculation, even when nothing about it did, so don't use it to spot changes.
deletedAttimestamp, nullableWhen you marked it as not recurring. Null on everything else.

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.

GET /api/bank_accounts/:bankAccountId/recurring

Auth: API key, subscription required.

Path parameters

AttributeTypeRequiredDescription
bankAccountIdstring (ulid)YesThe bank account whose recurring transactions you want.

Query parameters

AttributeTypeRequiredDescription
limitintegerNoHow many to return. Defaults to 25. Has to be between 1 and 100, or a 400.
offsetintegerNoHow many to skip first. Defaults to 0. Negative is a 400.
directionstringNodebit or credit, to only get the ones going that way. Leave it off to get both. Anything else is a 400.
endedbooleanNofalse for just the ones that are still going, true for just the ones that ended. Leave it off to get both. Has to be true or false, or a 400.

Example

curl --request GET \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/recurring?direction=debit&ended=false&limit=1" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET"
[
  {
    "transactionRecurringId": "txrc_01j6b4n8w2kq5t9r3xm7vdc6ph",
    "bankAccountId": "bac_01gds6eqsq7h5mgevwtmw3cyxb",
    "transactionClusterId": "tcl_01j6b4m3zr8yq2w6tnc5kxd9fe",
    "spendingId": "spnd_01j6b5q2h8ycz4n7w3tkr9vx5d",
    "fundingScheduleId": null,
    "window": "monthly",
    "ruleset": "DTSTART:20240301T060000Z\nRRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=12",
    "first": "2024-03-12T05:00:00Z",
    "last": "2024-08-12T05:00:00Z",
    "next": "2024-09-12T05:00:00Z",
    "ended": false,
    "confidence": 0.94,
    "direction": "debit",
    "amounts": {
      "1399": 3,
      "1549": 3
    },
    "lastAmount": 1549,
    "autoMatched": false,
    "autoAssign": false,
    "createdAt": "2024-05-13T03:15:06.214Z",
    "updatedAt": "2024-08-30T14:02:11.733Z",
    "deletedAt": null
  }
]

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

StatusWhen
400limit is outside 1 to 100, offset is negative, direction isn't debit or credit, ended isn't true or false, or the bank account ID is bad.

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.

GET /api/bank_accounts/:bankAccountId/recurring/:transactionRecurringId

Auth: API key, subscription required.

Path parameters

AttributeTypeRequiredDescription
bankAccountIdstring (ulid)YesThe bank account the recurring transaction belongs to.
transactionRecurringIdstring (ulid)YesThe recurring transaction you want.

Example

curl --request GET \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/recurring/txrc_01j6b4n8w2kq5t9r3xm7vdc6ph" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET"
{
  "transactionRecurringId": "txrc_01j6b4n8w2kq5t9r3xm7vdc6ph",
  "bankAccountId": "bac_01gds6eqsq7h5mgevwtmw3cyxb",
  "transactionClusterId": "tcl_01j6b4m3zr8yq2w6tnc5kxd9fe",
  "spendingId": null,
  "fundingScheduleId": null,
  "window": "monthly",
  "ruleset": "DTSTART:20240301T060000Z\nRRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=12",
  "first": "2024-03-12T05:00:00Z",
  "last": "2024-08-12T05:00:00Z",
  "next": "2024-09-12T05:00:00Z",
  "ended": false,
  "confidence": 0.94,
  "direction": "debit",
  "amounts": {
    "1399": 3,
    "1549": 3
  },
  "lastAmount": 1549,
  "autoMatched": false,
  "autoAssign": false,
  "createdAt": "2024-05-13T03:15:06.214Z",
  "updatedAt": "2024-08-30T03:15:05.902Z",
  "deletedAt": null
}

That one's a monthly charge on the 12th that went up from 13.99to13.99 to 15.49 partway through, which is why amounts has two entries.

Errors

StatusWhen
400Either ID is malformed.
404No recurring transaction with that ID on that bank account.

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.

PATCH /api/bank_accounts/:bankAccountId/recurring/:transactionRecurringId

Auth: API key, subscription required.

Path parameters

AttributeTypeRequiredDescription
bankAccountIdstring (ulid)YesThe bank account the recurring transaction belongs to.
transactionRecurringIdstring (ulid)YesThe recurring transaction you're linking.

Body

Send whatever you're changing. Anything else in the body gets rejected.

AttributeTypeRequiredDescription
autoAssignbooleanNoSpend new charges from the linked expense for you. Needs an expense linked, so debits only.
deletedAtnullNoSend null to undo mark as not recurring. Anything else is rejected.
fundingScheduleIdstring (ulid), nullableNoThe funding schedule to link, on the same bank account. Credits only. Send null to clear it.
spendingIdstring (ulid), nullableNoThe expense to link, on the same bank account. Debits only. Send null to clear it.

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

curl --request PATCH \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/recurring/txrc_01j6b4n8w2kq5t9r3xm7vdc6ph" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET" \
  --header "Content-Type: application/json" \
  --data '{
    "spendingId": "spnd_01j6b5q2h8ycz4n7w3tkr9vx5d",
    "autoAssign": true
  }'
{
  "transactionRecurringId": "txrc_01j6b4n8w2kq5t9r3xm7vdc6ph",
  "bankAccountId": "bac_01gds6eqsq7h5mgevwtmw3cyxb",
  "transactionClusterId": "tcl_01j6b4m3zr8yq2w6tnc5kxd9fe",
  "spendingId": "spnd_01j6b5q2h8ycz4n7w3tkr9vx5d",
  "fundingScheduleId": null,
  "window": "monthly",
  "ruleset": "DTSTART:20240301T060000Z\nRRULE:FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=12",
  "first": "2024-03-12T05:00:00Z",
  "last": "2024-08-12T05:00:00Z",
  "next": "2024-09-12T05:00:00Z",
  "ended": false,
  "confidence": 0.94,
  "direction": "debit",
  "amounts": {
    "1399": 3,
    "1549": 3
  },
  "lastAmount": 1549,
  "autoMatched": false,
  "autoAssign": true,
  "createdAt": "2024-05-13T03:15:06.214Z",
  "updatedAt": "2024-08-30T14:02:11.733Z",
  "deletedAt": null
}

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

v1.22.0

  • deletedAt can be sent as null to undo mark as not recurring.

Errors

StatusWhen
400Either ID is malformed, the body has something other than spendingId, fundingScheduleId, autoAssign or deletedAt, you sent deletedAt as anything but null, you linked an expense to a credit or a funding schedule to a debit, you linked a goal, that expense or funding schedule is already linked to a different recurring transaction, or you turned on autoAssign without an expense linked or on a credit.
404No recurring transaction with that ID on that bank account, or the expense or funding schedule you sent doesn't exist on that bank account.

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.

DELETE /api/bank_accounts/:bankAccountId/recurring/:transactionRecurringId

Auth: API key, subscription required.

Path parameters

AttributeTypeRequiredDescription
bankAccountIdstring (ulid)YesThe bank account the recurring transaction belongs to.
transactionRecurringIdstring (ulid)YesThe recurring transaction that isn't recurring.

Example

curl --request DELETE \
  --url "https://my.monetr.local/api/bank_accounts/bac_01gds6eqsq7h5mgevwtmw3cyxb/recurring/txrc_01j6b4n8w2kq5t9r3xm7vdc6ph" \
  --user "$MONETR_API_KEY_ID:$MONETR_API_KEY_SECRET"

Returns 200 with an empty body.

Errors

StatusWhen
400Either ID is malformed, or it's already been marked as not recurring.
404No recurring transaction with that ID on that bank account.