Keep your budgets flexible with configurable budget periods

TL;DR – Automation makes managing budgets easier and the Budget API now supports configurable budget time periods for even more flexibility!

Even though we just walked through some of the basics of using the Budget API, there’s a new feature that’s worth checking out: the ability to set custom time periods on budgets. Here’s a refresher on how budgets work if you’d like one. By default, budgets work on a monthly basis, so they reset on the first of each month. This is pretty convenient for most use cases, but might not work for you if your finances work on different periods. Regardless of what your timing needs are, let’s look at two new ways to work with your budgets!

Calendar periods

With this new update, you can change the general time period that a budget looks at. There are three options here:

• Monthly: the default for budgets, starting on the first day of each month and ending on the last day of each month (January 1st through January 31st, for example)
• Quarterly: an even split of the year into four quarters starting on January 1st, April 1st, July 1st, and October 1st
• Yearly: the whole year, starting with January 1st

Since budgets are typically repeated, these new options give you additional options for what the time period should look like. Each budget has its own period that it covers, so you can mix budgets of different time periods together for more customizable reporting!

These time periods also affect the budget amounts (more info under the Amount section here) if you’re using the dynamic “last period’s spend” rather than a fixed amount. So, if you’re working with a quarterly budget and it’s currently Q2 (April 1 – June 30th), the last period’s spend amount would be based on Q1 (January 1st – March 31st). This works the same way for yearly budgets, so you can easily track your spending year over year. Let’s see what this looks like using the API!

Here’s our new function for creating a budget (and here’s a link to the documentation if you want to see more information about the different properties):

Adding a calendar period is pretty straightforward, since it’s just passing an ENUM into the budget filter. Here’s the part where the filter is set:

and

Now we can pass in budgets.CalendarPeriod.MONTH (or .YEAR or .QUARTER) in order to set the calendar period for this budget. We’ve also updated the function that lists budgets to include more information about the budget, so if we create a new budget and list it:

The output will look like this:

Custom periods

Picking the calendar periods is great, but what if you need something a bit more custom? For example, maybe you want to set a budget for that ever-popular holiday season, or for a week where you’re rolling out a new product? Custom periods (as the name might imply) can help you with those by giving you the option to set custom start and end dates. So if you’re rolling out that new product on August 18th, you could create a budget with a start date of 2021-08-15 and an end date of 2021-08-25 (or whatever else you want) to track spending during just that period. Combined with all the other filters, there’s quite a bit of granularity!

These custom period budgets work a bit differently than the typical calendar period budgets, though:

• Custom period budgets do not repeat. These budgets are only useful for the time period specified so you’ll have to create multiple budgets to cover each of the time periods you want to know more about

• Since they don’t repeat, you can’t use the “last period’s spend” setting for amount, which makes sense because there’s no last period!

• The start date must be after January 1st 2017. I’m not really sure who this would affect but now you know

• And the end date is actually optional. If you don’t provide one, the budget will track all the usage after the start date with no end in sight

With all of that out of the way, let’s look at how to actually create these custom period budgets! The same create_budget function works, and here’s the part that actually sets the start and end dates:

Since a budget can’t have a calendar period and a custom period, this will create the budget with one or the other and pass in the properties through the budget filter. So when we run the code:

The output will be:

One more thing

It’s worth noting that any budgets created with a custom time period won’t show up in the UI. For now, these budgets will have to be managed through the API only. This code should hopefully help you get started with managing them and getting ready for when they’ll be available in the console at some point in the near future^TM. Also here’s the updated list_budget code:

In the meantime, you can check out the client library and the documentation for more details. Happy budgeting!