Skip to main content
This guide explains key terminology when using our Spending Plan API. It also gives a user workflow example using our Spending Plan Widget. The guide assumes you’re creating a widget like our Spending Plan Widget, but is helpful even if you’re creating something unique. Using the API, you can perform basic CRUD (create, read, update, delete) operations to build your own custom UI based on the following data:
  • A user’s spending plan
  • A user’s spending plan iterations
  • A user’s spending plan iteration items
  • A user’s spending plan accounts
Next, we’ll cover those terms.

​
API Terminology

These sections give context to the unique terminology used in the API. To summarize, a spending_plan contains iterations, which each represent a month. Each iteration contains iteration_items relevant to the month of the iteration. A spending_plan also contains spending_plan_accounts, which represent the user’s spending accounts. The transactions within these accounts will help populate the data used in the iteration_items.

​
Spending Plan

A spending_plan represents a plan to help end users better manage and understand their spending. A spending_plan object holds all info relevant to the plan, such as its iterations, iteration items, and spending plan accounts.

​
Iterations

An iteration contains the spending plan data for one month. Creating a spending_plan automatically creates an iteration. An iteration always starts on the first day of the month and ends on the last day of the month. For example, an iteration for May would start on May 1st and end on May 31st. On June 1st, a new iteration would automatically be created for the user.

​
Iteration Items

In our API, an iteration_item can represent one of the following:
  • INCOME – Represents the user’s income.
  • OTHER_EXPENSE – Represents spending unrelated to budgets or recurring expenses.
  • PLANNED_EXPENSE – Represents budgets the user has planned for.
  • RECURRING_EXPENSE – Represents recurring expenses, such as bills or subscriptions.
You’ll need to create these for each user. This is the data that populates the UI.

​
Spending Plan Accounts

A spending_plan_account is an account that’s associated with a spending_plan. This lets users specify which spending accounts they want the widget to use.

​
Example UI: MX’s Spending Plan Widget

The Spending Plan Widget helps users track their income and expenses each month. It shows the user:
  • An overview of their monthly income and spending.
  • How much money they have left to spend that month.
  • Other details about their spending, such as recurring expenses, budgets, and any other spending that isn’t recurring or included in their budgets.
For more info about how our widget works, see Spending Plan Widget Overview.

​
User Workflow

This describes the user workflow if you’re building something like our Spending Plan Widget. You can reference this when building your own widget.
  1. User loads the widget for the first time. You create a spending_plan, which automatically creates an iteration.
  2. Onboarding screen is presented.
    • User sets their projected income. You create an iteration_item with item_type set to INCOME.
    • User chooses their spending accounts from a list of their connected accounts. You create a spending_plan_account for every account the user selected, based on the account_guid of the selected account.
    • For the spending accounts the user chose, you create an iteration_item for any RECURRING_EXPENSEs or OTHER_EXPENSEs (this type of expense represents spending that isn’t recurring or included in the user’s budgets).
  3. User has completed onboarding and can make the following actions, which will require you to create, update, or display the data in the iteration_items for each action:
    • Automatically create a monthly budget based on their prior spending habits.
    • Manually create a new monthly budget or manage an existing one.
    • View recurring expenses, manage the details of a recurring expense, or remove an expense entirely.
    • See any other spending from the accounts they selected.
    • Edit their income.
    • Edit which of their accounts are used for spending.
    • See their spending plans from previous months.
    • See transactions associated with categories they haven’t created budgets for, then add those budgets to their spending plan.
We recommend you use Webhooks to notify you when a spending_plan is created, deleted, or updated.