Postman collections ↗Bud Console ↗

Spending Budgets

Suggest Edits

What are Spending Budgets?

Spending Budgets are a way for customers to intelligently track their spending on certain categories or merchants in order to manage their money better and achieve their financial goals sooner.

Create a Spending Budget

The POST goals/v1/spending-budgets endpoint will create a spending budget for a customer.

A spending budget can be linked to a specific account_id or can be across all of a given customer's accounts. When creating a budget you must provide a name, amount and recurrency. Beyond these attributes, you also have the option to specify one or a number of categories both l1 and l2, and merchants. If you do not specify any categories or merchants the budget will ignore these when counting transactions within the budget.

An example of a request and a successful 201 response can be seen below.

{
  "operation_id": "goals_v1_spending_budgets_post",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Travel Budget",
    "amount": {
      "value": "300.00",
      "currency": "USD"
    },
    "recurrency": {
      "period": "monthly",
      "starting_day": 1
    },
    "include": {
      "categories": [
        {
          "l1": "travel"
        }
      ],
      "merchants": {
        "slugs": [
          "uber"
        ]
      }
    },
    "spent": {
      "from": "2023-10-01T00:00:00Z",
      "to": "2023-10-31T00:00:00Z",
      "amount": {
        "value": "160.59",
        "currency": "USD"
      },
      "ratio": "0.14"
    },
    "created_at": "2023-10-03T09:20:30Z",
    "_links": {
      "transactions": "/goals/v1/spending-budgets/f46d76c4-56d3-11ee-ac69-d6df71eb5902/transactions"
    }
  }
}

curl --request POST \
     --url https://api-sandbox.thisisbud.com/goals/v1/spending-budgets \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": {
    "value": "100.00",
    "currency": "USD"
  },
  "recurrency": {
    "period": "monthly",
    "starting_day": "1"
  },
  "include": {
    "merchants": {
      "slugs": [
        "netflix"
      ]
    },
    "categories": [
      {
        "l1": "travel"
      }
    ]
  },
  "name": "<budget>"
}
'

In the response, you will see an overview of the budget that has been created including an id, relevant categories, merchants, the recurrency, the budget amount and a link to any transactions that have already been calculated as part of the budget.

📘

Please note, all criteria included in a budget whether that is categories, merchants or a mixture of both will be applied as OR operators, meaning if you create a budget with the criteria categories: travel, merchants: spotify it will include transactions that have a category of travel OR a merchant of spotify.

If you receive a 400 response, please check the headers and body you're sending in the request before trying again.

Retrieve Spending Budgets

The GET goals/v1/spending-budgets endpoint retrieves all spending budgets for a given customer.

This endpoint can be filtered by account_id or date using the query parameters. An example of a 200 response can be seen below.

📘

Please note, the date parameter will allow you to specify the period of reference for the returned “spent” calculation. For example, if date=2023-02-10 and the monthly budget has from_day_of_month=25 the spent amount would be calculated between 2023-01-25 AND 2023-02-25 (the month that includes the date received in the filter). It isn't currently possible to return more than one month for a given budget.

{
  "operation_id": "goals_v1_spending_budgets_get",
  "data": [
    {
      "name": "Travel",
      "amount": {
        "value": "string",
        "currency": "string"
      },
      "recurrency": {
        "period": "string",
        "starting_day": "Unknown Type: int"
      },
      "account_id": "RxsYshVGded4JeilkXgWKdXA",
      "include": {
        "categories": [
          {
            "l1": "string",
            "l2": [
              "string"
            ]
          }
        ],
        "merchants": {
          "slugs": [
            "string"
          ]
        }
      },
      "id": "string",
      "spent": {
        "from": "string",
        "to": "string",
        "amount": {
          "value": "string",
          "currency": "string"
        },
        "ratio": "string"
      },
      "created_at": "string",
      "_links": {
        "transactions": "string"
      }
    }
  ],
  "metadata": {
    "results": 1,
    "account_id": "RxsYshVGded4JeilkXgWKdXA"
  }
}

curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/goals/v1/spending-budgets?account_id=RxsYshVGded4JeilkXgWKdXA&day=2019-02-29T12%3A23%3A00Z' \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The response will contain a list of the relevant budgets including information about the budget criteria, the spent amount and a link to view all transactions related to that particular budget.

Retrieve Spending Budget Transactions

If you would like to view the transactions related to a budget you can follow the link provided in response to GET goals/v1/spending-budgets or you can hit the endpoint directly via GET goals/v1/spending-budgets/{budget_id}/transactions.

{
  "operation_id": "goals_v1_spending_budget_transactions_get",
  "data": [
    {
      "transaction_id": "fbdc28e82f0f137586a526a88ec4a6be",
      "account_id": "RxsYshVGded4JeilkXgWKdXA",
      "provider": "BankOfBud",
      "description": "uber taxi",
      "credit_debit_indicator": "debit",
      "status": "booked",
      "amount": {
        "value": "16.39",
        "currency": "USD"
      },
      "date_time": "2023-10-03T10:00:00Z",
      "enrichments": {
        "categories": {
          "l1": {
            "slug": "transport",
            "confidence": "0.99"
          },
          "l2": {
            "slug": "taxi",
            "confidence": "0.99"
          }
        },
        "merchant": {
          "id": "9f345fcb-d1ee-4e79-a23e-510fb8dbd61f",
          "slug": "uber",
          "display_name": "Uber",
          "logo": "https://url/uber_logo.jpeg"
        }
      }
    }
  ]
}

curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/goals/v1/spending-budgets/81a68821-dca6-4771-80d4-002c7fce412e/transactions?day=2019-02-29T12%3A23%3A00Z' \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json'

The response will contain a list of all the relevant transactions in the same format as GET financial/v2/transactions, including transaction details such as description, amount, categories, regularity and merchant.

In the case that the customer doesn't have a budget with an id that matches the id provided, a 404 is returned.

Update an existing Spending Budget

The PATCH goals/v1/spending-budgets/{budget_id} endpoint is used to update an existing spending budget.

Any element of the budget such as account_id, name, amount,categoriesor merchants is available to be updated, you can do so by passing these values in the request body.

An example of a 200 response can be seen below.

{
  "operation_id": "goals_v1_spending_budgets_patch",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Travel Budget",
    "amount": {
      "value": "300.00",
      "currency": "USD"
    },
    "recurrency": {
      "period": "monthly",
      "starting_day": 1
    },
    "include": {
      "categories": [
        {
          "l1": "travel"
        }
      ],
      "merchants": {
        "slugs": [
          "uber"
        ]
      }
    },
    "spent": {
      "from": "2023-10-19",
      "to": "2023-10-31",
      "amount": {
        "value": "160.59",
        "currency": "USD"
      },
      "ratio": "0.54"
    },
    "created_at": "2023-10-03T09:20:30Z",
    "_links": {
      "transactions": "/goals/v1/spending-budgets/f46d76c4-56d3-11ee-ac69-d6df71eb5902/transactions"
    }
  }
}

    --url https://api-sandbox.thisisbud.com/goals/v1/spending-budgets/81a68821-dca6-4771-80d4-002c7fce412e \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": {
    "value": "10.98",
    "currency": "USD"
  },
  "recurrency": {
    "period": "monthly",
    "starting_day": "1"
  },
  "include": {
    "merchants": {
      "slugs": [
        "uber"
      ]
    },
    "categories": [
      {
        "l1": "travel"
      }
    ]
  },
  "name": "Travel",
  "account_id": "RxsYshVGded4JeilkXgWKdXA"
}
'

The response will contain an overview of the budget that has been updated including an id, relevant categories, merchants, the recurrency, the budget amount and a link to any transactions that have already been calculated as part of the updated budget.

In the case that the provided id does not exist, a 404 HTTP response will be given

If you receive a 400 response, please check the headers and body you're sending in the request before trying again.

Delete a Spending Budget

The DELETE goals/v1/spending-budgets endpoint will delete all spending budgets for a given customer.

If you would like to delete a specific budget you can do so by specifying an id in the URL of the endpoint such as DELETE goals/v1/spending-budgets/{budget_id}

This endpoint will return a 204 if the deletion has been successful.

In the case that the customer doesn't have a budget with an id that matches the id provided in the request, a 404 is returned.

If you receive a 400 response, please check the headers you're sending in the request before trying again.

Dealing with 401 and 500 responses

A 401 response from any of these endpoints would indicate that you are not authorised to make this request, if you believe this to be a mistake or are receiving persistent 500 responses please raise a support request.




If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.

Updated 10 days ago