Budgeting

A budget in PocketSmith is formed by the placement of budget events on the forecast calendar. For example, setting up an event for the Food category that repeats every week will form a weekly budget. However, placement of events can be arbitrary -- they could be a mixture of one off, yearly, and quarterly events for a single category.

The budget reporting API serves one core purpose: to report, in a variety of different ways, the actual spending and earning versus forecasted (budgeted) earning and spending.

The endpoints available closely follow the functionality available in the PocketSmith web application.

Data modelling

At the core of the data you'll be working with is the budget analysis. A budget analysis will either be analysing income, or analysing expense. These are wrapped in a budget analysis package, which provides an income analysis or an expense analysis, or both where applicable.

Here's what a simple, noncontextual budget analysis package might look like:

{
  "income": null,
  "expense": {
    "start_date": "2016-11-01",
    "end_date": "2016-11-30",
    "total_actual_amount": -20.0,
    "average_actual_amount": -20.0,
    "total_forecast_amount": 0,
    "average_forecast_amount": 0.0,
    "total_under_by": 0,
    "total_over_by": 0,
    "periods": [
      {
        "start_date": "2016-11-01",
        "end_date": "2016-11-30",
        "actual_amount": -20.0,
        "forecast_amount": 0,
        "refund_amount": 0,
        "current": true,
        "over_budget": false,
        "under_budget": true,
        "over_by": 0,
        "under_by": 0,
        "percentage_used": 0
      }
    ]
  }
}

This is termed a noncontextual analysis package because there is just an income and expense analysis provided. In other cases, a contextual package will be provided, which includes a category key (to inform the consumer the single category being analysed to produce the analyses) and an is_transfer key (to inform the consumer whether or not the expense and income analyses look like transfers between each other).

In this case, in the date range and period being analysed, the user has budgeted $0 of spending, and actually spent $20. The user hasn't received any income and hasn't budgeted for any income, therefore no income analysis is generated.

Note that amounts are signed; when you're dealing with an expense analysis, you'll have negative amounts for both actual and forecast figures. For income analyses, you'll have positive numbers.

In a budget analysis, periods is an array of period analyses. In the example above, it so happens that the budget analysis only contains one period, but it could be several. Periods are formed by splitting up the date range provided using the requested period. For example, if you analyse with a date range of 2016-10-01 to 2016-11-30, and with a period of months with interval 1, you'll end up with two period analyses -- one for 2016-10-01 through 2016-10-31 and 2016-11-01 through 2016-11-30. This would let you compare budget trends month to month.

Period types

The period defines how the budget analysis should be split up across the date range.

Time period analysis

Time period analysis will split the date range up over a time period, e.g. 2 weeks for every fortnight. The forecast (budget) events that happen to fall in that date range, as well as the actuals (transactions) that fall in that range will be included.

Event period analysis

Event period analysis is a special case, where the budget events themselves form the period. This is what the user intends when they set up a repeating budget in PocketSmith. If a weekly repeating budget is set to start on 2016-09-01, and the budget is requested to be analysed from 2016-09-01 to 2016-09-30, the following periods would form:

1. 2016-09-01 - 2016-09-07
2. 2016-09-08 - 2016-09-14
3. 2016-09-15 - 2016-09-21
4. 2016-09-22 - 2016-09-28
5. 2016-09-29 - 2016-10-05

Note how the end date has been pushed out to accomodate full periods.

It's always good when we can do event period analysis in simple cases (like the user's current budget), however when the analysis gets more complex and, in particular, when more than one category is involved, it might not make sense for us to do event period analysis.

• the user might have added multiple sets of budget events for the category, in which case the events might not form a clear repeating event sequence
• multiple categories are included in a single analysis, where different repeating events are being considered together, meaning it's unlikely we'll find an overall clear repeating sequence of events. However, if all event sequences were e.g. weekly and repeated on the same dates, we'd happily do event period analysis.

For example, if a fortnightly repeating budget set to start on 2016-09-02 is set up in the same category mixed in with the existing weekly budget, the periods would be strange and not very useful:

• 2016-09-01 - 2016-09-01 [just one day, because the next event (the start of the fortnightly sequence) starts on the 2nd]
• 2016-09-02 - 2016-09-07 [between the first fortnightly event and the second weekly event]
• 2016-09-08 - 2016-09-14 [between the second weekly event and the third weekly event]
• 2016-09-15 - 2016-09-15 [just one day, because the second fortnightly event starts on the 16th]
• 2016-09-16 - 2016-09-21 [between the second fortnightly event and the fourth weekly event]

and so on. Clearly event period analysis in this case makes little sense, so we head it off by rejecting the request for event period analysis and offering the next best time period analysis. In this case, we'd suggest 1 months as a good time period analysis.

Endpoints

There are three endpoints available for budgeting that serve unique purposes.

Listing the user's budget

The user's budget is all of their budgeted categories analysed currently in the event period. This shows the progress the user is making at the moment toward each of their forecasted amounts. Since the budget is being analysed currently, there'll only be one period analysis -- the current period.

You'll get an array of budget analysis packages. These will be contextual packages, so you can see what category was analysed to produce the analyses, and also whether or not the analyses look like a transfer.

To see the user's rolled up budget (budget on subcategories combined into the parent category's analyses), you can specify roll_up=1 as a query parameter. The children will still be analysed in their own right, but categories that do have budgeted child categories will have those combined into its analyses.

In cases where event period analysis is not possible, we will automatically fall back to the next best time period alternative. This will be some number of weeks, months or years with an interval that best matches the event period. For example, if there was a weekly repeating event mixed in with a monthly repeating event, the time period analysis alternative would be 1 months, as it's the smallest time period that makes sense to report on. Doing event period analysis in this case would cause some nonsensical results. It's therefore gauranteed there will be some kind of analysis available for any category that has a current budget.

Get the user's budget summary

The budget summary is simply a shortcut for analysing all the user's categories for a certain time period. This is shown in both the PocketSmith web and mobile apps above the budget listing, representing your expense (vs your income) actuals vs forecasted.

The budget summary endpoint will respond with a noncontextual analysis package.

Whilst you can attempt event period analysis, it will likely be rejected with a time period alternative since all categories are being analysed together, meaning wildly different events are in the mix.

Get a trend analysis

A trend analysis is essentially a raw query to the budgeting system. You simply request the analysis with all the categories you want analysed, across which scenarios, between which dates and in what period. The result will be a noncontextual analysis package with the results.

You'll very likely want to include all scenarios in your analysis. You'll only want a subset if you specifically want to ignore budget events on certain scenarios. You can obtain all scenarios by iterating over the user's accounts and collecting all the items in the scenarios array for each.

Handling a time period alternative

If you attempt event period analysis on the trends endpoint, and it's not possible, you'll be rejected with a 422 Unprocessable Entity status. In the response headers, you'll find X-Suggested-Time-Period-Alternative-Type and X-Suggested-Time-Period-Alternative-Interval. The type will be e.g. weeks, months and the interval will be an integer.

You should make the request again, and use the suggested period type and interval instead.